diff --git a/AGENTS.md b/AGENTS.md index 51353c2..d0981a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,11 +60,20 @@ these rules. ## Runtime policy -Provider routing must pass the provider-free startup preflight. Active legacy -package state blocks all provider routing. Unknown-family governance review -requires explicit configuration and fails closed; non-governance use carries an -independence warning. Policy-only safe mode preserves only validated async -inbox/coordination seams and returns typed unavailable for every model route. +The coordinator is a routing-only shim. Its client validates the manifest, +request, and native bundle; the signed runtime selects descriptor-admitted +routes. Provider-free planning does not establish authentication or live +availability. Run the migration doctor as a separate host inventory step; do +not claim that the coordinator automatically runs a migration or identity +preflight. Host-owned asynchronous coordination is outside this routing wire. + +The caller and skill/repository workflow verify the primary, artifact-author, +and reviewer lineages wherever independence is required. The current wire has +no dynamic primary/author-family exclusion fields; host observations and a +route decision cannot establish independent approval. Unknown-family output +can be advisory but cannot satisfy governance-grade independence. A policy-only +package has no admitted native artifact and returns typed unavailable for model +execution. It does not expose a separate async-runtime safe-mode service. The native client accepts no path or member override, resolves only the manifest-selected closed bundle beneath the plugin root, and rejects links, diff --git a/changelog.d/20260908-runtime-policy-documentation.md b/changelog.d/20260908-runtime-policy-documentation.md new file mode 100644 index 0000000..869b382 --- /dev/null +++ b/changelog.d/20260908-runtime-policy-documentation.md @@ -0,0 +1,5 @@ +### Documentation + +- Correct contributor instructions to distinguish the routing shim and verified + client from separate migration inventory and caller-owned identity checks. + Remove obsolete runtime-management and async safe-mode descriptions. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 015ab9e..87fd167 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -108,7 +108,7 @@ not a public issue or pull request. | How are agent projects estimated? | [Project estimation](project-estimation.md) | Public request/result schemas, deterministic helper, released v7.0.6 maintenance evidence, skill checkpoints, maintenance verifier, producer-byte compatibility fixtures, and focused tests. | | Who may review, write, or merge? | [Governance and authority](governance-and-authority.md) | Host policy, coordinator, public governance contract, PR template, and compliance checks. | | Is a route usable now? | [Status and evidence](status-and-evidence.md) | Installed version plus provider-free readiness on that host. Repository presence alone is insufficient. | -| How do I install or recover? | [Lifecycle and operations](lifecycle-and-operations.md) | Current host CLI, migration doctor, runtime-management surface, and migration policy. | +| How do I install or recover? | [Lifecycle and operations](lifecycle-and-operations.md) | Current host CLI, migration doctor, verified runtime client, and migration policy. | | How is a release produced? | [Repository and release architecture](repository-and-release.md) | Release scripts, workflows, signed-tag contract, archive checks, and release evidence. | | Where may Claude participate? | [Claude participation](claude-participation.md) | Signed action/source targeting, official structured-CLI boundary, async coordination, and host-support statements in this handbook. | diff --git a/docs/architecture/governance-and-authority.md b/docs/architecture/governance-and-authority.md index b11b4e1..a0a4698 100644 --- a/docs/architecture/governance-and-authority.md +++ b/docs/architecture/governance-and-authority.md @@ -153,7 +153,7 @@ and its evidence is verified. remain uncertain; neither is converted into successful governance evidence. - **Separation of duties:** authoring, reviewing, integrating, merging, and releasing remain distinct accountable acts. -- **Recoverability:** safe mode and retained verified state stop execution +- **Recoverability:** an unavailable native artifact stops execution without reviving retired packages or bypassing migration checks. For operational application of these rules, continue to diff --git a/docs/architecture/repository-and-release.md b/docs/architecture/repository-and-release.md index e662a58..685e55a 100644 --- a/docs/architecture/repository-and-release.md +++ b/docs/architecture/repository-and-release.md @@ -22,7 +22,7 @@ contributors do not need access to it. | `docs/architecture/` | current | Public architecture handbook. | Update with boundary or lifecycle changes. | | `docs/design/` | mixed | Design-of-record and historical review evidence. | Consult the design index and source/tests before treating it as current. | | `docs/public-governance.md` | current/normative | Contribution and merge contract. | Keep prose and automation aligned. | -| `docs/migration-from-legacy-packages.md` | current | Retirement, cleanup, safe mode, and package migration. | Do not revive retired install surfaces. | +| `docs/migration-from-legacy-packages.md` | current | Retirement inventory, cleanup guidance, and package migration. | Do not revive retired install surfaces. | | `changelog.d/` | staged | Per-change release-note fragments. | Commit one unique fragment; do not compile `CHANGELOG.md` on feature branches. | | `CHANGELOG.md` | generated | Release-time compilation of fragments. | Updated only by the release flow. | | `scripts/` | current | Build, validation, compliance, archive, evidence, and release tools. | Preserve fail-closed behavior and tests. | diff --git a/docs/architecture/system-context.md b/docs/architecture/system-context.md index f368684..04b9082 100644 --- a/docs/architecture/system-context.md +++ b/docs/architecture/system-context.md @@ -25,7 +25,8 @@ to land the result. - A public policy boundary that defines lineage and independence requirements for repository and skill workflows, and seals route authority. - A verified client for an optional co-packaged native runtime. -- A migration and safe-mode boundary for retiring older package generations. +- A separate migration inventory and fail-closed native-artifact boundary for + retiring older package generations. - A deterministic offline project-estimation component with a released, privacy-safe bootstrap aggregate and no provider dependency. - A public contribution, CI, and release contract that can be applied without diff --git a/docs/documentation-audit-2026-09-08.md b/docs/documentation-audit-2026-09-08.md index bb05a6b..9132d14 100644 --- a/docs/documentation-audit-2026-09-08.md +++ b/docs/documentation-audit-2026-09-08.md @@ -36,3 +36,9 @@ This audit changes repository documentation only. It does not regenerate skills, alter package/runtime bytes or policy, move tags, or claim a new release. Private producer identifiers, local paths, credentials, and native invocation recipes are excluded. Validation and review evidence are recorded in the PR. + +The follow-up instruction-file correction removes the obsolete `AGENTS.md` +claim that the routing shim automatically runs identity/migration preflight +or owns an async safe-mode service. The doctor is a separate inventory tool, +and lineage verification is a caller workflow requirement. This clarification +changes no runtime enforcement and follows the operator-reserved review path.