From b362985d463540ffdc3a0416a1a95c57d7264ad0 Mon Sep 17 00:00:00 2001 From: John Osumi <931193+sumitake@users.noreply.github.com> Date: Tue, 8 Sep 2026 15:06:10 -0700 Subject: [PATCH] docs: audit current architecture and release documentation --- README.md | 5 ++- .../20260908-documentation-main-audit.md | 6 +++ docs/architecture/README.md | 3 ++ .../capabilities-and-workflows.md | 9 +++-- docs/architecture/repository-and-release.md | 19 ++++++---- docs/architecture/system-context.md | 8 ++-- docs/documentation-audit-2026-09-08.md | 38 +++++++++++++++++++ skill-specs/README.md | 3 +- 8 files changed, 75 insertions(+), 16 deletions(-) create mode 100644 changelog.d/20260908-documentation-main-audit.md create mode 100644 docs/documentation-audit-2026-09-08.md diff --git a/README.md b/README.md index 5bd64eb7..3e3f54a6 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,9 @@ codex plugin marketplace add sumitake/agent-collab codex plugin add agent-collab@agent-collab ``` +For other supported hosts and update verification, follow +[Lifecycle and operations](docs/architecture/lifecycle-and-operations.md). + ### Post-install setup (agent-performed, consent-gated) When an agent performs the installation inside a user project, it completes @@ -162,7 +165,7 @@ setup step exists. ```text python3 scripts/build_skills.py --check python3 scripts/build_marketplace.py --check -python3 scripts/build-changelog.py --check +python3 scripts/build-changelog.py --dry-run python3 -m unittest discover -s tests -t . -v python3 -m unittest discover -s scripts -p 'test_*.py' -v python3 scripts/check_release_consistency.py diff --git a/changelog.d/20260908-documentation-main-audit.md b/changelog.d/20260908-documentation-main-audit.md new file mode 100644 index 00000000..cba8fd5a --- /dev/null +++ b/changelog.d/20260908-documentation-main-audit.md @@ -0,0 +1,6 @@ +### Documentation + +- Audit the current README and architecture handbook against implementation; + clarify runtime versus public-client ownership, complete the skill capability + map, and make qualification stages explicit. Preserve the automated + latest-release-only README rule and dated release evidence. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 960f205d..015ab9e5 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -120,3 +120,6 @@ or release boundary changes. Keep each claim tied to repository-relative source and focused evidence. If delivery evidence lags source, keep both observations and label them; do not “fix” the discrepancy by declaring one generation active everywhere. + +The [2026-09-08 documentation audit](../documentation-audit-2026-09-08.md) +records the inspected baseline, update delta, coverage, and historical boundaries. diff --git a/docs/architecture/capabilities-and-workflows.md b/docs/architecture/capabilities-and-workflows.md index a4bf0c77..13dc682f 100644 --- a/docs/architecture/capabilities-and-workflows.md +++ b/docs/architecture/capabilities-and-workflows.md @@ -22,6 +22,7 @@ organizes that inventory by user outcome. | Deliberation and stakeholder lenses | `debate`, `simulate-user` | Expose conflicting arguments or test a proposal against a persona. | | Delegation and implementation | `delegate`, `dev-delegate`, `worker` | Analyze supplied sources or return a development artifact for the primary to integrate. | | Context and knowledge work | `context`, `knowledge-compile`, `project-knowledge` | Extract or synthesize bounded documents/repositories, or maintain an explicit project knowledge layer, with provenance. | +| Shared project lessons | `learning-loop` | Consult and maintain an explicit project-owned lesson ledger through the portable offline helper; retrieved lessons remain untrusted hypotheses. | | Reproducible workflows | `chain`, `chain-configurator`, `orchestrate` | Define and execute repeatable multi-step coordination. | | Integration and conflict handling | `merge-resolve` | Analyze and resolve a bounded merge conflict while preserving intent. | | Visual guidance | `ui-to-code`, `visual-review` | Guide primary-only visual work when typed image transport is absent; never invent a managed attachment path. | @@ -46,7 +47,9 @@ Current repository route contracts cover: cost-last after eligible Gemini and Grok routes; - Gemini advisory, governance, and bounded context work; - Codex advisory, governance, and output-only code-generation work; -- OpenCode planning and output-only build work; +- OpenCode planning, context, governance, and output-only build work through + four logical lineages: Moonshot, Zhipu, Alibaba, and DeepSeek. They share one + transport/resource pool; shared transport does not establish independence; - Grok read-only architecture, governance, bounded context, and output-only code generation. @@ -107,7 +110,7 @@ primary/artifact-author lineage exclusion fields. ### Bounded delegation The primary keeps objective interpretation and integration ownership. Ordinary -`delegate` work analyzes supplied bounded documents or an exact sealed +`delegate` work analyzes supplied bounded documents or a caller-verified repository through an admitted context action. A list of names, links or topics alone is not a document corpus, and this route does not promise source discovery. Each worker receives the relevant sources, scope and stop condition. Results @@ -156,7 +159,7 @@ authority. | Codex CLI/app | Codex-native manifest and generated Codex marketplace. | Native package install and the same skill namespace. Start a new task after install/update. | | Antigravity | Compatible plugin import, logical Gemini managed routes, and separate host-owned async coordination; no separate package. | Gemini repository review uses the co-packaged coordinator and action-scoped readiness. Async readiness is a different surface; neither host name nor reviewer role proves independence. | | OpenCode and ZCode | Dynamic host/model policy and managed OpenCode routes; no separate package. | A compatible host/plugin surface is required. OpenCode is a transport; the selected model supplies family lineage. | -| Custom host | Explicit primary identity fields and the closed package contract. | If the host cannot load the package safely, it is unsupported; do not recreate provider-specific shims. | +| Custom host | Caller-verified identity and the closed package contract; the routing wire does not accept primary/author lineage fields. | If the host cannot load the package safely, it is unsupported; do not recreate provider-specific shims. | ## Availability rules diff --git a/docs/architecture/repository-and-release.md b/docs/architecture/repository-and-release.md index 0d48f1c9..e662a580 100644 --- a/docs/architecture/repository-and-release.md +++ b/docs/architecture/repository-and-release.md @@ -13,7 +13,7 @@ contributors do not need access to it. | --- | --- | --- | --- | | `skill-specs/` | current | Editable source for collaboration skills. | Edit here; do not hand-edit generated copies. | | `plugins/agent-collab/skills/` | generated/current | Host-readable installed skill contracts. | Regenerate with `scripts/build_skills.py`. | -| `plugins/agent-collab/` public Python modules | current | Coordinator, identity/authority policy, migration, runtime verification/management, and signing policy. | Keep the public module inventory closed. | +| `plugins/agent-collab/` public Python modules | current | Routing transport, host observations, migration reporting, runtime verification, and signing policy; workflow authority remains caller-owned. | Keep the public module inventory closed. | | `plugins/agent-collab/project-estimation-data/` | current bootstrap contracts and evidence | Strict request/result and maintenance schemas plus one privacy-safe aggregate/pricing/quota handoff and version-bound receipt. | Never add raw evidence; admit only closed, receipt-declared members. | | `plugins/agent-collab/.claude-plugin/` and `.codex-plugin/` | current | Host manifests for the same name and version. | Update together. | | `.claude-plugin/` and `.agents/plugins/` | generated/current | Claude-compatible and Codex marketplace views. | Regenerate with `scripts/build_marketplace.py`. | @@ -56,8 +56,8 @@ fragment. The public repository owns: -- request and result policy; -- model-family and authority decisions; +- public request/result schemas and caller workflow policy; +- skills that require caller verification of reviewer family and authority; - skills and generated host-facing documentation; - runtime client, manifest schema, migration, and management contracts; - artifact verification and signing-policy anchors; @@ -66,7 +66,7 @@ The public repository owns: The private producer owns: -- native provider implementation source; +- native provider implementation and compiled route-admission logic; - build credentials and signing keys; - private build/sign infrastructure; and - any secret-bearing provider integration material. @@ -135,20 +135,25 @@ flowchart LR Source --> Generated["Regenerated package views"] Generated --> Fragment["Unique changelog fragment"] Fragment --> Local["Local validation"] - Local --> Review["Independent exact-head review"] + Local --> Staged["Required staged artifact qualification"] + Staged --> Review["Review required by the change tier"] Review --> PR["Governed pull request"] PR --> Main["Merged source baseline"] Main --> Tag["Signed annotated tag"] Tag --> Release["Verified release assets and evidence"] Release --> Install["Host install/update"] Install --> Ready["Provider-free readiness"] - Ready --> Closeout["Final documentation closeout"] + Ready --> Live["Required installed native qualification"] + Live --> Closeout["Final documentation closeout"] Closeout --> Complete["Release complete"] ``` Each arrow needs its own evidence. A merged pull request does not create a tag; a tag does not create a release; a release does not update a host; installation -does not prove readiness. +does not prove readiness, and provider-free planning does not prove native +execution or fresh-session skill loading. The required qualification scope +depends on the changed artifacts; unchanged runtime evidence retains its date +and identity. A documentation-only correction does not itself cut a release. ## Validation layers diff --git a/docs/architecture/system-context.md b/docs/architecture/system-context.md index 06abea34..f368684d 100644 --- a/docs/architecture/system-context.md +++ b/docs/architecture/system-context.md @@ -57,10 +57,10 @@ flowchart LR Skill --> Async["Host-owned async coordination readiness"] Coord --> Identity["Manifest-bound routing request"] - Identity --> Policy["Descriptor-admitted routes and resources"] - Policy --> Client["Verified runtime client"] + Identity --> Client["Verified runtime client"] Client --> Runtime["Manifest-selected signed runtime"] - Runtime --> Role["Managed provider role"] + Runtime --> Policy["Descriptor-admitted routes and resources"] + Policy --> Role["Managed provider role"] Role --> Result["Opaque content and execution facts"] Result --> Primary @@ -104,7 +104,7 @@ The installable package contains: - Claude-compatible and Codex-native manifests for the same package/version; - generated skills built from the editable `skill-specs/` source; -- coordinator, host policy, migration doctor, runtime client/setup, bundle +- coordinator, host observations, migration doctor, runtime client, bundle verification, and signing-policy modules; - the closed runtime and output schemas; - package legal and third-party notices; and diff --git a/docs/documentation-audit-2026-09-08.md b/docs/documentation-audit-2026-09-08.md new file mode 100644 index 00000000..bb05a6be --- /dev/null +++ b/docs/documentation-audit-2026-09-08.md @@ -0,0 +1,38 @@ +# Documentation audit — 2026-09-08 + +The inspected remote-main baseline is `fb13fc5`, the v7.0.6 documentation +closeout. The previous closeout was `77d061f` for v7.0.5. Between them, +`c03af78` corrects caller-owned review independence across skill instructions, +`fc8d66b` compiles the release changelog, and `fb13fc5` records the resulting +release and installation evidence. The signed v7.0.6 tag identifies +`fc8d66b3978dc1f2a177e9447b45915bb3486f84`; its runtime remains 5.0.7. + +The audit examined unchanged descriptions as well as that release delta. +All nine architecture handbook pages were checked against public source, +generated inventories, contract tests, and the existing dated release record. + +| Surface | Disposition | +| --- | --- | +| Root README | Verified the 7.0.6 summary and sole latest-release showcase. Added the supported-host lifecycle pointer and use changelog dry-run for a branch carrying fragments. | +| Architecture index | Verified ownership, source map, lifecycle labels, and sanitization contract. | +| System context | Corrected the order: public client verifies the bundle, then the signed runtime selects descriptor-admitted routes. Removed the nonexistent setup-module description. | +| Capabilities/workflows | Added the missing `learning-loop` skill, corrected OpenCode's four-lineage context/governance coverage, and clarified caller-owned repository and identity verification. | +| Governance/authority | Verified caller-owned lineage and source checks, opaque-content acceptance, separate evidence and merge decisions, and no inferred independence from routing. | +| Lifecycle/operations | Verified supported host install/update commands against this repository's maintained host contract, doctor and planning distinctions, recovery boundaries, and fresh-session loading caveat. | +| Repository/release | Corrected public transport versus compiled admission ownership; made staged and installed native qualification visible in the lifecycle alongside provider-free readiness. | +| Status/evidence | Verified current release identity against the immutable tag and published release; retained dated installation claims and earlier canaries as historical evidence. No new host qualification is claimed. | +| Project estimation | Verified current receipt-bound bootstrap, source inventory, private/public boundary, unknown metrics, maintenance validation, and release gates. | +| Claude participation | Verified intent-only admission and the dated 7.0.6 subscription denial; host, resident, async, and managed roles remain separate. | +| Package technical README and skill-specs README | Checked current counts and wire/manifest/client boundaries; corrected the source-spec count to 53, excluding authoring material. | +| Supporting current docs, design index, governance, migration, licensing/provenance, and changelog | Checked owning source links and current/historical status. Retained historical designs, release snapshots, and generated history with their original identities. | + +The README's latest-release-only rule remains automated by +`scripts/check_release_consistency.py` and its regression suite in +`scripts/test_check_release_consistency.py`. Exactly one heading must name the current +package version; missing, duplicate, and stale headings fail. Older releases +belong in `CHANGELOG.md`, not additional README showcases. + +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. diff --git a/skill-specs/README.md b/skill-specs/README.md index f6928045..1abc05ba 100644 --- a/skill-specs/README.md +++ b/skill-specs/README.md @@ -1,6 +1,7 @@ # Shared skill specifications -The 52 non-underscore Markdown files in this directory are the editable source +The 53 skill specifications in this directory (excluding this README and +underscore-prefixed authoring material) are the editable source for their matching `plugins/agent-collab/skills/*/SKILL.md` files. There is one output package and no alias or preset generation.