Skip to content

[Docs][Trust] Disclose route-written Git state, make the installed-Hook comparison optional, and state Codex trust and Windows status - #232

Merged
wheakerd merged 1 commit into
mainfrom
feature/docs-trust-model
Oct 30, 2026
Merged

wheakerd merged 1 commit into
mainfrom
feature/docs-trust-model

Conversation

@wheakerd

Copy link
Copy Markdown
Owner

Scope

Refs #221. Four user-facing documentation gaps:

  • docs/trust-model.md gains Repository State Written By Routes, naming every location the routes write inside a target repository's Git metadata: axiom/traceable-git-submit-baseline.json and axiom/traceable-git-submit-active-checkpoints.json under the Git directory, backup refs under refs/axiom/backups/traceable-git-submit/<unique-id>, and agents-architect session capsules under axiom/agents-architect/, with when they are written, the commands to list and remove them, the legacy working-tree locations, and the user-local ignore entries agents-architect may add. The Boundary Summary gains a matching row.
  • The installed-Hook comparison becomes an optional supply-chain check for reviewers, described once in the trust model's Hook Trust Boundary. README.md, docs/guides/getting-started.md (whose Inspect The Hook section becomes Trust The Hook), docs/guides/managing-installation.md, docs/compatibility.md, and docs/reference/hooks.md now reference it instead of requiring it; the Hook Reference stays the canonical rendering of the checked-in commands.
  • The README install section states the Codex /hooks trust step (routing begins after it) and the Windows status; the Getting Started guide drops the test-repository precondition and the #inspect-the-hook anchor; Managing an Installation says that disabling or removing Axiom leaves route-written Git state in place.
  • docs/compatibility.md states that neither host has a recorded Windows observation, how the CI job exercises the Hook commands on Windows, and the PowerShell fallback.

Repository policy revision 119 records the change in the ledger; the plugin version and runtime contract digest are unchanged.

Affected files and surfaces

  • Shared files: None
  • Codex-specific files: None
  • Claude Code-specific files: None
  • Documentation or validation files: README.md, docs/trust-model.md, docs/guides/getting-started.md, docs/guides/managing-installation.md, docs/compatibility.md, docs/reference/hooks.md; evidence/repository-policy-revisions-v1.json, evidence/runtime-identity.json, evidence/release-status.json, docs/runtime-identity.md, docs/repository-policy-revisions.md (revision 119)

Routing and authorization impact

  • Route-selection impact: None. No skill text changes.
  • Action-authorization impact: None. The documentation describes existing route behavior; no route gains or loses authority.
  • New or changed stop conditions: None.

Documentation

The trust model owns the write-location disclosure and the optional verification; the install and update guides, the README, the compatibility reference, and the Hook Reference link to it. Installation and hook commands are unchanged.

Validation

Command Result
python3 -B scripts/check-publication.py Passed on this exact tree: 153 required files, 169 Markdown files, 30 immutable external action and image pins
python3 -B -m unittest discover -s tests -p 'test_*.py' OK in a disposable clone of this tree: 315 tests
git diff --check Passed
Additional targeted checks ASCII scan of the changed Markdown and JSON files: passed. No remaining #inspect-the-hook anchor in the repository.

Cross-platform parity

  • Shared skill changes were reviewed against Codex and Claude Code, or this change does not affect shared skills.
  • Manifest, marketplace, and hook differences remain intentional and documented.
  • Optional host-native validation results include the host/tool version, or are marked unavailable.

Unrelated work

  • I reviewed the final diff and did not reset, hide, stage, or rewrite unrelated work.
  • I did not add generated caches, disposable validation copies, local maintenance notes, or tool output.
  • I called out every affected file and any routing, authorization, documentation, or parity impact above.

…mparison optional

Remote baseline: origin/main @ 3097889

Scope:
Four user-facing documentation gaps from Issue #221. The trust model gains a Repository State Written By Routes section that names every location the routes write inside a target repository's Git metadata: the traceable-git-submit baseline cache and active checkpoint record under the Git directory, its backup refs under refs/axiom/backups/traceable-git-submit/<unique-id>, and the agents-architect session capsules under axiom/agents-architect/, with the commands to list and remove them, the legacy working-tree locations, and the user-local ignore entries agents-architect may add. The installed-Hook comparison becomes an optional supply-chain check for reviewers, described once in the trust model's Hook Trust Boundary and referenced from the README, the Getting Started guide (whose Inspect The Hook section becomes Trust The Hook), Managing an Installation, Compatibility, and the Hook Reference, which stays the canonical rendering of the checked-in commands. The README install section now states the Codex /hooks trust step and the Windows status, the Getting Started guide drops the test-repository precondition, Managing an Installation says that disabling or removing Axiom leaves route-written Git state in place, and Compatibility states that neither host has a Windows observation and how CI exercises the Hook commands on Windows. Repository policy revision 119 records the change for Issue #221 in the ledger with an unchanged plugin version and runtime digest.

Validation:
python3 -B scripts/check-publication.py: passed on the exact tree (153 required files, 169 Markdown files, 30 immutable action pins)
python3 -B -m unittest discover -s tests -p 'test_*.py': 315 tests OK in a disposable clone of the tree
git diff --check: clean; ASCII scan of the changed Markdown and JSON files: passed
@wheakerd
wheakerd merged commit 64f39b7 into main Oct 30, 2026
10 checks passed
@wheakerd
wheakerd deleted the feature/docs-trust-model branch October 30, 2026 09:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant