diff --git a/.custodian-brief.md b/.custodian-brief.md index 927216c..58b24ec 100644 --- a/.custodian-brief.md +++ b/.custodian-brief.md @@ -8,14 +8,18 @@ ## Open Workplans -### Bootstrap State Hub integration +### Agent security knowledge and NetKingdom integration -Workplan file: `workplans/EMERGENT-WP-0001-statehub-bootstrap.md` +Workplan file: `workplans/EMERGENT-WP-0002-agent-security-knowledge-and-netkingdom-integration.md` Open tasks: -- T01 - Review generated integration files -- T02 - Verify local developer workflow -- T03 - Seed first real workplan +- T01–T02 - Verify authoritative sources and reconcile doctrine/owner boundaries +- T03–T05 - Package, retrieve, and load shared knowledge in agent sessions +- T06–T07 - Map operational interfaces and evaluate situational understanding +- T08–T10 - Pilot, roll out, verify adoption, and hand off remaining owner work + +Status: ready. All ten implementation tasks are todo; this session created the +plan, not the knowledge distribution. Start with T01. EMERGENT-WP-0001 is finished. ## Session Start diff --git a/SCOPE.md b/SCOPE.md index 7d2a801..41d3dee 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,7 +1,8 @@ # SCOPE -> This file was generated by `statehub register`. Refine it as the repository -> boundaries become clearer. +> Repository boundary reviewed 2026-10-03. See `INTENT.md` for purpose and +> `workplans/EMERGENT-WP-0002-agent-security-knowledge-and-netkingdom-integration.md` +> for the planned ecosystem integration. ## One-liner @@ -9,21 +10,29 @@ Security governance canon, policy envelopes, and deterministic reference decisio ## Core Idea -emergent-security exists to provide the capability described in INTENT.md. +Delegate understood decisions within explicit envelopes, escalate unresolved +decisions without widening privilege, and keep root human-controlled. ## In Scope -- Maintain the repository's primary implementation. -- Keep docs, tests, and operational metadata current. +- Maintain the versioned canon, agent extract, YAML envelopes and risk scales. +- Maintain the pure Python reference evaluator and decision/governance fixtures. +- Develop source-backed agent knowledge and explicit mappings to existing + NetKingdom owners under EMERGENT-WP-0002. ## Out of Scope -- Own unrelated adjacent systems. -- Make irreversible operational decisions without human approval. +- Operate a second estate authorization decision point or credential broker. +- Take over another repository's canon, operational routes, or enforcement. +- Treat reference decisions or knowledge loading as operational authority. ## Current State -- Status: active; implementation and stability should be verified by the repo agent. +- Canon and reference package: v0.8; Python 3.11+, PyYAML, pytest. +- Verification: `python3 -m pytest -q` passed 288 tests on 2026-10-03. +- No running service, credential issuer, runtime enforcement, or agent knowledge + distribution is implemented here. Ecosystem compatibility conflicts and + provider rollout are tracked in EMERGENT-WP-0002. ## Getting Oriented diff --git a/workplans/EMERGENT-WP-0001-statehub-bootstrap.md b/workplans/EMERGENT-WP-0001-statehub-bootstrap.md index e687ba9..3e3ac62 100644 --- a/workplans/EMERGENT-WP-0001-statehub-bootstrap.md +++ b/workplans/EMERGENT-WP-0001-statehub-bootstrap.md @@ -4,7 +4,7 @@ type: workplan title: "Bootstrap State Hub integration" domain: communication repo: emergent-security -status: ready +status: finished owner: codex topic_slug: netkingdom created: "2026-10-03" @@ -20,7 +20,7 @@ Security governance canon, policy envelopes, and deterministic reference decisio ```task id: EMERGENT-WP-0001-T01 -status: todo +status: done priority: high state_hub_task_id: "eced19df-b6d3-549f-a825-5db2c9eb672f" ``` @@ -28,11 +28,16 @@ state_hub_task_id: "eced19df-b6d3-549f-a825-5db2c9eb672f" Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`. Replace generated placeholders with repo-specific facts where needed. +Completed 2026-10-03: distilled INTENT.md from canon, implementation and tests; +reviewed generated files; removed the unresolved credential-routing template +token; made SCOPE.md describe the shipped reference library and planned +integration. Registration was verified under communication / netkingdom. + ## Verify Local Developer Workflow ```task id: EMERGENT-WP-0001-T02 -status: todo +status: done priority: high state_hub_task_id: "b6272578-87ab-549a-8ba4-b69fc16e89e7" ``` @@ -41,11 +46,16 @@ Identify the repo's install, test, lint, build, and run commands. Add or refine those commands in the agent instructions so future coding sessions can verify changes confidently. +Completed 2026-10-03: AGENTS.md records Python 3.11+, installation with +`pip install -e '.[test]'`, `python3 -m pytest -q`, and the policy-first fixture +workflow. Existing suite: 288 passed. No dedicated lint command or running +service exists in this repository. + ## Seed First Real Workplan ```task id: EMERGENT-WP-0001-T03 -status: todo +status: done priority: medium state_hub_task_id: "de1098cd-9cba-54b8-9c55-8246b7c25e41" ``` @@ -55,5 +65,18 @@ next change. After workplan file updates, run the sync locally from this repo checkout: ```bash -statehub fix-consistency +uv run --project ~/repo-manager rmgr sync --path . --push ``` + +Completed 2026-10-03: EMERGENT-WP-0002 defines ten dependent tasks for agent +security knowledge and integration with the existing NetKingdom ecosystem. +It owns all follow-up doctrine reconciliation, provider adapters, engine/route +mappings, evaluation, pilots, and rollout work; no implementation is claimed here. + +## Completion evidence + +DoD-Ok — 2026-10-03: repository intent and boundaries reviewed; developer +workflow verified; registration and initial primary projection applied at +`22ae440c541ac7a055497e88eb279fadf268e952`; follow-up work is live in +EMERGENT-WP-0002. Final status and the new plan are published together through +Repo Manager sync. There are no remaining bootstrap tasks. diff --git a/workplans/EMERGENT-WP-0002-agent-security-knowledge-and-netkingdom-integration.md b/workplans/EMERGENT-WP-0002-agent-security-knowledge-and-netkingdom-integration.md new file mode 100644 index 0000000..0da3e07 --- /dev/null +++ b/workplans/EMERGENT-WP-0002-agent-security-knowledge-and-netkingdom-integration.md @@ -0,0 +1,353 @@ +--- +id: EMERGENT-WP-0002 +type: workplan +title: "Agent security knowledge and NetKingdom integration" +domain: communication +repo: emergent-security +status: ready +owner: codex +topic_slug: netkingdom +created: "2026-10-03" +updated: "2026-10-03" +--- + +# Agent security knowledge and NetKingdom integration + +Make every coding agent operating in the NetKingdom-governed estate able to +establish where it is, which security boundaries apply, which component owns a +decision or operation, which route is actually available, and what evidence is +needed before acting. Codex, Claude, Grok, and future agents should receive the +same authoritative security knowledge through their supported entry points. + +Emergent Security supplies the delegation and escalation model and its tested +reference semantics. Integrate that model with the existing estate's doctrine, +canon, engines, operational routes, and agent harnesses. Knowledge delivery must +not establish a second authorization system or imply capabilities that are only +aspirational, offline, blocked, or covered by a temporary exception. + +## Scope and completion contract + +Deliver a versioned, tool-neutral knowledge package; an owner/source and +capability map; reconciled doctrine; verified agent startup and retrieval paths; +and a tested pilot followed by an owned rollout. Use stable source references +and generated thin adapters instead of maintaining independent security rules +in each provider's prompt. This plan establishes work; it does not enact new +delegations, alter runtime controls, or authorize production changes. + +**DoR-Ok — 2026-10-03:** reviewed the current local canon, owner boundaries, +reference evaluator, existing orientation, and integration routes listed below. +The user explicitly requested this cross-repository workplan. Initial conflicts +are identified, task dependencies and acceptance evidence are defined, and T01 +can begin without changing another owner's policy. This readiness review is not +owner assent to the proposed integration or confirmation of live service health. + +**Definition of done:** all ten tasks have their acceptance evidence; all eleven +explicitly requested repositories have source-backed entries and dispositions; +Codex, Claude, and Grok have separate successful startup/retrieval evidence in +the actual supported session surfaces; a fourth/new adapter can reuse the same +contract; critical security scenarios have no unsafe authorization or routing +answers; source updates and offline operation have been exercised; remaining +owner work has live work-record IDs. An unavailable provider remains an explicit +blocker to full rollout, not an inferred pass. Never mark the plan finished from +documentation coverage alone. + +## Baseline and integration map + +Reviewed 2026-10-03 from local owner checkouts. Commit abbreviations identify the +review baseline, not a permanent version selection or live deployment proof. +T01 must refresh these references and distinguish owner declarations, deployed +behavior, accepted exceptions, and historical notes. Sibling paths are discovery +hints; published references must also resolve without `/home/worsch` checkouts. + +| Repository / baseline | Source entry points | Integration responsibility to preserve | +| --- | --- | --- | +| `net-kingdom` / `89cdcae` | `README.md`, `SECURITY-COMPANION.md`, `canon/standards/security-layer-model_v0.7.md` | Estate security architecture and canon publication; integrate Emergent Security through explicit owner-reviewed mappings. | +| `ops-warden` / `f1e25c3` | `INTENT.md`, `wiki/AccessRouting.md`, `wiki/NetKingdomSecurityMap.md` | Route access needs to the owning facility; distinguish SSH certificate issuance, caller-identity conduits, and declared gaps. | +| `ops-mason` / `20eef04` | `INTENT.md`, `README.md`, `docs/kubernetes-plane.md` | Construct security infrastructure under its approved-plan gate; retain the documented founder-accepted exception rather than claim PDP conformance. | +| `access-engine` / `424f1e5` | `INTENT.md`, `README.md` | Sole estate PDP, currently flex-auth; decide where the reference evaluator's semantics become reviewed claims/policy or remain offline conformance. | +| `security-canon` / `bbd4433` | `README.md`, `docs/vocabulary-card.md`, `docs/adr-001-securitycanon-boundary.md` | Map delegation, principal, scope, and L0–L4 to the architectural vocabulary without treating `MODE @ SCOPE` as a privilege ladder. | +| `user-engine` / `44ed6d5` | `README.md`, `INTENT.md`, `docs/contracts.md` | User/principal and membership facts; identify authoritative claim sources and distinguish identity from permission. | +| `tenant-engine` / `4f7fd11` | `SCOPE.md`, `INTENT.md`, `docs/tenant-guardrail-policy.md` | Tenant identity, lifecycle, roles, and guardrail facts; map platform and tenant envelopes without moving authorization into a PIP. | +| `zone-engine` / `407fa86` | `README.md`, `SCOPE.md`, `docs/pip-claim-boundary.md` | Offline zone-membership conformance; no live zone service or automatic temperature-to-permission mapping. | +| `whitehat-security` / `b5cc670` | `README.md`, `INTENT.md`, `docs/rules-of-engagement.md` | Independently scoped adversarial validation; fixture passes are not live assurance and probes require applicable engagement authorization. | +| `kings-guard` / `200fd17` | `README.md`, `INTENT.md`, `docs/AdjacentSystemBoundary.md` | Observation, posture, and containment proposals; no local authorization or automatic containment actuation. | +| `gate-house` / `6f80ba8` | `README.md`, `INTENT.md`, `docs/contracts/authority-context.md` | Doctrine council and teaching owner; not a credential broker, runtime gate, or PDP. | + +Required adjacent seams: `secrets-engine` (`3149654`, credential lifecycle and +decision consumption; `docs/netkingdom-security-infrastructure.md`), `key-cape` +and OpenBao (identity and custody), `approval-engine` and `informed-decision` +(human decision/approval flow), `audit-core` (evidence custody), `risk-nexus` +(findings), `info-tech-canon` (shared semantics), `ops-bridge` (transport), +Railiance owners (workload execution), `glas-harness` (`dc49415`, session/tool +policy), and `the-custodian` (`f303bda`, estate orientation and rollout). +T01 verifies these additional owners rather than assigning them new duties. +The ops-mason checkout had unrelated tracked changes in `WORK-RECORDS.md` and +`intakes/intakes.md`; they were not modified for this review. + +## Conflicts that must be settled before distribution + +1. Canon G9 calls the credential broker "Gate-House". Gate House's current + owner intent explicitly withdrew that runtime role. Resolve terminology and + map actual credential lifecycle to secrets-engine and its custody backend. +2. The pure `src/emergent_security/decide.py` function is a reference evaluator; + the accepted estate model allows only access-engine to render operational + authorization decisions. Decide its integration and declared repository + boundary without treating reference outcomes as runnable grants. +3. Canon G8/G9 describes bounded observer containment. Kings Guard currently + proposes containment, and the estate documents no automatic actuation surface. + Separate future architecture from current available routes. +4. HOT build defaults, tenant governance, human-controlled root, and policy-edit + rules must be reconciled with the founder's 2026-10-03 build-mode directive, + explicit agent grants, ops-mason's accepted plan gate, and production-change + requirements. Build mode does not mean every target is disposable. +5. Zone temperature, security-zone identity, tenant scope, authority modes, and + runtime environment are different dimensions. Publish an explicit mapping; + never infer one from repository names or from the model provider. +6. Some owner documentation is internally stale: tenant-engine's scope still + contains pre-conformance statements alongside shipped conformance entries; + the companion's observation statement predates Kings Guard's documented + real-event pilot support. Record discrepancies and verify owner evidence; + neither statement establishes current production observation. + +Existing source of operational context: +`the-custodian/docs/agent-environment-orientation.md` (tool-neutral, including +build mode), `docs/agent-autonomy-decision.md`, and +`docs/security-close-down-checklist.md`. Reuse and link their owned facts. +Do not turn archived bootstrap procedures, stale runtime addresses, or a cached +knowledge bundle into current authority. Preserve constitutional disagreements +as explicit decisions with owners; do not silently pick the more permissive text. + +## T01 — Establish the authoritative source and capability inventory + +```task +id: EMERGENT-WP-0002-T01 +title: Establish authoritative sources and current capabilities +status: todo +priority: high +``` + +Refresh all repositories in the integration map, their relevant workplans, +owner declarations, contracts, accepted decisions, and current agent entry +points. Extend the map for actual dependencies. Produce +`knowledge/sources.yaml` and `docs/netkingdom-integration-map.md` (proposed paths). +Each entry names owner, canonical repo/path, revision or digest, authority type, +scope, last verification, review trigger, replacement/supersession, and the +distinction between implemented, deployed, fixture-only, blocked, and unknown. +Keep sensitive routing details out of provider-visible public artifacts. + +Acceptance: every named repository is traceable to its own evidence; broken +references and contradictory status claims are explicit findings; no live-state +claim is inferred from a README or test pass. Identify overlapping owner work +and link it rather than opening duplicate implementation plans. + +## T02 — Reconcile doctrine and decide Emergent Security's integration boundary + +```task +id: EMERGENT-WP-0002-T02 +title: Reconcile doctrine and the reference evaluator boundary +status: todo +priority: high +``` + +Depends on T01. Prepare concrete owner-reviewable dispositions for the six +conflicts above, including the repository's own layer declaration and the +relationship between its canon and NetKingdom's published standards. Record +decisions with gate-house, net-kingdom, access-engine, and security-canon through +their established work-record process. Include tenant, zone, credential, +observer, and construction owners where their contracts change. Record assent, +rejection, or an unresolved dependency without claiming approval from silence. + +Acceptance: a versioned compatibility matrix maps each relevant Emergent rule +to an estate rule, claim, evidence obligation, operational route, or explicit +gap. Apply settled changes to canon, agent extract, policy data, and fixtures +together. All 288 baseline tests still pass unless an explicitly settled +semantic change replaces a documented expectation; new cases cover changes. +Unsettled conflicts block the affected knowledge from normative distribution. + +## T03 — Build the common agent orientation and knowledge package + +```task +id: EMERGENT-WP-0002-T03 +title: Build source-backed security knowledge for agent sessions +status: todo +priority: high +``` + +Depends on T02. Publish one concise start-here document, a machine-readable +manifest, and task-specific reference sections, with source citations and +clear labels for rules, current capabilities, examples, proposals, and gaps. +Set and measure a startup context budget; retrieve deeper material by need. + +The startup context covers task and delegator, repository/domain, principal and +represented actor, environment, tenant, zone/temperature, applicable envelope, +authority mode, evidence needs, and escalation target. Unknown fields remain +unknown. Cover common journeys: local code/test work; access discovery; identity +and tenancy facts; credential use; infrastructure construction; protected deploy; +root recovery; security findings; and requests outside an envelope. + +Acceptance: a fresh reader can identify the right owner and next legitimate +step for every journey and cite its source. Package contains no credentials, +grant-minting behavior, implicit policy overrides, or copied mutable owner +runbooks. The full agent extract is not the default startup payload until its +conflicts are resolved and its context cost is measured. + +## T04 — Define freshness, retrieval, and offline behavior + +```task +id: EMERGENT-WP-0002-T04 +title: Make knowledge retrieval scoped versioned and refreshable +status: todo +priority: high +``` + +Depends on T03. Implement source/version validation, section-level retrieval, +supersession, and a last-verified offline bundle. Tie dynamic facts to their +owner's current interface instead of freezing endpoints, grants, or service +readiness into prose. Keep content and retrieval tenant-scoped; redact or omit +material the chosen provider/session may not receive. + +Acceptance: exercise changed and withdrawn sources, unavailable repositories +or Statehub, expired facts, unresolved scope, and retrieval of another tenant's +content. Stable offline orientation remains useful; current permissions are +never inferred from stale facts. Receipts record package version and consulted +sources without secrets or private tenant content. Retrieved instructions remain +data, not a new delegator or permission channel. + +## T05 — Integrate Codex, Claude, Grok, and harness entry points + +```task +id: EMERGENT-WP-0002-T05 +title: Integrate and verify provider-specific knowledge loading +status: todo +priority: high +``` + +Depends on T04. Inventory the actual installed/direct sessions and governed +glas-harness/rein sessions separately. Verify supported instruction discovery +and context loading for Codex, Claude, and Grok using their current installed +surfaces and official documentation where needed. Use thin pointers/adapters +to the same knowledge contract; do not assume all providers read `AGENTS.md`, +`CLAUDE.md`, skills, or MCP. Support a documented explicit bootstrap where no +native automatic mechanism exists, and make an unloaded session visible. + +Acceptance: fresh-session evidence per provider shows the package version, +source access, scope resolution, and successful task-specific retrieval. Show +loading again after context compaction/resume and when entering another repo. +Test a new adapter against the same contract. An unavailable CLI/account or +blocked harness is recorded as unavailable, never bypassed or counted as tested. +No adapter broadens harness permissions, supplies standing credentials, or +conflates knowledge loading with isolation/enforcement readiness. + +## T06 — Connect operational routes and engine contracts + +```task +id: EMERGENT-WP-0002-T06 +title: Connect delegation knowledge to owned operational interfaces +status: todo +priority: high +``` + +Depends on T02 and T03. Walk the journeys against current ops-warden routing, +ops-mason construction plans, access-engine request/decision contracts, +user/tenant/zone fact sources, secrets-engine lifecycle, approval objects, +audit evidence, and observer/finding routes. Specify field mappings for +principal, scope, delegation, envelope, request identity, decision lifetime, +obligations, and evidence. Identify which seams already exist and which need +owner implementation. Use inert fixtures/dry runs to demonstrate contracts. + +Acceptance: each journey names the owning API/tool or documented unavailable +surface, expected result, failure behavior, evidence, and escalation recipient. +No parallel authorization service, phantom zone API, Gate House credential +broker, automatic containment, or inferred cross-tenant capability is introduced. +Cross-repository changes become linked owner work records; this plan does not +silently take over their implementation or publish their assent. + +## T07 — Evaluate agent understanding and adversarial failure cases + +```task +id: EMERGENT-WP-0002-T07 +title: Test situational understanding and unsafe routing failures +status: todo +priority: high +``` + +Depends on T05 and T06. Build a provider-neutral scenario corpus and expected +owner/rule/evidence outcomes. Include ordinary delegated edits (no unnecessary +escalation), missing scope, tenant-envelope excess, tenant human reservations, +stale claims, negative memory, engine outage, root requirements, provider switch, +hostile retrieved instructions, broader available credentials, production targets +in build mode, stale bootstrap instructions, and the six known doctrine conflicts. +Include a source withdrawal and a task whose answer requires deeper retrieval. + +Acceptance: deterministic package/contract checks pass; actual Codex, Claude, +and Grok session reports identify exact model/session/adapter/package revisions +and separate retrieval failure from reasoning failure. Predeclare scoring: +every critical case requires correct boundary, owner/route, evidence, and no +invented permission; any unsafe action recommendation blocks release. Record +all results and rerun failed cases after fixes. Seek whitehat-security-owned +adversarial review; fixture evaluation does not authorize live attack traffic. + +## T08 — Pilot in representative ecosystem repositories + +```task +id: EMERGENT-WP-0002-T08 +title: Pilot agent orientation across doctrine operations and engines +status: todo +priority: high +``` + +Depends on T07. Arrange owner-scoped pilots spanning net-kingdom/gate-house, +ops-warden/ops-mason, an engine consumer, and an ordinary infrastructure repo. +Run bounded tasks covering local implementation, operational routing, and an +escalation; use the approved provider routes and record correct abstentions. +Pilot activation changes knowledge entry points only; any required security +control or live-environment change needs its own reviewed owner work. + +Acceptance: source-backed session evidence shows agents finding applicable +context and completing authorized work or reaching the right human/owner. +Measure startup context size, retrieval success, stale-source detection, +unnecessary escalations, and unsafe recommendations. Demonstrate rollback to +the preceding knowledge release. Capture owner feedback and link all defects. + +## T09 — Roll out and establish knowledge maintenance + +```task +id: EMERGENT-WP-0002-T09 +title: Roll out shared knowledge and establish update ownership +status: todo +priority: medium +``` + +Depends on T08. Agree publication and teaching ownership with gate-house and +net-kingdom, source update duties with each owner, and startup distribution +with the-custodian/glas-harness. Use the estate's existing standing-notice and +acknowledgment mechanism through an explicitly authorized communication step; +do not independently rewrite every repository's agent policy. Track coverage +for all named repositories and providers, including explicit non-applicability. + +Acceptance: published package and adapters have release/rollback procedures, +change triggers, source freshness checks, and an assigned review cadence. Owner +changes invalidate or regenerate affected knowledge; unsupported sessions and +failed loading are visible. Notices/acknowledgments demonstrate reach, while +T07/T08 evidence demonstrates understanding. Add unresolved implementation +needs as owner work records, not buried prose or implied delivered capabilities. + +## T10 — Verify adoption and close with evidence + +```task +id: EMERGENT-WP-0002-T10 +title: Verify adoption and hand off remaining owner work +status: todo +priority: medium +``` + +Depends on T09. Review the completion contract against the source matrix, +settled decisions, adapter results, provider scenario reports, pilot records, +and rollout coverage. Confirm current docs distinguish observed behavior from +aspiration and reference semantics from operational authorization. + +Acceptance: publish a concise evidence index and final integration map. Record +DoD-Ok only when the completion contract is met. Every residual has a linked +live work record and owner; unresolved safety-critical conflicts or missing +provider proofs keep this plan open. Sync the final source files through Repo +Manager and verify the primary Statehub projection matches the pushed commit.