aoci.code.txt

#AOCI-CODE-VOLUME: 1

===/<repository>/===
.gitattributes[CG3T]: F:Normalizes repository text line endings for deterministic hashes and cross-platform collaboration | R:- | A:- | S:autocrlf rewrites would mark the whole tree stale
.gitignore[CG5T]: F:Separates tracked cognition assets from ignored runtime, recovery, build, agent host integration, cached release binaries, and local configuration state | R:code:internal/hooks/installer.go,code:internal/hooks/claude.go | A:- | S:Never track the agent host configs listed here: their paths are machine-bound and installers early-return on a key-presence check, so a committed copy silently no-ops another machine's init
.goreleaser.yml[CG5T]: F:Defines six CGO-free trimmed aoci archives with legal documents, bilingual READMEs and logos, checksums, and per-archive SBOM generation | R:code:.github/workflows/release.yml,code:scripts/release/archive-smoke/main.go,code:internal/buildinfo/buildinfo.go | A:GoReleaser v2 configuration | S:Remote publishing remains disabled; the signed workflow rebuilds SHA256SUMS after adding all six SBOMs; ldflags inject internal/buildinfo
AGENTS.md[CG8S]: F:Defines repository integration and AOCI cognition setup, reuse, AOCI-first reading, maintenance, closing, verification, and index-admission rules for agents | R:code:docs/contract-authority.md,code:docs/zh-cn-contract-authority.md,code:scripts/blackbox/README.md,code:Makefile | A:- | S:Live Guide, tool schema, Spec, and Validator remain authoritative over this integration block; historical memory never substitutes for a current repository-bound cognition receipt; a green make fast proves nothing about the make full-only gates; make verify is the one-shot closure command and never replaces the per-change table; the managed block is the rendered AGENTS template, so a template change lands here too and never by hand; the index quality check runs after the final Apply, on the aligned tree
CHANGELOG.md[CG3L]: F:Records public release history, an Unreleased section for changes not yet tagged, and per-version contract, governance, and Schema Evidence changes | R:- | A:- | S:Pointer tests read the top ## v heading as current
CODE_OF_CONDUCT.md[CG3T]: F:Sets public community behavior and reporting expectations | R:- | A:- | S:-
CONTRIBUTING.md[CG5T]: F:Explains contribution boundaries, verification gates, public contracts, and review requirements | R:code:Makefile | A:- | S:The go.mod version names the base Go install, not what go version prints, because GOTOOLCHAIN=auto re-executes a downloaded toolchain and hides an older base
LICENSE[CG5S]: F:Carries FSL-1.1-MIT terms and the 2026 Liu JinShi copyright notice, including Permitted Purpose limits and the future MIT grant | R:code:NOTICE,code:scripts/check-licenses.sh | A:FSL-1.1-MIT | S:The MIT grant begins on the second anniversary of the date each version is made available
Makefile[CG9M]: F:Defines build, preflight, format, test, connector-replay, license, full, verify, coverage-floor, fuzz, self-axis, migration-drill, ladder, and release targets | R:code:scripts/check-opengauss-connector.sh,code:scripts/check-licenses.sh,code:scripts/release/manifest/main.go,code:scripts/blackbox/ladder.py,code:scripts/check-coverage-floors.sh,code:internal/buildinfo/buildinfo.go,code:scripts/blackbox/legacy-migration/main.go,code:scripts/blackbox/mcp_upgrade.py | A:make fast,make full,make verify,make axis-self,make fuzz-smoke,make legacy-migration | S:fmt covers the main module and AOCI-owned connector patches only, keeping the upstream mirror byte-identical; race times out at 30 minutes; preflight checks the base toolchain; verify runs full under -k, must invoke BUILD_BIN, then suites and axis-self, printing the ladder; fuzz-smoke refuses a Fuzz function absent from FUZZ_TARGETS; update-goldens rewrites every golden, init hints included, only under AOCI_UPDATE_GOLDEN=1; ldflags target internal/buildinfo; fast-builds builds examples/engine-embed; legacy-migration gets LEGACY_RELEASE by mcp_upgrade.py --fetch, outside full
NOTICE[CG3T]: F:Records AOCI-CODE v0.1.0-rc1 through v0.2.0-rc1 under FSL-1.1-MIT with Liu JinShi, copyright year 2026, and public availability dates | R:code:LICENSE,code:PATENTS,code:TRADEMARKS,code:THIRD-PARTY-NOTICES | A:- | S:Availability lines are appended, never rewritten
PATENTS[CG3T]: F:Provides Liu JinShi as Patent/IP contact while making no patent ownership, number, application, registration, or additional-rights claim | R:code:LICENSE | A:- | S:Authorized counsel must confirm extra disclosure
README.md[CG5L]: F:Introduces AOCI-CODE in English: what it does, sample entry, CodeGraph contrast, quick start, how it works, format, hosts, CLI, databases, releases, community | R:code:README.zh-CN.md,code:docs/database-evidence.md,code:docs/supply-chain.md,code:spec/public/aoci-database-evidence-v1.txt,code:textassets/en-US/templates/volume-root.txt.tmpl,code:textassets/en-US/templates/volume-meta.txt.tmpl | A:- | S:Tag links serve archives; QR URL absolute as archives omit it; MySQL 5.7.6+, no MariaDB; openGauss 6.0.5 A/PG; header blocks, badge, version, counts test-bound; the Meta excerpt mirrors the template
README.zh-CN.md[CG5L]: F:Presents, in Chinese, AOCI-CODE capabilities, usage, CodeGraph contrast, cognition, layout, onboarding, governance, releases, openGauss, and a user group | R:code:README.md,code:docs/database-evidence.md,code:docs/supply-chain.md,code:spec/public/aoci-database-evidence-v1.txt,code:textassets/zh-CN/templates/volume-root.txt.tmpl,code:textassets/zh-CN/templates/volume-meta.txt.tmpl | A:- | S:Tag links serve archives; QR URL absolute, archives omit it; MySQL 5.7.6+, no MariaDB; openGauss 6.0.5 A/PG; header blocks test-bound; badge, version, counts gated; Meta excerpt mirrors the template
SECURITY.md[CG5T]: F:Defines security reporting, sensitive-data boundaries, the no-model-client network rule, backup and status-page limits, and coordinated disclosure | R:- | A:- | S:The status-page link and its registration carry a per-process capability and must not be shared or logged
THIRD-PARTY-NOTICES[CG3L]: F:Retains hashed license texts and the exact 26-module release-matrix inventory, including the SQLite driver, the patched openGauss Connector and transitives | R:code:go.mod,code:docs/supply-chain.md,code:scripts/check-licenses.sh,code:third_party/openGauss-connector-go-pq.PROVENANCE.md | A:- | S:Connector attribution must remain auditable
TRADEMARKS[CG3T]: F:Provides Liu JinShi as Trademark/IP contact while making no ownership or registration claim and limiting use to LICENSE identification | R:code:LICENSE | A:- | S:Final marks and brand policy require legal review
go.mod[CG8T]: F:Declares the canonical Go module, exact Go version, and pinned runtime graph: four database drivers and the reviewed openGauss Connector replacement | R:code:third_party/openGauss-connector-go-pq/go.mod,code:third_party/openGauss-connector-go-pq.PROVENANCE.md,code:THIRD-PARTY-NOTICES | A:Go module dependency graph | S:The exact local replace keeps builds off unpatched upstream; the go directive carries the full patch version because setup-go installs it via go-version-file and the GOTOOLCHAIN=local license gate rejects a toolchain switch. A bump changing cmd/aoci's module set breaks the license inventory (make licenses only); a first-party import must be a direct requirement, since CI tidies and diffs the marker; the pure-Go SQLite driver brings three modules, 26 in the release matrix
go.sum[CG3S]: F:Authenticates downloaded Go dependency content, including the openGauss Connector and SQLite driver transitive graphs used by builds | R:code:go.mod | A:- | S:Local replacement needs separate provenance proof
glama.json[CG3T]: F:Names the GitHub maintainers who may claim this repository's listing in the Glama MCP directory | R:- | A:- | S:Directory metadata only; nothing in AOCI reads it

===/<repository>/.github/workflows/===
ci.yml[CG5M]: F:Runs the pull-request and branch CI matrix: formatting, tests, builds, contract checks, static analysis, black-box suites, harness regressions, native SQLite | R:code:scripts/blackbox/README.md,code:internal/safety/files.go | A:- | S:Pins match the other workflows; every job has a timeout; sqlite-native fails on an empty selection; v*-line pushes run it; contracts-and-safety holds the index to its floors
full-confidence.yml[CG5L]: F:Runs nightly, manual, and main-push gates: licenses, races, lifecycle, scale, upgrade axis, migration drill, coverage floors, fuzz, benchmarks, databases, OSes | R:code:Makefile,code:scripts/check-licenses.sh,code:scripts/blackbox/README.md,code:scripts/blackbox/mcp_upgrade.py,code:scripts/coverage-floors.txt,code:scripts/blackbox/mcp_lifecycle.py,code:scripts/blackbox/legacy-migration/main.go | A:GitHub Actions workflow_dispatch | S:openGauss pins 6.0.5; MySQL 5.7/8.4 legs add the database lifecycle; Linux is four parallel jobs under 60 min; push runs axis --recent 3, nightly every release; PostgreSQL on a free port
release-rehearsal.yml[CG5S]: F:Exercises non-publishing release packaging, artifact verification, and the candidate's self-axis with read-only permissions | R:code:.github/workflows/release.yml,code:internal/safety/files.go,code:scripts/blackbox/mcp_upgrade.py | A:- | S:Its action pins must equal release.yml's, enforced by internal/safety; make axis-self runs the packaged linux binary in both axis roles, so a shape premise expiring with this version fails pre-tag
release.yml[CG9L]: F:Builds, keyless-signs, attests, verifies, and conditionally publishes exact 16-asset GitHub releases with version-derived prerelease and latest state | R:code:.goreleaser.yml,code:scripts/release/manifest/main.go,code:scripts/release/manifest/signed_release.go,code:scripts/release/manifest/signed_bundle.go,code:docs/supply-chain.md | A:workflow_dispatch,push tags v* | S:Dry runs cannot publish; tag publication requires the peeled tag to equal remote main plus successful exact-SHA Fast, Full, Rehearsal, and signed dry-run gates; the dry run takes its version from the dispatch input, whose default is the version last cut, so a new version must be passed or it rebuilds an existing tag; binaries and manifest share the version, full commit, UTC commit date, and go.mod toolchain

===/<repository>/cmd/aoci/===
main.go[CG8T]: F:Starts the aoci process, delegates to the CLI root command, and maps command errors to process exits | R:- | A:- | S:MCP stdio stdout is reserved for JSON-RPC; all process logging must remain on stderr

===/<repository>/docs/===
agent-integrations.md[CG5M]: F:Documents Codex, Claude Code, Cursor, OpenCode V1, and Qoder setup, multi-repository sessions, host-config governance, approval routes, compaction reload | R:code:internal/hooks/opencode.go,code:internal/hooks/codex.go,code:internal/cli/init_gitignore.go,code:internal/cli/mcp.go | A:aoci init --agent opencode | S:Refresh or reopen only when the session has not loaded the server; a hand-made host config is ignored before the first scan; OpenCode is V1 only; Qoder shares .mcp.json; returned commands carry --repo
cognition-refresh.md[CG5M]: F:Defines checkpoint reasons, delivery receipts, refresh generations, the session line, probe, compaction handoff limits, capacity stop, and post-change alignment | R:code:spec/public/aoci-cognition-refresh-v1.txt,code:internal/mcptools/overview_capacity.go | A:- | S:Probe only with no known compaction, its pass enables delta_since; after compaction only a full Overview restores cognition; capacity_stop answers a compacted reload, a confirmed delivery clears it
cognition-volumes.md[CG5L]: F:Explains Volume-first init, authoring and parallel batches, the once-per-process contract, lifecycle routing, terminal_proof, observe review, optimization | R:code:spec/public/aoci-cognition-volumes-v1.txt,code:spec/public/aoci-index-format-v1.txt,code:spec/public/aoci-database-evidence-v1.txt,code:docs/managed-scope-and-budget.md | A:Public Volumes and lifecycle guide | S:DB authoring never reconnects; terminal_proof closes the final Apply, orphans as removals; observe review rides the auto batch; roots /<repository> since 0.2.0; next_commands carry --repo
database-cognition-authoring.md[CG5M]: F:Documents evidence-bound model authoring and atomic application of Database Cognition entries for Volumes repositories | R:code:docs/cognition-volumes.md | A:aoci_maintain,aoci_update_entry | S:Database Cognition uses ordinary no-argument Maintain and the complete current machine batch; the 64 KiB byte gate is the operative page bound; status --deep and index score remain Legacy-only
database-evidence.md[CG5L]: F:Documents source setup, catalog-only collection, snapshots, Baselines, drift, and acceptance for PostgreSQL, MySQL 5.7.6+, openGauss, and file-based SQLite | R:code:spec/public/aoci-database-evidence-v1.txt,code:internal/dbevidence/collector.go,code:internal/dbevidence/collector_sqlite.go,code:third_party/openGauss-connector-go-pq.PROVENANCE.md,code:docs/mongodb-collection-evidence-profile.md | A:Database Evidence developer guide | S:openGauss 6.0.5 A/PG, verify-full; MySQL gates CHECK, index expr, visibility by version, no MariaDB; SQLite may touch -shm; failures advance nothing; snapshot prints the accept line; MongoDB: proposal
getting-started.md[CG5S]: F:Guides the first week: install and initialize, a teammate's clone, connect the Agent and build the index, keep it aligned on every task | R:code:docs/install.md,code:docs/cognition-volumes.md | A:- | S:Three safety-test anchors verbatim, no-argument aoci_maintain on one line; scan before Guide, read init's build cost first; five everyday commands match root help; a clone: init --agent, never scan
install.md[CG5M]: F:Documents source builds and layered verification of exact signed 16-asset releases using checksums, identity, signatures, attestations, SBOMs, and manifest | R:code:docs/supply-chain.md,code:.github/workflows/release.yml,code:scripts/release/manifest/main.go | A:sha256sum -c,cosign verify-blob,gh attestation verify | S:No runtime dependency on gh, Cosign or Go; scanning a Git tree needs host git; bundle verify needs no login but may need a Sigstore root; api.github.com serves assets when github.com is unreachable
localization.md[CG5T]: F:Defines locale authority, asset parity, the Volumes Locale switch, prospective Entry language, and runtime text consistency rules | R:code:internal/config/config.go,code:internal/mcptools/server.go,code:internal/cli/locale_switch_transaction.go | A:- | S:Git's stderr after a failed inventory query is the one untranslated exception; the Volumes switch rewrites only the Root marker with config and Baseline, Legacy stays read-only
managed-scope-and-budget.md[CG5L]: F:Explains scope roles, governed changes, approval, activation, posture, CLI or MCP observe review, onboarding, starter rules, the exclusion kinds, budgets | R:code:spec/public/aoci-managed-scope-and-budget-v1.txt,code:internal/volumegovernance/facts.go,code:internal/cli/scope_activate.go,code:internal/fs/safe_inventory.go,code:internal/managedscope/starter.go,code:internal/mcptools/tools_observe_review.go | A:- | S:S hard limit = Meta rune quota; non-Git root reads child Git; v2 name rules, starter rules, root list: init-only; rules+Observe merge: activate --reviewed-by; pre-scan exclude batches
overview-delivery.md[CG5M]: F:Documents Overview chunk transport, v1/v2 cursors, guarded reuse, result-size declaration, Challenge pass share, split proof, capacity stop, L5 deltas | R:code:internal/mcptools/tools_read.go,code:internal/mcptools/overview_session_v2.go,code:internal/mcptools/overview_capacity.go | A:- | S:Result-size declaration is static, no capability probe; v2 token never reconstructed, failures restart at Chunk 1; delta_since needs a probe pass; the guard checks sources via the fingerprint cache
rollback.md[CG5T]: F:Provides safe binary rollback, conditional MCP process refresh, and layout-appropriate post-rollback verification | R:code:docs/upgrading.md | A:- | S:A host-wide restart is unnecessary when its MCP integration can reload and prove the replacement process; Volumes close through Verify, Check, and Guide, while status --deep remains Legacy-only
safe-inventory-and-scope-refresh.md[CG5T]: F:Explains Safe Inventory exclusions and sensitive-name rule sets, the Managed Scope route for changing a Baseline's scope, and the retired Legacy refresh | R:- | A:- | S:An ignored directory collapses to one line only when every file is a hard exclusion; exclude_root_dirs names are hard at the root and where git ignores them; sensitive_name_rules v2 is a Scope Change
supply-chain.md[CG8M]: F:Defines release assets, signing, provenance, the 26-module license audit with its driver table, and reproducible verification of the patched Connector | R:code:.github/workflows/release.yml,code:THIRD-PARTY-NOTICES,code:scripts/check-licenses.sh,code:scripts/check-opengauss-connector.sh,code:go.mod,code:internal/dbevidence/driver_pin_contract_test.go,code:third_party/openGauss-connector-go-pq.PROVENANCE.md | A:make release-check | S:go mod verify does not cover a local replace; the connector gate must verify origin and sums, replay the canonical patch, and byte-compare the complete tree; the driver audit table is a released declaration, so a row may change only when go.mod changes with it, never by hand; the SQLite translation's MIT-0 recognition binds one version, no replacement, and the exact license hash
troubleshooting.md[CG5L]: F:Diagnoses MCP identity, scope, dialogs, authoring, stdio, repair, drift, recovery, Ledger, excluded names, submodules, E scale, Legacy, big indexes, slow calls | R:code:internal/baseline/fingerprint_cache.go,code:docs/upgrading.md,code:docs/cognition-volumes.md,code:internal/ui/server.go,code:internal/index/parser.go,code:internal/cognitiontxn/transaction.go,code:internal/mcptools/tools_remove_volumes.go | A:- | S:Disk bytes do not prove MCP identity: self-reported as service_binary_replaced_on_disk; a renamed tree closes via removals; a pending exclude is no orphan until activated; old roots: index relocate
uninstall.md[CG5T]: F:Explains removal of the binary, host integration, and optional repository-local AOCI assets | R:- | A:- | S:-
upgrading.md[CG5M]: F:Defines safe upgrade, artifact checks, MCP refresh, runtime identity, scope path migration, in-flight approvals, Legacy read-only, the migration steps, rollback | R:code:docs/install.md,code:docs/rollback.md,code:spec/public/aoci-managed-scope-and-budget-v1.txt,code:internal/migrationapply/mapping.go,code:internal/cognitionplan/validate.go | A:- | S:Approvals bind the preview envelope, not the plan; rc19 drops exclude_root_dirs; 0.1.x answers scope_change_required on v2; an aligned apply carries terminal_proof; next_commands carry --repo
windows-host-agent.md[CG5L]: F:Documents Windows host integration, runtime identity, Guide execution, PowerShell-safe workflows, and the no-staging-files rule for Volumes authoring batches | R:code:docs/cognition-volumes.md | A:- | S:Every section is the Volumes route since 0.2.0 (Legacy is read-only); the cross-layer test needs every auto, cognition, refresh status and reason token present; FRAS v2 limits bind F
zh-cn-contract-authority.md[CG5T]: F:Defines the authority order for Chinese contracts, machine facts, Guide output, and runtime assets | R:- | A:- | S:-
contract-authority.md[CG5T]: F:Provides the English rendering of the contract-authority order and conflict handling for fact sources | R:code:docs/zh-cn-contract-authority.md | A:- | S:-
windows-host-agent.en.md[CG5M]: F:English rendering of the Windows host-agent and PowerShell 5 contract with pointers to the English authorities | R:code:docs/windows-host-agent.md,code:docs/cognition-volumes.md | A:- | S:The Chinese original stays normative and is byte-locked by cross-layer and CLI tests; edits land additively there first and this rendering follows without its own locks
engine-library.md[CG5S]: F:Explains embedding the kernel: reading cognition, Overview, governance, and identity, running the tools in process, version identity, and the import caveats | R:code:spec/public/aoci-engine-library-v1.txt,code:examples/engine-embed/main.go | A:- | S:The connector replace and the one-Locale-per-process limit are stated as version limitations, not library terms
mongodb-collection-evidence-profile.md[CG3S]: F:Records a proposed catalog-only MongoDB collection Evidence profile from #135: identity, listCollections/listIndexes facts, two-pass consistency, acceptance | R:code:docs/database-evidence.md,code:spec/public/aoci-database-evidence-v1.txt | A:- | S:A proposal, not a contract; no mongodb source yet

===/<repository>/examples/minimal-repository/===
README.md[CG5T]: F:Explains the isolated minimal Go example used to demonstrate AOCI repository integration | R:- | A:- | S:-
go.mod[CG5T]: F:Declares the independent minimal-example Go module | R:- | A:- | S:-

===/<repository>/examples/minimal-repository/counter/===
counter.go[CG5T]: F:Implements the small counter behavior used by the standalone example module | R:- | A:- | S:-

===/<repository>/internal/authoringcontract/===
contract.go[CG8M]: F:Assembles Locale-bound Code and Database authoring guidance with starter-aware calibration from formal Meta and machine contracts | R:code:internal/index/dict.go,code:internal/index/quota.go,code:internal/cognition/authoring_example.go,code:internal/machinecontract/numeric.go,code:textassets/model_prompt_assets.go | A:CurrentMachineFacts,ParseMeta,Build,Assemble | S:Formal Meta bytes are never substituted; EG/EI calibration is selected only when exact official starter definitions match, while custom and legacy Meta retain deterministic dictionary-authoritative fallback; the transport instruction tells the model to author inline, mind token bands for CJK, and re-Maintain after context loss; the locale instruction makes the project Locale prospective: candidates in it, older Entries untouched

===/<repository>/internal/baseline/===
baseline.go[CG9L]: F:Defines the versioned repository fingerprint baseline, its Managed Scope receipt, and deterministic serialization | R:code:internal/baseline/process_memo.go | A:- | S:Raw SHA-256 is authoritative; normalized line-ending and gofmt hashes are diagnostic, a missing Role means Legacy Index, and the receipt's authorization mode is the active governance posture that proves later mode transitions; Load answers from the process memo by the bytes' digest with a fresh header and a copied file map
detect.go[CG9L]: F:Snapshots repository fingerprints and classifies Index/Baseline drift, including optional line-ending equivalence | R:code:internal/baseline/fingerprint_cache.go,code:internal/baseline/hash.go,code:internal/baseline/baseline.go,code:internal/fs/walk.go,code:internal/fs/safe_inventory.go,code:internal/index/types.go | A:Snapshot,SnapshotWithInventory,Detect,DetectWith,EquivalentFingerprints,IsStaleFileWith | S:Line-ending equivalence is opt-in and falls back to raw SHA-256 when either normalized digest is absent; per-file snapshot hash failures remain explicit warnings; isExcludedRel delegates the configured lists to fs.ConfiguredExclusionSource because a private copy drifted on exclude_root_dirs and reported an Entry under backup/ as an orphan, and classifies built-in names under the configured sensitive_name_rules so drift sees the inventory's exclusions; SnapshotWithInventory hashes through the fingerprint cache and, as it walks the whole inventory, prunes the cache to it on save
hash.go[CG7M]: F:Computes raw, CRLF-normalized, and gofmt-derived identities for files and in-memory postimages | R:code:internal/baseline/baseline.go | A:HashFile,HashFileReusing,HashBytes,IsFormatOnlyChange | S:Raw SHA stays authoritative for CAS and staging; binary or over-4MiB input degrades to raw-only, and reuse needs raw, size, and normalized digests to agree first
scope_detect.go[CG7S]: F:Separates Index-role governance drift from Observe-only fingerprint drift against the active Managed Scope Baseline | R:code:internal/baseline/baseline.go,code:internal/index/types.go | A:DetectManagedScope | S:Callers must first prove desired and active policy identities match; direct policy edits are Scope Change, never permission to reinterpret Baseline roles
fingerprint_cache.go[CG8M]: F:Remembers each path's fingerprint and line count beside its size and mtime under .aoci, so an unchanged file costs a governance call one stat, not a read | R:code:internal/baseline/hash.go,code:internal/fs/countlines.go,code:internal/cli/init_gitignore.go | A:OpenFingerprintCache,HashFile,FileLines,Save,SetFingerprintCacheWrites,FingerprintCacheWritesEnabled | S:Runtime asset git-ignored by the init boundary, outside Baseline, CAS, and every identity: a hit returns the bytes' digest, a bad or foreign file hashes every path; trust is same size and mtime hashed two seconds after the mtime (git's racily-clean window), so a rewrite keeping both is unseen though git catches it by ctime; AOCI_FINGERPRINT_CACHE=off hashes everything; the status page, scan --dry-run, and status never save; Save(prune) drops unseen paths, so only whole-tree walks prune; opens are memoized by digest, each with its own map; KnownLines answers only a trusted entry, never reads
process_memo.go[CG8S]: F:Remembers the decoded Baseline and fingerprint cache per path by the digest of their bytes, so a process decodes each document once | R:code:internal/baseline/baseline.go,code:internal/baseline/fingerprint_cache.go,code:internal/managedscope/memo.go | A:ProcessMemoEnv,ProcessMemoDisabled | S:A hit is a fresh value: the Baseline header is decoded again from its own JSON and the file map copied, so UpdateOne on what a caller got never reaches the next caller, and each cache open gets its own entry map to mutate and save; a rewritten file is a new digest, never a stat-based key, which a same-second rewrite would fool; AOCI_PROCESS_MEMO=off disables every in-process memo, the evaluation memo included

===/<repository>/internal/businesssource/===
manifest.go[CG8M]: F:Builds deterministic public-source manifests without reading excluded secrets or runtime data | R:code:internal/fs/git_command.go,code:internal/fs/git_head.go | A:BuildFromState,ErrScopeChangeRequired | S:Managed manifests include Index and Observe, exclude formal cognition and Exclude paths, and omit GeneratedAt from aggregate identity; a scope-change refusal is a sentinel a caller recognises without matching text; the Safe Inventory is built only on the legacy branch, through one Profiler; a managed manifest takes inventory and fingerprints from managed state, and BuildFromState takes that state from the caller, deferring to Build without a Managed Scope or budget block, so its bytes equal a fresh Build's; GitHead comes from the files git keeps when GitHeadFast understands them, else from git

===/<repository>/internal/capability/===
manifest.go[CG8S]: F:Builds the machine capability manifest for CLI, MCP, layouts, schemas, TTY and host-dialog interactions, and PostgreSQL, MySQL, openGauss, and SQLite Evidence | R:code:internal/machinecontract/capabilities.go,code:internal/cognition/loader.go,code:internal/machinecontract/human_approval.go | A:capability-manifest/v1 | S:openGauss and SQLite Evidence and host_dialog are additive; host_dialog's available_for and terminal_only_for partition tty.required_for, so the dialog never serves an action the terminal does not, and reversal and both rollbacks stay terminal-only; mcp_protocols lists the negotiated MCP revisions, newest first, beside mcp_protocol; the nine-tool MCP name identity is unchanged; baseline_scope_refresh and ordinary_legacy_scope_reduction left in 0.2.0-rc1; parallel_batches names L4, overview_delta and the delta modes L5, locale_switch and locale_resume the Locale transaction

===/<repository>/internal/cli/===
check.go[CG8L]: F:Runs aggregate repository checks and reports structural, governance, scope, and recovery failures | R:code:internal/volumegovernance/escale.go,code:internal/cli/volume_governance_render.go | A:- | S:In Legacy layout (read-only since 0.2.0), RawMissing alone, Orphan, line-ending-only, S-quota, and tagparse are informational; actionable debt, enforced budget, or Locale migration can block and the Entries issue points at migration. Under Volumes the E scale audit is JSON e_scale, never an issue or exit code; Check's Ledger event keeps result for the run and the verdict in check_passed, with governance_result and next_action; a failed Volumes check lists drift paths and the next step via the shared renderer; Legacy prints the read-only hint and an S hint that points past the migration
cognition_system.go[CG8S]: F:Exposes narrow system relation, lineage, impact, and evolution projections over cognition | R:code:internal/cognition/system_projection.go,code:internal/jsonstrict/duplicate.go | A:- | S:A snapshot read from disk rejects case-colliding duplicate keys before strict decoding; every projection is derived and unpersisted
init.go[CG8L]: F:Initializes Volume-first cognition, team configuration, baseline skeletons, host integration, line-ending normalization, and diagnosable initial-scope blocks | R:code:internal/hooks/installer.go,code:internal/managedscope/proposal.go,code:internal/cli/init_gitignore.go,code:internal/config/cognition.go,code:internal/config/config.go | A:aoci init --agent opencode,aoci init --agent qoder | S:Fresh repositories default to production Managed Scope, policy-bound auto only when machine approval is safe; a fresh config moves ambiguous artifact names into exclude_root_dirs, an existing one keeps its lists and automation; init never overwrites maintainer files; it writes the host-config ignore here, as roles freeze at the first scan, so it also prints the first-build estimate and does not run scan; a Git-ignored host config never advances an existing Baseline (a clone's init --agent is inert); --agent claude widens transport defaults; only a custom index_path gets the Legacy skeleton
mcp.go[CG8T]: F:Runs the AOCI MCP stdio server with protocol output isolated on stdout | R:- | A:- | S:stdout is reserved exclusively for JSON-RPC; startup emits no banner or version and never performs an automatic scan
root.go[CG8L]: F:Constructs the aoci root command, global flags, version identity, locale, command tree with its everyday group, and runs one in-process invocation | R:code:internal/cognitiontxn/transaction.go,code:internal/buildinfo/buildinfo.go | A:- | S:MCP stdout is an unbuffered JSON-RPC-only stream; ordinary --json emits at most one ASCII-safe JSON object on Windows; a command that already wrote a report returns only the exit code; the recovery gate opens only what every pending receipt kind allows (Legacy header receipt: reads only, 0.1.x closes it; locale: only config set locale, same target; relocate: only index relocate); executeCLIWithInput resets flags, binds stdio, scopes the locale per run, so tests never touch package flags; hooks load config read-only and fall back to the default locale; version identity aliases buildinfo
scan.go[CG8M]: F:Builds Safe Inventory fingerprints, refuses to baseline without the Volumes it governs, and establishes or refreshes the governed Baseline | R:code:internal/baseline/fingerprint_cache.go,code:internal/fs/git_ignore.go,code:internal/scopechange/authorization.go,code:internal/cli/scan_skipped.go,code:internal/cli/scope_rule_batch.go | A:- | S:--force cannot advance an existing Managed Scope Baseline: the refusal names Maintain, remove_entry, and scope activate; --dry-run never writes, fingerprint-cache saves included, but still refuses a scan that would omit a git-hidden formal asset, since publishing that Baseline makes the omission durable; announces skipped sources, the first-build estimate, and how many git submodules it left alone, as gitlinks are boundaries, not files; policy is reloaded under the index lock, so an exclusion batch saved while scan waited is seen
scope.go[CG8L]: F:Implements managed-scope policy, budget, review, authorization, Apply, activation, recovery, and Volumes-aware status commands in three help groups | R:code:internal/volumegovernance/facts.go,code:internal/scopechange/plan.go,code:internal/managedscope/evaluate.go,code:internal/baseline/scope_detect.go,code:internal/cognition/ownership.go,code:internal/cli/scope_rule_batch.go | A:aoci scope | S:Policy and budget edits need a Scope Change; under Volumes the budget spans all assets; brace globs and enabled file rules naming a formal asset are refused at add or edit; explain judges a future path under the Root's layout, naming gitlinks and credential rules; Volumes status drift is CodeDrift: held sources skipped, never authoring targets; Volume drift refusals add a recovery hint; approve asks for yes, --actor defaults human-operator, no TTY offers host_dialog; an applied change names the orphans it leaves; rule add takes repeated --pattern only before the first scan
update_entry.go[CG8S]: F:Provides the human CLI for one previewed or committed Entry update through the shared atomic write and Baseline pipeline | R:code:internal/mcptools/tools_write_batch.go,code:internal/cli/stdin_limit.go | A:- | S:A real write requires the current raw source SHA; preview may omit it, repairable failures return scoped findings without starting formal writes, stdin is bounded by the Entries request limit, --entry with --stdin is refused before any write, and a Legacy layout answers legacy_read_only_migrate_required
verify.go[CG8L]: F:Verifies structural validity, source alignment, governance, relations, budgets, and recovery state | R:code:internal/volumegovernance/escale.go,code:internal/cli/volume_governance_render.go | A:- | S:Verify never advances formal Index or Baseline, but it may write Verify History and Ledger; raw Missing remains visible while exit status counts only unresolved actionable, pending, orphan, stale, and unbaselined debt; drift counts dedupe a path listed under both Missing and Unbaselined; the E scale audit (e_scale) is computed after the report and printed last, never in the exit code; its Ledger event keeps result for the run and the verdict in check_passed; the Volumes human text is verdict, drift paths, and next step from the shared renderer, and History keeps it
business_source.go[CG7T]: F:Exposes deterministic business-source manifest inspection through the CLI | R:- | A:- | S:generated_at defaults to the current UTC second; callers needing reproducible manifest bytes must provide --generated-at; the error keeps its cause so git's stderr prints
capabilities.go[CG7T]: F:Prints the versioned machine capability manifest without network access | R:- | A:- | S:-
cli_help_contract.go[CG7M]: F:Registers localized command help while preserving machine schema and protocol authority | R:- | A:- | S:Help asset failures are surfaced for only the invoked command; they never panic or silently fall back to duplicated hardcoded text
cognition_bootstrap.go[CG8M]: F:Routes governed Cognition Bootstrap preparation, review approval, Apply, status, resume, and rollback commands | R:code:internal/bootstrapapply/prepare.go,code:internal/bootstrapapply/transaction.go,code:internal/cli/host_interaction.go | A:aoci cognition bootstrap | S:Review approval here is the terminal route: a plain summary and the answer yes in a TTY, saved with --out-file, --actor defaulting to human-operator; the dialog route is aoci_maintain human_approval through onboarding; rollback confirms the same way and answers the interaction contract without a TTY; policy-bound auto uses a separate receipt and never permits model self-approval
cognition_layout.go[CG7T]: F:Enforces Legacy-only preconditions for CLI cognition and governance writes and for the read commands documented Legacy-only | R:code:internal/cognition/loader.go,code:internal/config/config.go,code:internal/cli/status.go | A:- | S:Missing cognition is allowed only for initialization; any Volumes v1 layout, even incomplete, fails before a Legacy write can mutate state, and the read guard resolves that same verdict, not a copy
cognition_migration.go[CG7L]: F:Implements governed Legacy-to-Volumes migration CLI workflows and recovery commands | R:code:internal/cli/host_interaction.go,code:internal/migrationapply/approval.go | A:- | S:approve --out-file feeds onboard apply; mapping template --out-file never overwrites; prompts are a summary plus yes, --actor defaults human-operator; reversal and rollback stay terminal-only
cognition_onboard.go[CG8M]: F:Exposes persistent model-authored onboarding from session start and evidence batching through preview, preparation, Apply, resume, status, and abort | R:code:internal/onboarding/workflow.go,code:internal/bootstrapapply/prepare.go,code:internal/migrationapply/prepare.go,code:internal/jsonstrict/duplicate.go,code:internal/cli/onboard_next_commands.go | A:aoci cognition onboard | S:Review preparation returns a person's approval boundary: the terminal command and, when the team channel admits it, host_dialog_request for aoci_maintain human_approval; policy-bound auto preparation does not make the model an approver; next_commands ride output wrappers embedding the result types, so the persisted session never carries them; human output prints each next command, and prepare prints the write count, the dialog route first when admitted, the terminal command, and the apply command instead of JSON; confirmation_phrase is yes; a completed apply carries terminal_proof
cognition_plan.go[CG7M]: F:Routes deterministic cognition bootstrap, migration, and candidate-validation planning commands and writes planner artifacts to operator-chosen paths | R:code:internal/fs/atomic.go | A:writePlannerArtifact,validatePlannerOutput | S:An artifact path is validated before any human is asked, because a spent confirmation cannot be reused; the file is created only when absent and is owner-readable while it can stand in for that human
command_localization.go[CG7M]: F:Applies localized command names, help text, command groups, and errors without changing machine tokens | R:code:textassets/ui.go | A:- | S:A command or flag absent from the hand-kept maps renders package-init English under every locale; group titles end with a colon and refresh with the locale; an unregistered group member panics
config.go[CG7L]: F:Implements team configuration list, merged-value get, and governed base-layer set commands, with typed --json output | R:code:internal/config/config.go,code:textassets/catalog.go,code:internal/fs/safe_inventory.go,code:internal/cli/locale_switch_transaction.go | A:aoci config list,aoci config get,aoci config set | S:Set writes the team layer only; locale runs the switch transaction, which saves it, then needs an MCP restart; directory lists are names; absent sensitive_name_rules is v1; parallel 1..4
database.go[CG7M]: F:Registers database evidence commands and manages credential-free source declarations, readiness checks, and read-only catalog inspection | R:code:internal/dbevidence/config.go,code:internal/dbevidence/access.go,code:internal/dbevidence/collector.go | A:aoci database,aoci database source | S:Config holds a credential env-var name, never a secret, SQLite only its --path; add, list, access never open the file; source errors name operation, object; a missing --source lists declared sources
database_cognition.go[CG7S]: F:Implements evidence-bound Database Cognition status and bootstrap workflows with a stable outer error and redacted failure diagnostics | R:code:internal/databasebootstrap/prepare.go,code:internal/dbcognition/state.go,code:internal/machinecontract/status.go | A:aoci database cognition status,aoci database cognition bootstrap,database_bootstrap_stopped,cause_code,safe_next_action | S:Stopped-bootstrap Details never include wrapped errors, source IDs, paths, endpoints, or credentials; unknown failures collapse to the generic stopped cause
database_evidence.go[CG7S]: F:Implements Database Evidence bundle access, independent baseline acceptance, and Code-context projection for table cognition | R:code:internal/dbevidence/store.go,code:internal/dbevidence/config.go,code:internal/databasebootstrap/transaction.go,code:internal/cognition/impact.go | A:aoci database evidence,aoci database baseline accept | S:Bundles expose catalog structure only, business_data_read=false; bundle and accept refuse a snapshot of a replaced selection; accept binds --snapshot-sha, auto-bootstraps only via its transaction
database_snapshot.go[CG7S]: F:Implements database catalog snapshot capture, cached inventory, and live drift verification commands | R:code:internal/dbevidence/collector.go,code:internal/dbevidence/store.go,code:internal/dbevidence/config.go | A:aoci database snapshot,aoci database inventory,aoci database verify | S:Inventory is offline and refuses a snapshot of a replaced selection; snapshot and verify replace Evidence after a complete capture; engine_not_implemented is config; snapshot prints the accept line
doctor.go[CG7M]: F:Diagnoses repository and cognition assets, Agent integrations, exclusion gaps, and sensitive-name coverage | R:code:internal/config/config.go,code:internal/hooks/status.go,code:internal/fs/safe_inventory.go | A:aoci doctor | S:No network probe since 0.2.0; the exclude-gap hint reads raw team JSON, silent without exclude_dirs; the sensitive-name hint lists index paths v2 drops, reading no content
hook.go[CG7M]: F:Implements the hidden pretool and codex-compact hook runtimes that normalize host input and delegate pre-write governance checks | R:code:internal/hooks/pretool.go,code:internal/hooks/claude.go,code:internal/config/paths.go,code:internal/cli/stdin_limit.go | A:aoci hook pretool,aoci hook codex-compact | S:Hook failures, missing paths, and oversize stdin all fail open; Claude blocks via exit 2 with stderr, the generic code is 4, and codex-compact emits context only, so it bypasses the recovery gate
host_interaction.go[CG7M]: F:Defines the terminal confirmation (summary plus yes), its rejection guidance, the host-dialog route, the non-TTY boundary, and the exact command it prints | R:code:internal/mcptools/tools_human_approval.go,code:internal/config/approval.go,code:internal/cli/root.go | A:- | S:Prompts go to stderr, cobra writer buffered; only yes (any case) approves; non-TTY is a zero-write boundary, host_dialog_request if admitted; the exact command adds --repo <root> unless given
index.go[CG7M]: F:Registers the index inventory, header show, score, agent guide, and relocate commands that survive the Legacy retirement | R:- | A:- | S:No Legacy authoring subcommand since 0.2.0; relocate is the one write, a receipted transaction; loadCognitionSetForCLI loads every read, loadIndexForCLI adds the Volumes refusal for document readers
index_agent_guide.go[CG8L]: F:Renders Volumes governance state into host-executable Guide JSON and answers a Legacy layout with the blocked read-only guide that names the migration | R:code:internal/cli/index_agent_host_contract.go,code:internal/mcptools/tools_maintain_volumes.go,code:internal/mcptools/tools_maintain_budget.go,code:internal/volumegovernance/facts.go,code:internal/machinecontract/lexical.go,code:internal/cognitiontxn/transaction.go,code:internal/ui/snapshot.go | A:aoci index agent guide | S:Guide is read-only; a blocked Guide carries per-blocker remediation (scan, review then Guide, activate, budget levers, receipt closure), instructions, commands and stop ahead of findings and governance; evidence_required names the snapshot and accept commands and the sources; buildVolumeAgentGuide is the one assembler; executable_targets omits informational findings; Legacy gets the blocked read-only guide: stage legacy_read_only_migrate_required, onboard command bound, pending receipts named with closures; the batch projection takes the verdict's snapshot; commands bind binary and --repo
index_agent_host_contract.go[CG7M]: F:Binds every Volumes Guide command to the absolute executable and --repo of its repository, shell-safe for POSIX and PowerShell, evidence commands included | R:code:internal/cli/index_agent_guide.go,code:internal/cli/onboard_next_commands.go | A:- | S:The bound field list is hand-kept, so a new Guide command ships unbound unless added; finalization needs an absolute executable and a quotable absolute root, never bare aoci or an unrooted command
index_agent_text_assets.go[CG7T]: F:Renders localized Guide text lines from registered runtime assets | R:- | A:- | S:Load failure returns an ID-bound diagnostic without panic or hardcoded fallback
index_header.go[CG7T]: F:Wires the read-only index header show command that prints a Legacy Header or the Volumes Meta dictionary | R:- | A:aoci index header show | S:The Legacy Header draft, diff, and apply commands are retired since 0.2.0; nothing here writes
index_score.go[CG7S]: F:Runs and renders the nine-dimension quality score of a Legacy or Volumes repository, or one selected diagnostic dimension | R:code:internal/indexgen/score.go,code:internal/indexgen/score_volumes.go,code:internal/volumegovernance/facts.go,code:internal/volumegovernance/escale.go | A:aoci index score | S:tagparse shows nonparseable-tag Warnings, never Check blockers; --dim drops the sample limit, keeps the whole judgment; a Volumes set scores from Assess and the E scale audit, exit 2 if Assess fails
init_gitignore.go[CG7M]: F:Creates the default-deny .aoci/.gitignore boundary, ignores the host configuration init wrote and its backups, and normalizes line endings for new repositories | R:code:internal/fs/atomic.go,code:internal/fs/git_command.go,code:internal/cli/init.go | A:- | S:Maintainer files are never rewritten, which outranks the line-ending protection; the host block must precede the first scan, since roles freeze there and later removal needs an approved Scope Change
init_messages.go[CG7S]: F:Renders deterministic localized initialization results and next steps | R:- | A:- | S:The automation-mode hints and the Legacy skeleton header hint come from init text assets whose protocol tokens and goldens are test-locked
init_volumes.go[CG7S]: F:Creates parseable Root, Meta, and Code Volume skeletons for new repositories | R:- | A:- | S:Meta and empty Code are created before Root activation; retries accept only exact deterministic regular-file postimages, and init never authors Code Entries or Database semantics
json_ascii.go[CG7S]: F:Encodes stable machine JSON with ASCII-safe escaping where protocol compatibility requires it | R:- | A:- | S:-
json_error.go[CG7S]: F:Maps CLI failures to stable machine-readable error envelopes and exit codes | R:- | A:- | S:MachineCode overrides generic exit mapping; successful --json payloads remain unwrapped, and this envelope is emitted only before any business JSON was written
locale_migration.go[CG7M]: F:Handles configuration-only Locale changes (no index or Legacy index), reports a pending Legacy migration's coverage, and refuses init's change of a Volumes Root | R:code:internal/config/config.go,code:internal/index/parser.go,code:internal/hooks/installer.go,code:internal/cli/locale_switch_transaction.go | A:- | S:A Legacy index keeps the Locale it was written in (locale.legacy_read_only); a Volumes Root is refused here (locale.volumes_use_config_set) because only the switch transaction may rewrite it
remove_entry.go[CG7T]: F:Registers the human CLI for previewing or removing one named cognition Entry through the shared guarded pipeline | R:code:internal/mcptools/tools_remove.go | A:aoci remove-entry | S:CLI deliberately passes orphanOnly=false, so a human may remove a live-file Entry and surface it as Missing; MCP removal remains orphan-only, and --preview performs no write
status.go[CG7L]: F:Reports compact cognition metadata, the Volumes governance verdict, or deep Managed Scope drift and budget diagnostics | R:code:internal/managedstate/state.go,code:internal/cognitionbudget/report.go,code:internal/cli/cognition_layout.go,code:internal/volumegovernance/facts.go,code:internal/cli/volume_governance_render.go | A:aoci status | S:Legacy never rehashes, prints the read-only hint; Volumes runs Assess, cache saves off; unreadable Baseline exits 2, not missing; --deep is Legacy-only and allows a missing index
verify_render.go[CG7M]: F:Renders stable localized human Verify output and workflow-priority hints from an already computed report | R:code:internal/cli/verify.go,code:textassets/catalog.go | A:- | S:Pending Curation hints yield to actionable Missing, Unbaselined, and Stale work and defer phasing to Guide; the Legacy branch opens with the read-only hint and an S hint pointing past the migration
stdin_limit.go[CG7T]: F:Reads standard input under an explicit byte bound and reports oversize separately from a read failure | R:code:internal/cli/hook.go,code:internal/cli/update_entry.go,code:internal/machinecontract/numeric.go | A:readLimitedInput,hookInputMaxBytes | S:The bound reads maxBytes+1 because only that extra byte separates exactly-at-limit from oversize; hook input carries its own small bound and fails open while update-entry refuses
ui.go[CG7M]: F:Runs the local status page in the foreground, or with --detach as its own session that reports its URL and returns, and stops a registered page with --stop | R:code:internal/ui/server.go,code:internal/ui/detach.go,code:internal/ui/registry.go | A:aoci ui,aoci ui --detach,aoci ui --stop | S:Readiness goes to process stdout, not the buffered command writer; exits only when the page stops; foreground and detach refuse a live tokenless page until --stop; roots normalize before lookups
scope_activate.go[CG7S]: F:Activates the desired Managed Scope policy through the empty-candidate preview and Apply, pausing for approval or answering already_aligned when nothing changes | R:code:internal/cli/scope.go,code:internal/scopechange/plan.go,code:internal/scopechange/transaction.go,code:internal/cli/host_interaction.go,code:internal/baseline/baseline.go | A:aoci scope activate,--reviewed-by | S:Never prompts, approves, edits rules, or authors Entries; a pause saves an activate-* preview, a dialog request if admitted, commands as printed; --reviewed-by records the review the refusal names
scan_skipped.go[CG5M]: F:Counts the index-role files no model can author or curation keeps out, and estimates the first build's rounds, sequential and parallel, for scan and init | R:code:internal/curation/classify.go,code:internal/cli/scan.go,code:internal/volumegovernance/facts.go,code:internal/mcptools/tools_maintain_budget.go | A:- | S:Same classification Verify reports as code_skipped/code_curation_excluded; estimates run the real cuts, the parallel line the sibling cut, never rounds/N; one file and one round singular
git_query_detail.go[CG5T]: F:Prints a failed Safe Inventory git query's stderr tail and keeps causes reachable behind CLI messages | R:code:internal/fs/safe_inventory.go,code:internal/cli/root.go | A:- | S:The tail is git's verbatim text on stderr only, the one documented locale exception; causedError keeps the message so exit codes stay the same
onboard_next_commands.go[CG7S]: F:Spells each onboarding result's next_commands from session state: batch, receipt, a Migration's template then Preview, Prepare or resume, none once completed | R:code:internal/machinecontract/lexical.go,code:internal/cli/index_agent_host_contract.go,code:internal/cli/cognition_onboard.go | A:onboardingNextCommands,onboardingBatchNextCommands | S:Like the Guide's, commands carry the binary and --repo <root>; Plan and Snapshot paths filled in quoted, Host files stay placeholders; unbindable binary or root, or a completed session: none
locale_switch_transaction.go[CG8L]: F:Switches a Volumes repository's Locale as one resumable CAS transaction over the Root #Locale line, team configuration, and Baseline record of the Root | R:code:internal/cognitiontxn/transaction.go,code:internal/index/locale.go,code:internal/config/config.go,code:internal/baseline/hash.go,code:internal/cli/locale_migration.go,code:internal/cli/root.go | A:aoci config set locale | S:Meta, Code, and Database Volumes are guards checked before every publish and never written, so no Entry is rewritten and Locale is prospective; publish order is Root, config, Baseline, each against its exact preimage; the Baseline joins only when it records the Root, and a stale record stops the switch before any write; a crash leaves locale-<id>.json that only the same command and target resume while the CLI gate holds every other command; no index or a Legacy index stays prepareLocaleChange's configuration-only path; locale_switch_apply is written once, only when the Ledger is enabled
volume_governance_render.go[CG7S]: F:Renders the Volumes governance verdict, drift paths, other actionable findings, and the next step that verify, check, and status share | R:code:internal/volumegovernance/facts.go,code:internal/cli/verify.go,code:internal/cli/check.go,code:internal/cli/status.go,code:internal/machinecontract/status.go | A:- | S:Keys stay literals for the locale consumer test; next step follows finalize: baseline, recovery, scope, locale, orphan, observe, bootstrap, Evidence, authoring; informational codes never count
index_relocate.go[CG8L]: F:Rewrites an index's recorded section roots to /<repository> and names it in the Meta, as one receipted transaction over Meta, Code Volume, and Baseline | R:code:internal/index/section_roots.go,code:internal/cli/locale_switch_transaction.go,code:internal/cognitiontxn/transaction.go,code:internal/cli/root.go,code:internal/cli/index_agent_guide.go | A:aoci index relocate,--dry-run | S:Readers resolved the old headers already, so the rewrite changes what a person or model reads, not what the machine does; publish order Meta, Code, Baseline, each CAS against its exact preimage with the Root and every other Volume as guards; a Baseline record that no longer matches the asset refuses before any write; the receipt relocate-<id>.json gates every other command and the same command resumes it; verify proves every section neutral, the Meta naming the root, and the records moved; the Meta line comes from the starter template in the project Locale; Legacy is refused
scope_rule_batch.go[CG7S]: F:Adds a validated batch of directory exclusions to the desired policy before the first scan: one config write under the scan lock, stable per-directory IDs | R:code:internal/cli/scope.go,code:internal/config/scope_budget.go,code:internal/managedscope/policy.go | A:aoci scope rule add --pattern (repeated) | S:Enabled directory excludes only; a directory must exist, resolve to itself, not be formal or .aoci; ID = prefix + sha256(pattern)[:8]; a same-ID differing rule rejects the batch; a Baseline refuses

===/<repository>/internal/cognition/===
authoring_boundary.go[CG7T]: F:Enforces strict Volume authoring form only for newly created or genuinely changed Tag and R fields while preserving tolerant reads | R:code:internal/cognition/impact.go,code:internal/index/types.go | A:- | S:Unchanged dotted tags and bare legacy relations remain readable; any new or changed Tag must be compact and every changed R token must be an exact canonical code: or database identity
authoring_example.go[CG7T]: F:Validates one supplied Code or Database authoring example through formal Volume parsing and the scoped tag dictionary | R:code:internal/cognition/loader.go,code:internal/index/dict.go | A:ValidateVolumeAuthoringExample | S:The example is a machine-contract fixture with no repository Meta, so it is judged against machine-default quotas and performs no filesystem, network, or write action
identity.go[CG9T]: F:Computes typed, length-delimited SHA-256 identities for cognition assets, scopes, objects, and composite sets | R:code:internal/cognition/types.go | A:- | S:Every field is domain-separated and length-framed, so absent assets and concatenation boundaries cannot collide; identities derive from exact formal bytes and ordered descriptors
impact.go[CG8L]: F:Validates cognition candidates and derives the bounded Review, Write, and Guard sets for one atomic batch | R:code:internal/cognition/impact_graph.go,code:internal/cognition/impact_types.go | A:ResolveImpact | S:Candidate form, identity, and dictionary violations fail closed per candidate, but R never does: relations only widen Review and Guard, and no Entry is checked against another. Field limits resolve through the repository Meta declaration, so a candidate legal at Load is legal here; object-missing and already-present findings bind canonical_object_identity as their field
impact_graph.go[CG8S]: F:Projects model-authored R onto a read-only edge set that only widens the Review face | R:code:internal/cognition/impact.go | A:- | S:A token naming no managed object, or several, simply produces no edge; this projection has no diagnostic channel, so relations can never fail a write, and entry-to-entry meaning is built by the model reading the Whole-Index
impact_types.go[CG7S]: F:Defines public impact, lineage, evidence, and projection result structures | R:- | A:- | S:Candidates carry semantic or structural intent only; the relation graph has no issue channel because relations never fail a write
loader.go[CG9L]: F:Loads Legacy or Volumes cognition layouts and fails closed on invalid or mixed assets | R:code:internal/index/quota.go | A:Load,DetectLayout,RootLayout | S:Layout is selected solely by the exact first Root marker; a damaged recognized marker never falls back to Legacy. Root descriptors are validated before any declared path access, and Root, Meta, and object Volumes reject copied authority or dynamic state. Meta is assembled before any object Volume is judged, because the Root may declare them in any order and the Meta carries the quota every object is measured against. RootLayout reads only the Root's first bytes and is the one answer Managed Scope takes for whether the formal-asset pin applies
objects.go[CG9M]: F:Parses canonical Code and Database objects and validates object identity, compact tags, FRAS v2 order, and field limits | R:code:internal/index/parser.go,code:internal/index/quota.go,code:internal/cognition/registry.go | A:IsCanonicalDatabaseRef | S:Database identities are explicit database://source/namespace/table references; parsing never infers or generates semantics. The S limit resolves through index.LimitForC, which honours a Meta declaration only when it is looser than the machine default, so this error-level gate can never be tightened into refusing a Volume that already loads
ownership.go[CG7S]: F:Assigns formal assets and object identities to exactly one cognition owner and projects the business scope without them | R:- | A:FormalAssetOwner,BusinessScope | S:Database URIs are Database-owned, registered formal paths case-insensitively Root, Meta, Code, or Database, all else Code; BusinessScope strips formal paths from snapshot and Baseline; never repairs
projected.go[CG9M]: F:Validates projected Volumes v1 Root descriptors, target paths, and candidate CognitionSet bytes without activating them | R:code:internal/cognition/loader.go,code:internal/index/quota.go | A:ParseProjectedRoot,ValidateProjectedTargetPaths,BuildProjectedSet | S:Projected six-field descriptors stay separate from the active five-field loader until explicit layout activation. This is the assembler a volume commit runs, so it must resolve Meta first exactly as Load does, or a candidate legal at Load is refused at commit
registry.go[CG8T]: F:Defines the supported cognition Volume registry, dependencies, formats, and namespaces | R:- | A:- | S:Volume kinds are explicitly registered rather than inferred from filenames; callers receive a deep-copied kind-sorted registry so mutation and map order cannot change the contract
repair_findings.go[CG7T]: F:Stably orders public Repair Findings by domain, path, field, rule code, and integer candidate position | R:code:internal/cognition/types.go | A:SortRepairFindings | S:CandidateIndex remains the caller's immutable 1-based position in the complete batch and is compared numerically, not lexically
system_projection.go[CG8L]: F:Builds narrow system relation, lineage, impact, and evolution views without inventing semantics | R:- | A:- | S:All outputs are derived, non-authoritative, and unpersisted; relations naming no managed object are skipped rather than reported, because R may legitimately point at unwritten, removed, or unmanaged things; snapshot comparison observes change without evolving cognition
types.go[CG7S]: F:Defines loaded cognition sets, volumes, entries, layout modes, and formal asset metadata | R:- | A:- | S:This model is read-only; generation, maintenance, Baseline, CAS, Apply, Ledger, and Recovery remain owned elsewhere, and recognized damaged Volumes fail closed rather than falling back to Legacy

===/<repository>/internal/cognitionbaseline/===
build.go[CG8T]: F:Builds combined Code source and Database evidence baseline bindings for Volumes cognition | R:- | A:- | S:Build consumes only validated projected Volume bytes; Code bindings use source fingerprints while Database bindings use evidence identities, and exact Baseline serialization is shared by Bootstrap and Migration
verify.go[CG8T]: F:Verifies Volume objects against their current source or accepted database evidence bindings | R:- | A:- | S:-

===/<repository>/internal/cognitionbudget/===
policy.go[CG7S]: F:Defines, defaults, normalizes, resolves, and hashes Whole-Index and per-C R/S token budget policies | R:code:internal/machinecontract/managed_scope.go | A:DefaultPolicy,LegacyPolicy,Normalize,LimitFor,Identity | S:LegacyPolicy is a frozen persisted preimage every repository without a cognition_budget block resolves, so changing its literals or shape forces a Scope Change on all of them; DefaultPolicy may move
report.go[CG8L]: F:Measures Header and Entry token budgets, largest fields, enforceable violations, and S coverage by C band | R:code:internal/index/quota.go | A:EstimateTokens,RebindWholeIndexTokens,NewSCoverageTally,SFieldMaxTokens,BuildWithSQuota,ValidateEntryWithSQuota | S:Estimates are UTF-8 bytes/3 and never rewrite semantics; the Whole-Index thresholds only name the status, never a violation (an index may be read outside an Agent); enforce mode rejects an R or S hard-limit violation, observe only reports; the S limit is the band floored by the Meta rune quota (LimitForC), so an S within quota never violates and a nil quota floors at the machine default (#146). Build measures one asset and reads a quota only from a Legacy header: Volumes callers pass the Meta quota and rebind the total over the set; s_coverage follows the S bands and the hint rule lives here

===/<repository>/internal/cognitiontxn/===
transaction.go[CG9L]: F:Provides shared intent, preimage, postimage, CAS, atomic commit, and recovery transactions | R:- | A:- | S:Only exact preimage or postimage states are actionable; staged and archived bytes are immutable, other pending operations block, and a terminal Ledger event is accepted only after read-back proves idempotent completion, skipping foreign lines that do not decode (#121). Pending reads every receipt kind under .aoci/transactions (database-bootstrap, bootstrap, migration, reversal, scope, locale, relocate (layout), remove, entries, header) and any foreign .json as unknown; RejectOtherPending lets layout resumes proceed over MCP write receipts, OtherPending is the write tools' any-kind check

===/<repository>/internal/config/===
automation.go[CG7S]: F:Resolves legacy, off, review, and policy-bound auto authorization modes | R:- | A:- | S:Missing mode means legacy except proven Fresh Bootstrap, which defaults to auto; manual normalizes to absent legacy, and config.local.json cannot override team automation
cognition.go[CG7S]: F:Validates team-owned refresh, Overview chunking, Database and Code batch limits, parallel batches, the Maintain transport budget, and host transport defaults | R:code:internal/machinecontract/numeric.go | A:SetOverviewChunkTokens,DatabaseCognitionBatchLimits,CodeCognitionBatchLimit,CodeCognitionParallelBatchLimit,MaintainTransportBudget,SetHostTransportDefaults | S:Local configuration cannot override these team-owned limits; zero values resolve to machine defaults; host defaults touch only fields still at their default, and only for claude
config.go[CG8L]: F:Loads, merges, validates, and atomically saves team and local AOCI configuration | R:- | A:- | S:Team-governed fields (automation, line endings, refresh threshold, Database sources, Managed Scope, batch sizes, transport budget, parallel batches, root list, name rules, approval channel) cannot be overridden locally; never Save a merged Load back to team config; MarshalBase is Save's exact postimage; an absent team file takes the Root's #Locale marker, a markerless index zh-CN; defaultExcludeDirs backfills old files and must not change; sensitive_name_rules v1 or v2, absent in old files is rc22's; Locale materialization saves by CAS on the bytes it read
curation.go[CG7T]: F:Normalizes and matches static team curation_exclude path or subtree selectors for Missing classification | R:code:internal/config/config.go,code:internal/indexgen/missing.go | A:CurationExcluded,CountCurationExcluded | S:This policy only suppresses automatic Missing dispatch; it does not rewrite the raw Missing fact, override explicit --paths, or exempt an existing stale Entry
paths.go[CG7S]: F:Locates the canonical repository root and resolves formal, configuration, audit, and recovery asset paths | R:code:internal/config/config.go,code:internal/fs/safe_path.go | A:FindRepoRoot,AOCIPaths | S:Without --repo, root discovery completes the full upward .git search before considering .aoci, so a nearer nested .aoci cannot override the canonical Git root
scope_budget.go[CG7M]: F:Normalizes, clones, defaults, and CAS-mutates Managed Scope, cognition budget, and exact high-risk inventory opt-in configuration | R:code:internal/managedscope/policy.go,code:internal/cognitionbudget/policy.go,code:internal/scopechange/transaction.go,code:internal/managedscope/starter.go | A:SetNewProjectGovernance,MutateManagedScope,MutateInitialManagedScope,MutateCognitionBudget,MutateSafeInventoryHighRiskOptIn | S:Mutations change desired config only; active identities stay in Baseline until Scope Change applies; new-project defaults never reach old repos; initial batch needs no Baseline, under the scan lock
approval.go[CG7T]: F:Resolves the team human_approval_channel and answers whether an approval mechanism counts: only the host dialog is governed, and a nil config admits none | R:code:internal/config/config.go,code:internal/machinecontract/human_approval.go | A:EffectiveHumanApprovalChannel,AdmitsApprovalMechanism,SetHumanApprovalChannel | S:Setting the default stores it as absent, so a repository that never chose keeps its bytes; terminal and policy-bound mechanisms always pass

===/<repository>/internal/dbevidence/===
access.go[CG8S]: F:Resolves runtime-only environment credential references, or names a SQLite file route, and reports redacted access readiness without connecting or opening | R:code:internal/dbevidence/config.go | A:CredentialProvider,NewEnvironmentCredentialProvider,InspectAccess,DefaultCredentialEnv | S:Resolved credentials are never persisted or returned; v1 accepts only the environment provider; SQLite never invokes a provider and its readiness names the configured route, not file availability; an engine EngineCollectable rejects answers engine_not_implemented first
canonical.go[CG7L]: F:Canonicalizes PostgreSQL, MySQL, openGauss, and SQLite identifiers, columns, constraints, indexes, tables, and snapshots | R:code:internal/dbevidence/types.go,code:internal/dbevidence/collector.go | A:CanonicalTable,BuildSnapshot | S:Rejects invalid UTF-8, non-base tables, duplicates, unresolved facts, and cross-source references; openGauss keeps the Evidence v1 shape; only SQLite may leave a native type empty
collector.go[CG8M]: F:Coordinates bounded catalog-only PostgreSQL, MySQL, openGauss, and SQLite collection, repository-bound file paths, and redacted source-error mapping | R:code:internal/dbevidence/config.go,code:internal/dbevidence/queries.go,code:internal/dbevidence/collector_sqlite.go,code:internal/dbevidence/collector_opengauss.go,code:third_party/openGauss-connector-go-pq/connector.go | A:Inspect,Snapshot,NewCollector,NewCollectorAtRoot | S:Each collection uses one connection and one repeatable-read read-only transaction chosen per engine, so an engine without a policy fails closed before connecting; openGauss opens only through the strict connector parser, whose panic on a malformed string is recovered into a redacted error; no path reads business rows; SQLite opens a deferred read-only transaction, resolves no credential, and a relative path is anchored to the collector's root; an engine EngineCollectable rejects answers engine_not_implemented first; SourceError.Object names the table an unsupported feature stopped on
collector_mysql.go[CG7M]: F:Collects MySQL catalog metadata through reviewed read-only information-schema queries selected by server version | R:code:internal/dbevidence/collector_mysql_version.go,code:internal/dbevidence/queries.go,code:internal/dbevidence/collector.go | A:collectMySQL | S:Floor 5.7.6 (GENERATION_EXPRESSION); CHECK read from 8.0.16, index expressions from 8.0.13, visibility from 8.0.0, older servers run same-shape projections; MariaDB fails closed before any table query
collector_postgresql.go[CG7M]: F:Collects PostgreSQL catalog metadata through reviewed read-only catalog queries | R:- | A:- | S:Mid-level table = partition and parent: child linking merges into its partition facts, else evidence depends on child-name order; test-only catalogStepHook fires after tables, in the transaction
config.go[CG7M]: F:Validates and normalizes PostgreSQL, MySQL, openGauss, and SQLite source selection, credential references or file path, filters, and system namespaces | R:code:internal/dbevidence/types.go | A:NormalizeSources,NormalizeSource,Included,SourceConfigMatchesManifest | S:Credentials and timeouts are not Evidence identity; include filters never re-admit system namespaces; SQLite takes one path in main, never a URI, :memory: or credential; the path is its identity
drift.go[CG7S]: F:Classifies Database Evidence source identity and per-table structural drift against the independent accepted Baseline | R:code:internal/dbevidence/store.go,code:internal/dbevidence/types.go | A:CompareSnapshot,BuildEvidenceBundle | S:Comparison never advances the Baseline; table changes name only canonical structural components, and Evidence bundles contain no model-generated semantics or business-row data
drivers.go[CG7T]: F:Registers the reviewed pure-Go PostgreSQL, MySQL, and openGauss database/sql drivers | R:code:go.mod | A:database/sql driver registration | S:-
queries.go[CG7M]: F:Defines fixed catalog-only SQL inventories for PostgreSQL, MySQL with pre-8.0 and pre-8.0.13 index projections, and the dedicated openGauss 6.0.5 adapter | R:code:internal/dbevidence/collector.go,code:internal/dbevidence/collector_mysql_version.go,code:internal/dbevidence/collector_opengauss.go | A:- | S:No query interpolates user values or reads business rows; older MySQL index projections substitute NULL expression and YES visibility so one scanner fits all; openGauss never aliases PostgreSQL SQL
store.go[CG7L]: F:Persists and strictly reloads canonical Database Evidence snapshots and accepted Baselines for every supported engine | R:code:internal/dbevidence/canonical.go,code:internal/dbevidence/types.go,code:internal/fs/atomic.go | A:WriteSnapshot,LoadSnapshot,LoadTableEvidence,LoadBaseline,AcceptSnapshot | S:Evidence paths are content-addressed and Lstat-checked without following symlinks; Baseline acceptance requires the exact current saved Snapshot and never occurs during Snapshot write
types.go[CG7M]: F:Defines PostgreSQL, MySQL, openGauss, and SQLite source, table, column, constraint, index, Evidence, Snapshot, Baseline types and the collectable engines | R:code:internal/dbevidence/config.go,code:internal/dbevidence/canonical.go | A:EnginePostgreSQL,EngineMySQL,EngineOpenGauss,EngineSQLite,EngineCollectable | S:database and credential_env are omitempty, so a SQLite declaration writes neither; every surface asks EngineCollectable whether a source owes Evidence, and SQLite does since its collector landed
collector_opengauss.go[CG9L]: F:Collects deterministic openGauss 6.0.5 A/PG table, column, key, constraint, and index facts and rejects unsupported visible semantics | R:code:internal/dbevidence/collector.go,code:internal/dbevidence/queries.go,code:internal/dbevidence/config.go,code:internal/dbevidence/canonical.go | A:collectOpenGauss | S:Requires OpenSourceCentralized 6.0.5 in A or PG mode and ordinary permanent nonpartitioned row tables; unrepresentable constraint or index states fail closed
collector_mysql_version.go[CG7S]: F:Parses the MySQL server version and selects the version-gated catalog profile: whether CHECK is read and which STATISTICS projection a release can answer | R:code:internal/dbevidence/collector_mysql.go,code:internal/dbevidence/queries.go | A:parseMySQLServerVersion,mysqlCatalogProfileFor | S:Floor 5.7.6; MariaDB (any 'mariadb' in VERSION(), even behind the 5.5.5- prefix) or an unreadable version fails closed as unsupported_catalog_feature; three STATISTICS projections keep one shape
collector_sqlite.go[CG8L]: F:Collects ordinary SQLite table, column, key, and index catalog facts through a read-only file connection under a catalog-only authorizer | R:code:internal/dbevidence/collector.go,code:internal/dbevidence/canonical.go,code:internal/dbevidence/config.go | A:- | S:Opens mode=ro with query_only and trusted_schema(0) under an authorizer that admits catalog reads only; direct PRAGMAs defeat a business table named pragma_*; unsupported schema features fail closed rather than yielding partial Evidence, a table-level one naming its table as the error's object; read-only WAL access may still touch the -shm file

===/<repository>/internal/fs/===
atomic.go[CG9L]: F:Implements durable replacement, no-replace create or move, and exchange-based CAS with crash recovery and conflict preservation | R:code:internal/fs/atomic_exchange_linux.go,code:internal/fs/atomic_create_linux.go,code:internal/fs/lock.go | A:AtomicWrite,AtomicWriteMode,AtomicCreateCAS,ValidateCreateTarget,AtomicMoveCAS,AtomicWriteCAS | S:AtomicCreateCASMode is the mode-capped create; CAS never silently overwrites unproven third-party bytes; only plain AtomicWrite has a non-atomic Windows fallback, and that fallback renames the target to a same-directory backup instead of deleting it, restores it when the retry fails, and keeps both files when even restoration fails; AtomicWriteMode sets the exact mode even when replacing, so a private backup never inherits a broader prior mode
safe_inventory.go[CG9L]: F:Builds the deterministic Safe Inventory while excluding secrets, runtime data, generated assets, and unsafe paths under a selectable sensitive-name rule set | R:code:internal/fs/git_command.go,code:internal/fs/walk.go | A:BuildSafeInventory,BuiltInSafetyCategory,SensitiveNameUpgradeCandidates,NormalizeSensitiveNameRules | S:Exclusions classify by path, never content; Git and non-Git traversal share a boundary; a non-Git container reads each child repo through its own hardened Git (#54); exclude_root_dirs names count at the root and where git ignores them; a gitlink is git_submodule; a symlinked --repo is the Git root when os.SameFile agrees; rules identity: v1 is the absent set, v2 reads file names only, directories keep v1, templates exempt; logs and run are configured since 0.2.0 (#158); log, pid, socket files go by suffix; untracked paths come from status; ls-files only where --ignored=matching is missing
atomic_create_darwin.go[CG5S]: F:Publishes a staged file into a name that must not already exist, using the Darwin no-replace primitive with an O_EXCL copy fallback | R:code:internal/fs/atomic.go | A:- | S:exFAT answers ENOTSUP, which on darwin is a different errno from EOPNOTSUPP; the copy fallback keeps the refusal but not atomic content, so callers must verify the published digest
atomic_create_linux.go[CG5T]: F:Publishes a staged file into a name that must not already exist, using the Linux no-replace primitive with a link-based fallback | R:code:internal/fs/atomic.go | A:- | S:RENAME_NOREPLACE is a filesystem capability, not a kernel one; DrvFs refuses it and the link fallback carries the identical guarantee; the syscall is a package variable so tests replay DrvFs on ext4
atomic_create_other.go[CG3T]: F:Refuses to publish where the platform has no atomic no-replace primitive, instead of degrading to a replacing rename | R:code:internal/fs/atomic.go | A:- | S:This refusal is the contract, not a stub
atomic_create_windows.go[CG3T]: F:Publishes a staged file with MoveFileEx and no replace flag, so an existing name, directory, or reparse point is a hard conflict | R:code:internal/fs/atomic.go | A:- | S:MOVEFILE_REPLACE_EXISTING would void the guarantee
atomic_exchange_darwin.go[CG3T]: F:Uses Darwin rename exchange support for exact atomic replacement where available | R:- | A:- | S:-
atomic_exchange_linux.go[CG7S]: F:Exchanges two paths with renameat2 RENAME_EXCHANGE, emulating it with a hard link and two renames where the filesystem refuses the flag | R:code:internal/fs/atomic.go,code:internal/fs/atomic_create_linux.go | A:- | S:The emulation ends in the primitive's post-state; crash states converge via the capture name; its link-to-rename window lets a foreign rename-replace win unseen while in-place edits still fail CAS
atomic_exchange_other.go[CG3T]: F:Reports unavailable atomic exchange on platforms without a safe primitive | R:- | A:- | S:-
atomic_exchange_windows.go[CG3T]: F:Implements Windows replacement behavior for guarded atomic writes | R:- | A:- | S:-
countlines.go[CG7T]: F:Counts file lines consistently for inventory and cognition scale evidence | R:- | A:CountFileLines,CountLines | S:Empty files count zero, a final newline adds no line, an unterminated last line adds one; no binary sniffing; CountLines takes a reader so callers tee it into the digest binding the count
lock.go[CG7L]: F:Provides repository write locking with owner identity, stale-lock detection, and safe release | R:- | A:- | S:Reclaim needs age, dead owner and same-inode proof; directory fallback locks are never CAS-reclaimed; Release token-checks spare a successor; an owner gone between open and fstat reads as released
lock_owner_open_other.go[CG3T]: F:Reads lock-owner state on non-Windows platforms without following unsafe paths | R:- | A:- | S:-
lock_owner_open_windows.go[CG3T]: F:Reads lock-owner state with Windows-compatible sharing semantics | R:- | A:- | S:-
process_identity_linux.go[CG3T]: F:Captures Linux process start identity to distinguish live owners from PID reuse | R:- | A:- | S:-
process_identity_other.go[CG3T]: F:Provides conservative process identity behavior on unsupported operating systems | R:- | A:- | S:-
process_identity_unix.go[CG3T]: F:Probes Unix process liveness for lock ownership checks | R:- | A:- | S:-
process_identity_windows.go[CG3T]: F:Captures Windows process identity and liveness for lock ownership checks | R:- | A:- | S:-
safe_inventory_platform_other.go[CG3T]: F:Supplies platform-specific inventory exclusions outside Windows | R:- | A:- | S:-
safe_inventory_platform_windows.go[CG3T]: F:Handles Windows reparse points and filesystem hazards during Safe Inventory | R:- | A:- | S:-
safe_path.go[CG7T]: F:Normalizes agent-supplied repository-relative path syntax and rejects absolute, drive, UNC, empty, or parent-escape forms | R:code:internal/fs/walk.go,code:internal/fs/atomic.go | A:NormalizeRelPath,RelPathMessageKey | S:Lexical only; callers own root binding, symlinks and access; refusals are sentinels with machine-token text mapped to catalog keys; UNC precedes absolute; the drive check reruns on the cleaned path
walk.go[CG7S]: F:Walks governed repository files with configured exclusions and deterministic ordering | R:- | A:- | S:WalkRepo returns Safe Inventory managed candidates only; .git/.aoci, symlink escapes, runtime, generated, sensitive objects stay hard excluded; SensitiveNameRules is persisted config, never a default
git_command.go[CG8T]: F:Builds every read-only git invocation against an untrusted target repository with repository-controlled execution disabled and no child console window | R:code:internal/fs/safe_inventory.go,code:internal/businesssource/manifest.go,code:internal/fs/git_command_windows.go | A:UntrustedRepositoryGitCommand | S:A scanned repository's own .git/config can name core.fsmonitor and git executes it while walking the tree; command-line -c outranks repository config, so every git call must route through here; under a console-less host each git.exe would otherwise open a visible window, so the constructor calls hideChildConsole
git_ignore.go[CG7T]: F:Answers whether a path is hidden by Git's ignore authority and which rule source hides it | R:code:internal/fs/git_command.go,code:internal/cli/scan.go | A:PathIgnoredByGit | S:One check-ignore call covers .gitignore, .git/info/exclude and core.excludesFile, so the answer must come from Git; --no-index is never passed because it reports tracked files as ignored
git_command_other.go[CG3T]: F:Provides the no-op console suppression for git children on non-Windows platforms | R:code:internal/fs/git_command.go | A:- | S:-
git_command_windows.go[CG5T]: F:Hides the console window of git.exe children with HideWindow and CREATE_NO_WINDOW so a console-less MCP host never flashes a window per probe | R:code:internal/fs/git_command.go,code:internal/ui/detach_windows.go | A:- | S:CREATE_NO_WINDOW only suppresses console allocation and leaves stdio handle inheritance untouched, so host pipes and terminal output behave as before
git_head.go[CG7S]: F:Resolves HEAD from the files git keeps (detached HEAD, loose or packed ref, linked worktree via gitdir and commondir) without a git process | R:code:internal/businesssource/manifest.go,code:internal/fs/git_command.go | A:GitHeadFast | S:Declines anything it does not fully understand (no or symlinked .git, unborn branch, reftable, traversing ref, oversized file) so the caller asks git; the test holds it equal to git for every shape

===/<repository>/internal/index/===
dict.go[CG7L]: F:Parses Header and Meta tag dictionaries, validates canonical compact tag components, and exposes exact symbol definitions for semantic calibration | R:code:internal/authoringcontract/contract.go | A:ExtractTagDict,ExtractScopedTagDict,CheckTagsAgainstDict,DimensionNameNearMiss,AcceptedDimensionSpellingsForLocale,DisplayDimensionSpelling | S:Accepted spellings are exact and a near miss is only reported; a diagnostic must carry only text its Locale accepts, including the operator's own spelling, or the runtime discards it whole
editor.go[CG7L]: F:Edits or inserts one Entry while preserving section structure and unrelated index bytes | R:- | A:NeutralRepositoryRoot | S:Transforms stay in memory; planNewSection is the one decision for writer and probe; a new index begins with a /<repository> root section, never a machine path; sections continue the resolved root
editor_remove.go[CG7S]: F:Removes one exact Entry preimage and prunes only directory Sections left semantically empty | R:code:internal/index/editor.go,code:internal/index/parser.go | A:RemoveEntry,RemoveEntryForPath,PruneEmptySections | S:Zero or duplicate matches fail; path-aware removal disambiguates identical lines; line endings and independent formal content are preserved; an empty root section stays while it anchors other sections
escale.go[CG7M]: F:Derives and validates the scale tag from governed source line-count evidence and slices one profile's dictionary text out of a Meta | R:- | A:ExpectedEScaleSymbols,Symbols | S:E-scale drift is Warning-only and dictionary thresholds rule; missing, unparsable, overlapping, or gapped ranges are never guessed; CheckEScaleDetail is the one decision, CheckEScale renders it
escale_path.go[CG7T]: F:Resolves source paths safely for scale validation without escaping the repository | R:- | A:- | S:Only repository-root .aoci/** and root aoci.txt are excluded to prevent governance-history and self-referential scale churn; similarly named nested or prefix paths remain checked
header.go[CG7S]: F:Provides pure Header extraction, validation, and replacement primitives | R:code:internal/index/parser.go,code:internal/index/editor.go | A:ExtractHeader,ValidateHeaderText,ReplaceHeader | S:The first === line is the Header boundary; new nonblank lines must start with # and cannot contain section syntax, while replacement preserves Entry bytes and line endings and strips a leading BOM
locale.go[CG7S]: F:Detects, constructs, and replaces the canonical explicit Locale marker of an AOCI Index | R:code:textassets/catalog.go | A:DetectLocale,LocaleMarker,ReplaceLocaleMarker | S:An Index without a marker deterministically uses the legacy zh-CN locale; empty, duplicate, or unsupported markers fail; ReplaceLocaleMarker rewrites only the marker line, keeping BOM and CRLF
parser.go[CG8L]: F:Parses Legacy and Volume Entry sections and F/R/A/S fields into deterministic records | R:- | A:- | S:Section roots are historical coordinates judged from text before the runtime root, so origin and clones agree: the old writer's shape reads as written; 2+ sections rooted below the runtime root relocate whole, a lone one stays direct; else direct matches, then only the unmatched subset relocates by a shared prefix, never a guessed path; a name trimming to nothing is no Entry; warnings are forced to valid UTF-8; every leading BOM is stripped, not one, so Parse(RawText) is a fixed point (a doubled BOM is a concatenation artifact; body BOMs stay content)
query.go[CG7M]: F:Parses and evaluates keyword/tag Entry searches and renders localized session runtime rules with machine cognition limits | R:code:internal/index/parser.go,code:textassets/catalog.go,code:internal/machinecontract/numeric.go | A:ParseTagFilter,Search,BuildRuntimeRules | S:Only C accepts >= filters; runtime rules come from the active Locale asset and append validated refresh/chunk limits, never model-generated repository semantics
quota.go[CG7M]: F:Extracts effective per-C S-field rune quotas from Meta and reports violations with machine-default gap filling | R:code:internal/index/dict.go,code:internal/machinecontract/numeric.go | A:ExtractSQuotaThresholds,EffectiveSQuotaContract,CheckSQuotaWith,LimitForC | S:CheckSQuotaWith is warning-level and honours a declaration both ways; LimitForC serves error-level gates and honours only a looser one, so narrowing a header cannot make a persisted Volume unloadable
relations.go[CG5S]: F:Reports single-line form problems in a candidate R field without touching the filesystem | R:code:internal/index/validator.go | A:ValidateEntryRelations | S:Every result is a Warning that never blocks, and targets are never resolved, so R may name anything the model means
types.go[CG7S]: F:Defines Header, Entry, tag, field, section, and validation data structures | R:- | A:- | S:FullLine, not parsed fields, is canonical for comparison and replacement; malformed tags degrade to an empty map; LegacyAbsPath keeps the original header reading so truncated roots still resolve
validator.go[CG8M]: F:Validates Entry syntax, required fields, tags, field limits, and semantic structure | R:- | A:- | S:Multiline, filename mismatch, missing FRAS, or duplicate F/R/A are hard errors; unparseable tags, evolution narrative, and S quota are warnings, and validation never silently repairs candidate bytes
validator_tagparse.go[CG7T]: F:Classifies existing validator warnings into the tagparse reporting dimension without implementing a second tag parser | R:code:internal/index/validator.go,code:internal/index/parser.go | A:HasTagParseWarning | S:Only Warning-level violations with the stable tag-parse prefix qualify; parsing authority remains ValidateEntryLineWith and ParseTags
section_roots.go[CG7S]: F:Rewrites a Code Volume's directory section headers to the neutral root and inserts the Meta line that names it, keeping descriptions, Entries, and line endings | R:code:internal/index/parser.go,code:internal/index/editor.go,code:internal/cli/index_relocate.go | A:RelocateSectionRoots,EnsureSectionRootNote | S:Resolved as every reader does, read back to the same directories; an unresolved section fails the whole rewrite; note after the identity example, else before the first dictionary, else at the end

===/<repository>/internal/machinecontract/===
capabilities.go[CG9T]: F:Defines canonical AOCI-CODE product, repository, module, binary, MCP, and capability identities and the MCP protocol revisions the server negotiates | R:- | A:MCPProtocolCurrent,MCPProtocolHandshakeNewest,MCPProtocolSessionless,MCPSupportedProtocolVersions,MCPToolNameIdentity | S:A revision joins the negotiated list only once a black-box suite speaks it and every tool works on it; from MCPProtocolSessionless on a server may not send its own requests, so human_approval asks through input requests there; initialize answers at most MCPProtocolHandshakeNewest
cognition_planner.go[CG9S]: F:Defines cognition planner, candidate, preview, provenance, and lifecycle version tokens | R:- | A:- | S:-
lexical.go[CG7S]: F:Defines shared machine-owned lexical tokens and the remediation and onboarding command suffixes used across validators, runtime text, Guide, and next_commands | R:code:internal/cli/index_agent_guide.go,code:internal/mcptools/tools_next_commands.go,code:internal/cli/onboard_next_commands.go | A:- | S:Command suffixes live only here so no surface spells one twice; placeholders are host-filled ({snapshot_sha} is what accept binds), the CLI fills {plan_file} and {snapshot_file}
managed_scope.go[CG8S]: F:Defines managed-scope roles, structured decision bases, profiles, policy, evaluation, approval, and transaction tokens | R:- | A:- | S:-
numeric.go[CG9M]: F:Owns cross-layer numeric limits for FRAS, batching, budgets, refresh, and delivery | R:- | A:- | S:Cross-layer numeric limits live only here: the Code batch cap default (50) sits below the wire ceiling (200) it is validated against, the parallel batch count defaults to 1 with a ceiling of 4, the Maintain transport budget defaults to 24 KiB within 16 to 192 KiB with a 40 KiB Claude Code init value, the transport list limit is 20, and the Database Evidence byte gate defaults to 64 KiB; HighImportanceMinC (7) and the 25 percent S-absent hint threshold are read by the coverage report, the hint, and the optimization selector alike; the delta share bound is 50 percent
status.go[CG9M]: F:Defines stable machine status, error, recovery, and next-action vocabularies | R:code:internal/cli/index_agent_guide.go,code:internal/dbcognition/state.go,code:internal/databasebootstrap/prepare.go,code:internal/mcptools/tools_observe_review.go | A:ActionCallNoArgumentMaintainForCurrentMachineBatch,DatabaseCognitionActionMaintain,MaintainActionExplicitOrphanRemove,MaintainActionRemoveOrphansInBatch,StatusLegacyReadOnlyMigrateRequired,OverviewCapacityTokens | S:Database Cognition maintenance aliases the exact no-argument Maintain action used by Guide; a blocked Maintain names its blocker with the MaintainAction tokens (Database orphans first, review when the facts chose it, Guide-stop precedence); Code orphans alone answer remove_orphans_in_update_batch; legacy_read_only_migrate_required is one token for every write face of a Legacy layout; capacity_stop and its reason are the Host-capacity words; delta, chunked_delta and the delta_* fallbacks are the L5 words; observe_review answers acknowledged, stale, not_pending, or human_approval_required
overview_session.go[CG7T]: F:Owns the runtime resource limits of reused Overview deliveries: cursor prefix, store count and bytes, idle and absolute lifetimes, cursor size | R:code:internal/mcptools/overview_session_v2.go | A:OverviewDeliverySessionPrefix,OverviewDeliverySessionMaxCount,OverviewDeliverySessionMaxBytes,OverviewDeliverySessionIdleMillis,OverviewDeliverySessionLifetimeMillis,OverviewDeliveryCursorMaxBytes | S:Runtime resource limits only: they enter no cognition identity, receipt, or persisted policy, so moving them changes no repository's governance
human_approval.go[CG8T]: F:Defines the host-dialog approval tokens: mechanism, team channels, the Maintain human_approval intent, request kinds, decisions, result statuses, next actions | R:code:internal/mcptools/tools_human_approval.go,code:internal/config/approval.go | A:ApprovalMechanismHostElicitationConfirmation,MaintainIntentHumanApproval,HumanApprovalChannels,HumanApprovalKinds | S:Tokens only: the dialog's numeric limits live with its MCP handler because no other layer reads them

===/<repository>/internal/managedscope/===
evaluate.go[CG8M]: F:Evaluates Safe Inventory objects against profile, project, Curation, Git, and safety rules | R:code:internal/managedscope/memo.go,code:internal/managedscope/policy.go,code:internal/cognition/ownership.go,code:internal/cognition/loader.go | A:- | S:Exclude paths are never content-read; matching uses exact Git semantics on every host, so the applied identity never depends on the filesystem; the identity preimage keeps its case-sensitive form, and high-risk opt-ins remain approval-gated before Snapshot; under a Volumes Root a formal asset takes the index role before any rule, so no policy can observe or drop a Volume, while a git-hidden one stays excluded for scan's refusal; a Legacy index file stays rule-governed, as Maintain never plans its Entry; after the walk Build answers from the memo when every input's digest matches
policy.go[CG8M]: F:Normalizes, validates, canonically identifies, and matches Managed Scope policies, rules, patterns, and exceptions | R:code:internal/machinecontract/managed_scope.go,code:internal/managedscope/glob.go | A:Normalize,Identity,NormalizePattern,Match | S:User policy cannot claim safety-rule authority; matching is exact and case-sensitive on every host; paths must be normalized repository-relative values, file and directory patterns compare bytes and may hold '[', glob syntax is restricted, and rule precedence is deterministic. The compiled-pattern memo is keyed on the exact pattern bytes, so it stays bounded by policy size and never by repository size; glob verdicts come from the token program in glob.go, with buildGlobRegexp kept as the definition it is judged against
proposal.go[CG7S]: F:Builds reviewable scope proposals and role-count evidence without applying changes | R:code:internal/fs/safe_inventory.go | A:- | S:Approval keys on AutoBlockerCount, never on every excluded tracked path: an excluded path is never read, and keying on it refused init for any repository tracking a vendored directory
snapshot.go[CG7T]: F:Hashes only Managed Scope Index and Observe paths into role-aware Baseline fingerprints | R:code:internal/baseline/fingerprint_cache.go,code:internal/managedscope/evaluate.go,code:internal/baseline/hash.go | A:Snapshot,SnapshotReusing | S:Exclude content is never opened; high-risk reads need approved state; a prior spares a reparse and the stat cache a read, neither changing a digest; the cache is pruned on save to the paths walked
types.go[CG5T]: F:Defines managed-scope rules with decision bases, evaluations, path roles, proposals, and summaries | R:code:internal/managedscope/evaluate.go | A:- | S:-
starter.go[CG7S]: F:Defines the starter observe rules init persists under the production profile: vendored bundles, third-party trees, SVG, public certificates, lockfiles | R:code:internal/managedscope/policy.go,code:internal/config/scope_budget.go | A:StarterRules,StarterRuleIDPrefix,StarterRuleCreatedBy | S:Source builtin: profile rules outrank, any user rule overrides; persisted at init, never built in, which would flip roles in old repositories; new rules append so the first seven keep ids and orders
glob.go[CG8M]: F:Matches a path against a glob rule with a rune token program instead of the regexp engine, whose backtracking took half of every governance call on a large tree | R:code:internal/managedscope/policy.go,code:internal/managedscope/starter.go | A:- | S:The dialect is buildGlobRegexp's and nothing else: * within a segment, ** across segments, **/ an optional directory prefix, ? one rune, '[' refused, and '.' never matching a newline as the regexp does; literal prefix and suffix are compared as decoded runes, invalid UTF-8 as U+FFFD, because the fuzzer's first find was a byte-wise check disagreeing with the regexp; a verdict decides a path's role, so any disagreement would change Baseline identity, and the differential test over 100,000 pairs plus FuzzGlobMatch keep the regexp the definition this program is judged against
memo.go[CG8T]: F:Remembers each root's last Evaluation under a digest of every Build input, so a process evaluates an unchanged walk once and hands out copies | R:code:internal/managedscope/evaluate.go,code:internal/baseline/process_memo.go | A:- | S:Keyed on inputs, never on time: the digest covers the normalized policy, walk options, root layout, curation exclusions, inventory summary and exclusions, and every tracked, untracked, and ignored path, so a changed input always misses and a test mutates each one; one record per root, never handed out, and copies keep empty lists non-nil since they publish as []; Rule pointers are shared and immutable; a new top-level path under .aoci, which the first Maintain creates, is a legitimate miss; AOCI_PROCESS_MEMO=off disables it

===/<repository>/internal/managedstate/===
state.go[CG9S]: F:Loads the active Legacy or Managed Scope snapshot and detects Code drift only when policy and budget receipts align | R:code:internal/baseline/scope_detect.go,code:internal/managedscope/evaluate.go | A:Load,Detect,CurationExclusions | S:Direct policy edits fail closed as scope_change_required; a receipt recorded under the historical case-insensitive semantics is never adopted and migrates through Scope Change; empty budget identity is accepted only for early receipt compatibility. The loaded Baseline is passed to the snapshot for digest reuse, which changes no value; Load keeps the Legacy Safe Inventory it built on State.Inventory, so the Overview reuse guard reads the actual selection instead of scanning again

===/<repository>/internal/mcptools/===
cognition.go[CG8M]: F:Defines Legacy and Volumes cognition receipts, refresh projection, and host-model reliability assessment | R:code:internal/mcptools/tools_read.go,code:internal/mcptools/tools_read_volumes.go,code:internal/mcptools/overview_delivery_v1.go | A:- | S:Receipt identity can invalidate cognition but cannot declare model reliability; only host-model valid state with matching repository, service, scope, and cognition identity can suppress full recall, and write paths cache their proven aligned identity for the read-tool line; every Volumes receipt lists its Volumes with paths in delivered_volumes, an absent scope none
overview_attestation_v1.go[CG9L]: F:Builds and verifies identity-bound Whole-Index challenge attestations and receipts | R:- | A:- | S:The challenge samples deterministic strata of the exact formal Entry sequence; pass needs the current Index, sequence, count, digest, ordered answers with at least 80% fully correct and at most one identity miss, core F judged by normalized token similarity with CJK bigrams, and complete delivery claims; fail is only a foreign envelope or zero correct, otherwise partial, save a retained deletion-only delta: no ordinal, so an empty answer list with zero reported Entries passes under confirmed delivery and aligned governance; a repeated ordinal is scored once, so passed can never exceed total
overview_delivery_v1.go[CG9L]: F:Chunks complete formal cognition deterministically and validates continuation cursors and host receipts | R:code:internal/mcptools/overview_session_v2.go,code:internal/mcptools/overview_capacity.go | A:- | S:The first full request omits host confirmation and model attestation; either field selects attestation-only with no body resent; cursors bind snapshot, budget, ordinal, prior chunk; each proof half is kept per body, so both may arrive separately in either order, an explicit half supersedes memory, a fresh complete delivery resets it; a prepared delivery supplies frame, Challenge, chunk spans; check_only adds delivery_plan and host_capacity; a delta brings its own Challenge, modes, Metadata, and a removals-only delta with unchanged Root and Meta is marked deletion-only for the scorer
server.go[CG8M]: F:Registers the public AOCI MCP server and nine tools while carrying Code batch plans through structured failure handling | R:code:internal/cognitiontxn/transaction.go,code:engine/mcp.go,code:internal/config/config.go | A:NewServer,RunStdio | S:Tool names and count stay nine; every call reloads repository state uncached and never writes configuration, which would stale a prepared migration or Scope preview; stdout stays JSON-RPC-only, panics become structured MCP errors; startup records the binary's disk identity; negotiation stops at the handshake-era revisions; repoCtx.dict is the dictionary text, empty for Legacy; the loader stops only on layout transactions, as write receipts close in the tools that wrote them; the diagnostics and compact-listing middlewares run first; NewServer is the constructor stdio and the engine share
tools_maintain.go[CG9S]: F:Registers aoci_maintain, gives human_approval the whole call so a dialog spans rounds, and answers a Legacy layout with the read-only stop naming the migration | R:code:internal/mcptools/tools_next_commands.go,code:internal/mcptools/tools_human_approval.go | A:- | S:Since 0.2.0 a Legacy layout gets status=stopped, one finding whose cause starts with legacy_read_only_migrate_required, next_action migrate_legacy_repository, and next_commands for onboard and Guide, each carrying --repo <root>; Volumes Maintain lives in tools_maintain_volumes.go; human_approval is routed before any layout load, so a Legacy repository can approve its own migration
tools_maintain_volumes.go[CG9L]: F:Builds bounded Code and Database authoring batches, review closures, candidate bindings, and model-authoring contracts from shared governance facts | R:code:internal/codebatch/receipt.go,code:internal/mcptools/maintain_contract.go,code:internal/volumegovernance/transport.go,code:internal/dbcognition/receipt.go,code:internal/volumegovernance/facts.go,code:internal/mcptools/tools_maintain_budget.go,code:internal/mcptools/tools_observe_review.go,code:internal/mcptools/tools_maintain_parallel.go | A:- | S:One batch cut by the transport budget; remaining needs a new preimage; candidates are model-only, bound to the verdict snapshot's digest; continuation fields lead, the batch action is the top-level one; an unspellable directory withholds the batch; Code orphans ride beside the batch, never block; under auto a pending observe review rides with it too; siblings get one instruction line; blockingFinding names the blocker, observe-only review_observed_evidence; contract by reference after round one; under N>1 the batch is a sibling's, remaining what no sibling holds; next_commands carry --repo
tools_read.go[CG8L]: F:Registers and serves MCP Rules, Overview, Entry retrieval, and Search across Legacy and Volume cognition layouts | R:code:internal/mcptools/overview_attestation_v1.go,code:internal/mcptools/overview_volume_governance.go,code:internal/mcptools/overview_session_v2.go,code:docs/overview-delivery.md,code:internal/mcptools/overview_capacity.go | A:aoci_rules,aoci_overview,aoci_get_entries,aoci_search | S:Ordinary Overview delivers the complete requested dependency-closed cognition bytes, chunked only as transport; pending Recovery or snapshot drift fails closed; the aoci_overview _meta result-size declaration is static, raising only that tool's Host persist threshold, never a capability probe; path refusals render their catalog reason; a Volumes Overview routes through the owner-bound delivery store, and the schema_accepted event is appended once the config is loaded; a Legacy compaction reload obeys the same capacity stop; delta_since is validated before any read and refused on Legacy
tools_write.go[CG8L]: F:Prepares one Entry update for the shared atomic batch: parse, dictionary, threshold, and budget findings, plus the failure-code mapping | R:code:internal/mcptools/tools_write_api.go,code:internal/baseline/baseline.go,code:internal/mcptools/tools_write_batch.go | A:- | S:Budget rejections carry candidate-bound findings: entryBudgetRepairFindings measures R and S against the bands, S floored by the Meta quota, in enforce mode only; a dictionary refusal quotes the rejected spelling in a form the active Locale accepts or is discarded whole; threshold checks read the context's dictionary text; a refused path names its catalog reason; a refused write's Ledger event records a repairable refusal as repair_required and whether formal writes began; the outcome keeps the lines the editor replaced, wrote, or removed, which a sibling's applied record replays
tools_write_batch.go[CG9L]: F:Validates and applies one complete semantic candidate batch across affected Volumes | R:- | A:- | S:All candidates plan against one preimage and fail as a unit before writes; apply uses one locked CAS transaction, source/guard rechecks, postimage confirmation, Baseline advancement, and retained recovery so partial post-write failure remains recoverable rather than rolled back; a refused item path names its catalog reason; a Legacy layout is refused with legacy_read_only_migrate_required before planning, so a plan reaching commit without a Volumes plan is an internal failure (atomic_batch_plan_without_volume); a removal item names only a Code orphan's path, no Entry, digest, or candidate
overview_cognition_level.go[CG7T]: F:Derives additive cognition delivery and verification levels without conflating governance | R:- | A:- | S:-
overview_cognition_state_v2.go[CG8S]: F:Projects independent delivery, usability, attestation, governance, and reliability cognition state | R:- | A:- | S:-
overview_volume_governance.go[CG7S]: F:Calculates scope-specific Volume alignment and reliability for Overview responses | R:code:internal/volumegovernance/facts.go | A:- | S:Refresh identity excludes BusinessSource and Exclude counts, binds Baseline bytes; a new Baseline reuses no older body; blockers omit informational findings; the snapshot variant feeds the guard
tools_auto_alignment.go[CG7M]: F:Re-evaluates post-Apply Legacy or Volumes governance and returns alignment, remaining findings, and the current cognition receipt | R:code:internal/cognition/ownership.go,code:internal/managedstate/state.go,code:internal/curation/classify.go,code:internal/mcptools/tools_write_api.go,code:internal/volumegovernance/facts.go | A:- | S:Volumes drift is volumegovernance.CodeDrift, read by Verify and scope status too, so a once-observed Root record or a held source is no debt; the Legacy inspector keeps its Detect, allowlisted
tools_auto_audit.go[CG7T]: F:Builds a compact deterministic P-23 audit summary from an update batch and optional AtomicBatch outcome | R:code:internal/mcptools/tools_write_api.go,code:internal/mcptools/tools_write_batch.go | A:- | S:The summary hashes the exact submitted items, but its presence is audit evidence rather than governance or formal-write proof
tools_auto_result.go[CG8M]: F:Defines and serializes compact applied, repair, stopped, audit, governance, plan, optimization, terminal-proof, observe-review, and terminal-action MCP results | R:code:internal/mcptools/tools_write_api.go,code:internal/mcptools/tools_cognition_optimization.go,code:internal/codebatch/types.go,code:textassets/maintain_assets.go,code:internal/mcptools/tools_terminal_proof.go | A:autoResult,renderAutoResult,autoApplyNextAction | S:A batch whose Entries were already in place, a repeat or an unchanged resubmission, reports Applied=0 with the zero-write proof action; the final ordinary Volumes Apply selects a dedicated proof action and carries terminal_proof instead of commands, while paged, Legacy, and Optimization flows retain their own continuations
tools_contract_assets.go[CG9L]: F:Loads localized MCP contract assets, builds closed JSON Schemas for the nine tool inputs, and derives the compact view tools/list shows | R:code:internal/mcptools/tools_write_api.go,code:internal/mcptools/tools_maintain_database.go,code:textassets/catalog.go,code:internal/mcptools/overview_diagnostics.go,code:internal/mcptools/tools_observe_review.go | A:loadMCPInputSchemas,localizedMCPSchema,advertisedMCPInputSchemas | S:Nullable inputs use anyOf with a null branch; calls validate against the closed registered schemas, unknown fields fail, only cognition_receipt and probe_answers are listed as plain objects; Maintain intent stays additive: cognition_optimization with object_refs, human_approval and observe_review with closed objects, include_instructions a boolean, batch_id and delta_since described 64-hex strings; Code batches keep code_batch_id top-level with candidate and source bindings per item, removals a nullable {path} array, observe_review the closed digest object
tools_format_only.go[CG7T]: F:Lists the proven format-only or line-ending-only targets the Volumes batch may advance without semantic rewrites | R:- | A:- | S:Only the candidate filter survived the Legacy retirement; the Baseline advance itself lives in the Volumes write transaction
tools_header.go[CG7T]: F:Implements the MCP Header dictionary reader for Legacy and Volumes layouts | R:- | A:- | S:Volumes mode returns exact Meta bytes with Root/Meta identities plus the session cognition line; pending delivery fails closed and each read appends header_show to the Ledger
tools_maintain_database.go[CG8M]: F:Parses Maintain inputs and routes Legacy read-only, ordinary Volumes, explicit Database, optimization, and observe review requests to their workflows | R:code:internal/mcptools/tools_maintain.go,code:internal/mcptools/tools_maintain_volumes.go,code:internal/mcptools/tools_cognition_optimization.go,code:internal/dbcognition/receipt.go,code:internal/mcptools/tools_observe_review.go | A:- | S:Omitted scope or code/all use shared Volume governance; a non-Volumes layout gets the Legacy read-only stop; cognition_optimization takes only Volumes v1 Code, object_refs need that intent, explicit database reads saved Evidence offline; human_approval has no session here and is refused, as is approval_request without it; observe_review runs before any layout load, refuses Legacy itself, and its object needs the intent; collectorless sources block nothing; include_instructions reaches both Volumes paths; batch_id takes no scope and goes to sibling delivery first
tools_read_refresh.go[CG7L]: F:Computes cognition checkpoint reasons, generations, refresh guidance, the session line for reads, per-body delivery evidence, and the open compaction reload | R:code:internal/mcptools/overview_capacity.go | A:- | S:Session facts, no scans; invalid is an identity break, a reliable receipt with a pending refresh is uncertain; proof halves latch; mid-reload compaction is the verdict; keeps delta base and probe pass
tools_read_search.go[CG7S]: F:Searches Legacy or Volume cognition while preserving canonical object identities | R:- | A:- | S:-
tools_read_snapshot.go[CG7T]: F:Enumerates active formal cognition assets and revalidates their exact bytes after rendering to prevent mixed delivery | R:code:internal/mcptools/tools_read.go,code:internal/mcptools/transaction_guard.go | A:- | S:A changed byte, unsafe file type, or unreadable participant invalidates the entire delivery snapshot; this layer does not merge or repair images
tools_read_volumes.go[CG7L]: F:Delivers scoped Volumes Overview bodies, receipts, chunking, attestation targets, refresh accounting, guarded reuse, capacity stops, incremental deltas | R:code:internal/mcptools/tools_read.go,code:internal/mcptools/overview_attestation_v1.go,code:internal/mcptools/overview_volume_governance.go,code:internal/mcptools/overview_session_v2.go,code:internal/mcptools/overview_capacity.go | A:aoci_overview | S:Recovery or snapshot change fails closed; explicit Overview re-delivers unless capacity stops it; delta_since serves from the session base or names its fallback; cursors and proofs reuse a delivery
tools_remove.go[CG7L]: F:Implements MCP orphan Entry removal for Volumes and answers a Legacy layout with the read-only refusal | R:code:internal/mcptools/tools_remove_volumes.go,code:internal/cognitiontxn/transaction.go | A:- | S:Removal is orphan-only on both surfaces; a plain path under Volumes v1 routes as code:<path>; CAS recheck fails closed on drift; a Legacy layout answers legacy_read_only_migrate_required
tools_remove_volumes.go[CG7L]: F:Plans, proves, commits, and recovers explicit Code or Database Volume Entry removal with Baseline and evidence guards | R:code:internal/volumegovernance/facts.go,code:internal/cognitiontxn/transaction.go,code:internal/index/editor_remove.go,code:internal/dbevidence/types.go | A:- | S:Orphans only; Code lines go by path so twins stay; a pending scope change names scope activate; a disabled Ledger refuses pre-write; old receipt: absent→superseded, unchanged→discard, changed→refuse
tools_report.go[CG7T]: F:Validates aoci_report arguments and answers each layout's read-only refusal, the Legacy follow-up record being retired | R:code:internal/mcptools/tools_maintain.go | A:- | S:Volumes v1 keeps answering volume_read_only; a Legacy layout or an unloadable index answers legacy_read_only_migrate_required; nothing is written since 0.2.0
tools_write_api.go[CG9L]: F:Registers Entry-write MCP tools and maps requests into atomic execution, recovery, governance, optimization, precise repair, and terminal outcomes | R:code:internal/mcptools/tools_contract_assets.go,code:internal/mcptools/tools_auto_result.go,code:internal/mcptools/tools_cognition_optimization.go,code:internal/mcptools/tools_auto_alignment.go,code:internal/mcptools/tools_write_batch.go,code:internal/mcptools/tools_write_batch_recovery.go,code:internal/mcptools/tools_terminal_proof.go | A:aoci_update_entry,aoci_report | S:Optimization no_change and replacement recovery retain their dedicated contracts; binding repair is zero-formal-write and complete-batch scoped; the final ordinary Volumes Apply carries terminal_proof from the shared facts, which outrank the inspector: a blocker answers aligned=false, while Ledger remains audit only; a failure's code_plan is projected off the wire; removals ride beside entries as remove items, alone when nothing is authored; every write is the atomic batch; observe_review is confirmed before the batch is planned and reported beside every outcome
tools_write_batch_recovery.go[CG9M]: F:Persists, validates, resumes, completes, and rolls back evidence-bound atomic Entries recovery receipts | R:code:internal/mcptools/tools_write_volume_commit.go,code:internal/mcptools/tools_write_batch.go,code:internal/jsonstrict/duplicate.go | A:UpdateEntriesAtomicRecoveryPending,CompleteUpdateEntriesAtomicRecovery,RollbackUpdateEntriesAtomicRecovery | S:Resume or rollback requires exact participant pre/post hashes, guarded Root and Meta, unchanged Baseline preimage, and the identical candidate batch; unknown bytes fail closed; receipts reject case-colliding keys; a removal adds one value to the batch key, so keys of batches without removals are unchanged across the upgrade
tools_write_governance_receipt.go[CG7M]: F:Persists completed Entries governance receipts, loads them all, and archives or finds atomic batch recovery receipts by batch key | R:code:internal/mcptools/tools_write_batch_recovery.go,code:internal/mcptools/tools_write_volume_commit.go,code:internal/jsonstrict/duplicate.go | A:- | S:Receipts never authorize replay or replace alignment checks; they reject duplicate, case-colliding, or unknown keys; an archived recovery is still found by its batch key
tools_write_impact.go[CG7M]: F:Computes bounded relation and downstream impact for a proposed complete Entry batch | R:- | A:- | S:The envelope derives from complete candidates, Code deletes included; at most two Volumes written while Root, Meta, unwritten Volumes stay byte guards; Code context reads Meta's code dictionary
tools_write_repair_findings.go[CG7M]: F:Localizes, orders, and scopes deterministic candidate repair findings without generating replacement semantics | R:code:internal/cognition/repair_findings.go,code:internal/mcptools/tools_write_api.go | A:localizeRepairFindings,repairRetryScope | S:Repairs name the reported field or the whole candidate when none; object-missing and already-present findings carry their own action; R is never repairable; batch ids are top-level repairs
tools_write_volume_commit.go[CG9L]: F:Plans and commits receipt-bound Code and Database batches through identity checks, projection, guarded CAS, Baseline binding, and recovery | R:code:internal/codebatch/receipt.go,code:internal/mcptools/tools_write_batch.go,code:internal/mcptools/tools_write_batch_recovery.go,code:internal/cognition/impact.go,code:internal/codebatch/parallel.go | A:- | S:Nothing here reads the R just authored: relations never replan or stop a batch; a cross-volume partial write is judged per volume, the batch rolls forward; enforce-mode budget violations return per-candidate findings; a binding defect answers a Repair Finding before any write, every repairable candidate in one repair_required with its field budget overruns measured there too; Baseline fingerprints keep their index role; a removal needs a facts-proven orphan; a parallel sibling is validated by replay, reprojected under the lock if another landed first, leaving its applied record
transaction_guard.go[CG7T]: F:Blocks cognition delivery or Entry writes while pending recovery or AtomicWrite state makes the formal snapshot incoherent | R:code:internal/mcptools/tools_read_snapshot.go,code:internal/mcptools/tools_write.go,code:internal/cognitiontxn/transaction.go | A:- | S:Every pending receipt (cognitiontxn.Pending, shared with Verify and the CLI gate) blocks ordinary cognition delivery; unfinished Header transactions also block other governance writes
tools_cognition_optimization.go[CG9L]: F:Implements explicit aligned Code cognition optimization planning, deterministic candidate transport, checkpoint progression, and replay-safe Update integration | R:code:internal/cognitionoptimization/checkpoint.go,code:internal/cognitionoptimization/selector.go,code:internal/codebatch/receipt.go,code:internal/mcptools/tools_maintain_volumes.go,code:internal/mcptools/tools_write_api.go,code:internal/volumegovernance/facts.go | A:- | S:Only aligned Volumes v1 Code with no budget violation is eligible; the transport budget cuts the selector's order, so the batch is its leading prefix and the checkpoint keeps the cut; progress advances only after Update/Baseline/Recovery closure, altered replay fails before Apply; S:- on C7+ is s_absent_high_importance, a contradicted E letter e_scale_mismatch; candidates add file_lines and expected_e; every Select floors s_max_tokens by the Meta quota; a referenced contract keeps the review note in instructions; a redelivered batch keeps explicit_object_ref from the checkpoint
service_binary.go[CG5T]: F:Watches the service's own on-disk binary and reports replacement as an advisory governance fact | R:code:internal/mcptools/server.go | A:RecordServiceBinaryIdentity | S:Detection is size and mtime only and purely advisory: it never blocks a tool, probe failure silently disables it, and replacement means restart the host MCP integration
overview_probe_v1.go[CG7S]: F:Issues and grades the deterministic two-question cognition probe that turns model self-report into machine measurement | R:code:internal/mcptools/overview_attestation_v1.go,code:internal/mcptools/tools_read_volumes.go | A:- | S:Purely a measurement: it never advances the generation, records a reason, or touches a receipt; a pass licenses reuse instead of re-delivery, and a stale result is not evidence of loss
tools_next_commands.go[CG8S]: F:Composes runnable next_commands for blocked, evidence-required, and Legacy read-only MCP results from shared suffixes, the server executable, and --repo <root> | R:code:internal/machinecontract/lexical.go,code:internal/mcptools/tools_maintain_volumes.go,code:internal/mcptools/tools_write_api.go | A:- | S:The prefix is the running server's absolute quoted path plus --repo naming the root it serves, as aoci need not be on PATH and the Host's shell need not stand in the repository; an unresolvable executable or unquotable root omits the field, since an absent advisory beats a wrong command; recovery_pending points at the Guide, plus scope status for a scope receipt; scope_change_required names status then activate; the Legacy stop names onboard start then Guide; observed_pending names scope status alone unless the facts chose review, then acknowledge and the Guide follow
overview_plan_export.go[CG5S]: F:Exports the exact Overview chunk planner, the complete body, and the framed body with its receipt digest for the status page and the engine | R:code:internal/mcptools/overview_delivery_v1.go,code:internal/ui/snapshot.go,code:engine/overview.go | A:PlanOverviewChunks,OverviewChunkPlan,OverviewBody,FramedOverviewBody | S:All three run the delivery path's own builder and touch no session, Ledger, or receipt; FramedOverviewBody reuses frameOverviewBody, so the library digest is body_sha256
tools_maintain_budget.go[CG8M]: F:Sizes one Maintain response: reserves the fixed and sampled parts, measures candidates and scale evidence on the wire, cuts the batch, projects the plan | R:code:internal/codebatch/receipt.go,code:internal/mcptools/tools_maintain_volumes.go,code:internal/mcptools/maintain_contract.go,code:internal/cli/scan_skipped.go,code:internal/cli/index_agent_guide.go | A:PlanCodeBatchIncluded,EstimateCodeAuthoringRounds,EstimateCodeAuthoringRoundsParallel,scaleEvidenceWireWidth | S:The base reservation covers only path-free parts; Meta and instruction bytes are measured on the repository on a round that carries the contract, a reference round reserves it; the five-item samples are measured on the candidates, so a custom Meta or deep tree never overflows a constant; optimization candidates count 320 extra bytes; scale evidence is reserved at the width the cached line count gives, the widest form when the count is unknown; Guide and scan take a first round's shape, scan counting one contract round then reference rounds; the parallel estimate cuts siblings as Maintain does
overview_diagnostics.go[CG7S]: F:Names the attestation schema boundary in SDK errors, shows the compact advertised schemas on tools/list, and logs Overview delivery, proof, and capacity events | R:code:internal/mcptools/server.go,code:internal/ledger/ledger.go,code:internal/mcptools/overview_capacity.go,code:internal/mcptools/tools_contract_assets.go | A:- | S:The schema hint matches the SDK's validating-arguments prefix only for aoci_overview calls carrying an attestation; the listing copies each replaced tool; a delta counts as a completed delivery
overview_session_v2.go[CG8M]: F:Keeps one MCP server's reusable Overview deliveries: immutable prepared bodies, owner-bound HMAC cursors, a bounded store, proof retention, guarded continuation | R:code:internal/mcptools/overview_source_guard.go,code:internal/mcptools/overview_delivery_v1.go,code:internal/mcptools/tools_read_volumes.go,code:internal/machinecontract/overview_session.go,code:internal/mcptools/overview_capacity.go | A:- | S:The store belongs to one server, never a repository cache; a v2 cursor is v2:<id>:<v1 cursor>:<hmac> under a per-delivery secret, replayable, Host-bound, never reconstructed after expiry, eviction, or restart; bytes are accounted conservatively (8x body, 2048 per Entry, 192 per anchored object), so a large index overflows the 64 MiB budget and falls back to the live path; continuation re-validates the guard and counts toward its delivery chain; a retained delivery carries the delta anchor its proof settles and reports its real scope, so a confirmed proof can clear the capacity verdict
overview_source_guard.go[CG8M]: F:Binds a reused Overview delivery to its inputs and revalidates them on continuation without repeating policy evaluation | R:code:internal/mcptools/overview_session_v2.go,code:internal/fs/safe_inventory.go,code:internal/managedstate/state.go,code:internal/mcptools/tools_read_snapshot.go,code:internal/baseline/fingerprint_cache.go | A:- | S:Binds effective, raw and local config, Baseline and Curation bytes, the composite identity, the inventory digest (candidates with Git status, rules, blockers, unsafe boundaries) and each index/observe source's raw digest and size; validate rebuilds the inventory and checks sources through the fingerprint cache as scan and Maintain do (a stat while size and mtime match, else a hash), read-only, so a same-size rewrite with restored mtime is unseen, as by governance; no guard for a pending scope change, source warnings, or an enabled Database Volume, whose Evidence expires without drift
overview_capacity.go[CG8M]: F:Breaks compaction reload loops: a reload interrupted by compaction becomes a Host-capacity verdict, later reloads get the capacity stop; names delivery chains | R:code:internal/mcptools/tools_read_refresh.go,code:internal/mcptools/tools_read_volumes.go,code:internal/mcptools/overview_delivery_v1.go,code:spec/public/aoci-cognition-refresh-v1.txt | A:- | S:Only a fresh delivery of the complete scope under a pending compaction opens an attempt; a model proof half, even a failed one, a complete Host confirmation, or an attested delivery closes it, but an incomplete Host-only confirmation leaves it open; a fresh compaction event while it is open is the verdict, smallest size wins; the stop needs a pending compaction and a scope at least that large, consumes the generation with an uncertain receipt, and carries no body or level; the verdict lives in the server session only and a confirmed complete delivery at least that large clears it
tools_human_approval.go[CG8L]: F:Serves aoci_maintain human_approval: shows a pending Scope Change or onboarding review to the person by form elicitation, records an approve, reports a reject | R:code:internal/scopechange/transaction.go,code:internal/onboarding/store.go,code:internal/migrationapply/approval.go,code:internal/bootstrapapply/approval.go,code:internal/config/approval.go,code:internal/mcptools/tools_maintain.go,code:internal/cli/host_interaction.go | A:aoci_maintain intent=human_approval | S:Dialog text comes from the artifact on disk, not the caller; a preview under .aoci is read without following symlinks and replayed first; gates: approval on record, eligibility, team channel, host capability, dialog; approve records the approval where apply reads it, applying nothing; decline rejects, cancel or a host error dismisses; on 2026-07-28 the dialog is an input-request round whose answer counts only beside this process's HMAC state for the same text, else stale, and an undecided form dismisses; the note is cut here, not by maxLength; terminal outcomes carry approve and apply commands
tools_observe_review.go[CG8M]: F:Serves the observe_review intent and the batch's observe_review: confirms by digest the Observe evidence Maintain listed, via the scope acknowledge transaction | R:code:internal/volumegovernance/facts.go,code:internal/scopechange/plan.go,code:internal/scopechange/transaction.go,code:internal/mcptools/tools_maintain_volumes.go,code:internal/mcptools/tools_maintain_database.go,code:internal/mcptools/tools_human_approval.go | A:aoci_maintain intent=observe_review | S:The digest binds each listed path, change, and current byte digest and is recomputed first: moved bytes answer stale with the current listing and write nothing; preview fingerprints are rechecked against the listed bytes before Apply; a posture needing a person saves the preview under .aoci/scope-change/observe-* and offers host_dialog_request if admitted; an aligning ack carries terminal_proof; a pending Scope Change is refused; a list longer than the listing gets no confirmation, nothing is confirmed unseen; batch and ride-with-batch share one Build
maintain_contract.go[CG8S]: F:Sends the authoring contract once per process and refresh generation and a reference after; include_instructions or a new generation sends it again | R:code:internal/mcptools/tools_maintain_volumes.go,code:internal/mcptools/tools_cognition_optimization.go,code:internal/mcptools/tools_read_refresh.go,code:internal/authoringcontract/contract.go | A:attachAuthoringContract,codeContractOnWire,authoringContractDigest | S:The digest covers the Meta bytes and the contract instructions only, so the optimization review note rides in instructions beside a reference; a nil session sends the contract every time; the memo is keyed by digest and generation, so a completed compaction reload resends it with no Host flag; the Code-only digest decides the budget before the batch is cut, so a mixed Code and Database round may carry the contract where the reference was reserved
tools_maintain_parallel.go[CG8L]: F:Issues up to N sibling batches of one plan under code_cognition_parallel_batches, delivers the first unhanded one, lists the others, and serves any by batch_id | R:code:internal/codebatch/parallel.go,code:internal/mcptools/tools_maintain_volumes.go,code:internal/mcptools/tools_maintain_database.go,code:internal/mcptools/tools_maintain_budget.go,code:internal/mcptools/tools_write_volume_commit.go | A:buildParallelCodeCandidates,handleParallelSiblingDelivery | S:A plan is the siblings cut at its start and completes when each has applied or was invalidated, so the replay and the listing stay at N; every sibling is cut under the budget less the listing's bytes, iterated until it fits; a delivered sibling is handed out again only when none is undelivered; an invalidated sibling stays listed and holds no target; a batch_id under N<=1 or outside the plan is refused with zero writes; the plan that no longer replays is dropped on the next Maintain
overview_delta_v1.go[CG8L]: F:Serves incremental Overview deliveries: the session base, delta computation, delta body and Challenge, eligibility fallbacks, empty delta, base settlement | R:code:internal/mcptools/tools_read_volumes.go,code:internal/mcptools/overview_delivery_v1.go,code:internal/mcptools/tools_read_refresh.go,code:internal/mcptools/overview_probe_v1.go,code:spec/public/aoci-overview-delivery-v1.txt | A:deltaSinceInputFault,computeOverviewDelta,buildVolumeDeltaBody,buildDeltaChallenge | S:The base is session memory only: identities plus object line digests, never a body, anchored by a passing Attestation under aligned governance (complete or delta) and dropped by a partial or failed delta one; the delta Challenge keeps the complete sequence's identity facts while its ordinals are the delivered objects' current ones; a delta needs a retained delivery because only it holds that Challenge for the proof; an empty delta re-anchors without a proof; the share bound is machinecontract's
tools_terminal_proof.go[CG8T]: F:Builds the terminal_proof the final Apply, an aligning observe review, and a completed onboarding carry: Check's and the Guide's verdicts from the shared facts | R:code:internal/volumegovernance/facts.go,code:internal/mcptools/tools_write_api.go,code:internal/cli/check.go,code:internal/cli/index_agent_guide.go,code:internal/cli/cognition_onboard.go | A:TerminalProof,BuildTerminalProof | S:check_passed is structure_valid and governance_aligned, guide_complete is governance_aligned and guide_next_action the facts' next action, so it must track what check.go and index_agent_guide.go print; informational findings are left out; the facts rule over the write-side inspector, and an unassessable repository reads unavailable, never aligned

===/<repository>/internal/scopechange/===
authorization.go[CG8L]: F:Builds and verifies managed-scope authorization and partitions every auto blocker into reasons independent review may ratify and safety boundaries it may not | R:code:internal/scopechange/plan.go,code:internal/scopechange/transaction.go | A:EffectiveApplyAuthorizationMode | S:Scope Change and first Baseline establishment must resolve the effective mode through one function so the receipted and authorizing postures cannot diverge; Resume and idempotent re-apply select the same branch as Apply; an unclassified blocker fails the build. One unratifiable blocker denies the reviewer route entirely, because a transport constraint only ever accompanies a ratifiable one
plan.go[CG9L]: F:Builds scope-change envelopes, authoring debt, coverage and posture risks, formal cognition guards, and governed postimages | R:code:internal/managedscope/snapshot.go,code:internal/baseline/baseline.go,code:internal/cognition/loader.go,code:internal/scopechange/authorization.go,code:internal/cognition/ownership.go | A:Build,FormalCognitionBaselineGuards | S:Source equivalence uses EquivalentFingerprints; a weaker mode than receipted: relaxation; the envelope carries plan-time Curation exclusions the postimage cannot reproduce; auto interaction_required derives from the blocker set; an observe removal also needs the vanished set; under an aligned policy an excluded path keeping an Observe fingerprint joins the review set; Volumes takes policy-only candidates and keeps a changed source's old fingerprint for Maintain; Legacy fails closed; formal guards carry index, leave the review set; the review refusal carries its paths for activate --reviewed-by
transaction.go[CG8L]: F:Applies scope policy, Entry, Baseline, Observe, Curation, Ledger, and recovery changes atomically, and records and admits terminal or host-dialog approvals | R:code:internal/scopechange/authorization.go,code:internal/config/approval.go | A:NewApproval,NewHostDialogApproval,HostDialogEligible,ApprovalEffects,ApprovalEffectSummary,ApprovalBinds | S:Apply selects one live team authorization, replays Preview and guards under the global lock, publishes Baseline last, and permits Resume or Rollback only across exact frozen states; verification after publication must replay plan-time Curation exclusions, not recompute them from the new Baseline; an auto plan demanding interaction authorizes through the review branch; a host-dialog approval counts only while human_approval_channel admits it and the plan has no high-risk opt-in, judged when Apply starts, while Resume's structural check accepts both mechanisms; one lost file reads singular
types.go[CG5M]: F:Defines scope candidates, coverage-reduction, line-ending, stale-retention, and posture evidence, risk, Plan, Preview, authorization, and result types | R:code:internal/scopechange/plan.go | A:- | S:SourceLineEndingOnly and SourceStaleRetained are omitempty because planIdentity hashes the whole Plan, so serializing either empty would change every existing plan_id and strand in-flight approvals

===/<repository>/internal/volumegovernance/===
facts.go[CG9L]: F:Computes one deterministic governance fact set shared by Verify, Check, Guide, Maintain, and Overview | R:code:internal/baseline/detect.go,code:internal/businesssource/manifest.go,code:internal/curation/classify.go,code:internal/cognitiontxn/transaction.go,code:internal/mcptools/tools_observe_review.go,code:internal/dbevidence/types.go,code:internal/cognition/ownership.go | A:CodeDrift,ClassifyCodeDrift,DriftOf,AssessWithSnapshot,ObservedReviewDigest | S:CodeDrift is the sole drift projection; held sources are code_skipped/code_curation_excluded, so Maintain plans what Verify counts; a pending receipt is recovery_pending; finalize names review_observed_evidence only absent a harder blocker; code_orphan is authoring, no stop; AssessProjectedBudget floors S by Meta quota, size never violates; restore a drifted object Volume with Root, all Volumes, Baseline from one commit (a subset fakes alignment); observe evidence stays out of JSON; root_locale_mismatch blocks until config set locale; a declared source owes Evidence before its Volume exists
escale.go[CG7T]: F:Audits every Code Entry's E scale letter against its source line count for verify and check, reporting mismatches as facts that never fail | R:code:internal/index/escale.go,code:internal/cli/check.go,code:internal/cli/verify.go | A:AssessEScale,EScaleFacts,EScaleItem | S:Reads every indexed file, so verify and check call it and Assess never does; without Meta thresholds or on an unreadable source nothing is judged; items carry the letter, expected letters, and lines
transport.go[CG7T]: F:Projects Facts for a Maintain response: bounded lists, and the four per-asset records off the wire by shadowing their keys | R:code:internal/volumegovernance/facts.go,code:internal/mcptools/tools_maintain_volumes.go | A:TransportFacts,BoundForMaintainTransport,MaintainTransportOmittedKeys | S:Shadow fields keep Go names unlike Facts', or in-process readers of Facts.Code would see nil; decoding the wire leaves the promoted records empty; a test pins the omitted keys and key order
score_input.go[CG5T]: F:Projects the governance facts and the E scale audit into the input the Volumes score reads, so index score never measures drift, budget, or E scale again | R:code:internal/volumegovernance/facts.go,code:internal/volumegovernance/escale.go,code:internal/indexgen/score_volumes.go | A:Facts.ScoreInput | S:Lists are copied, never aliased; ObserveReviewRequired comes from the team policy, not the facts; the E scale audit is an argument because Assess never reads a source

===/<repository>/scripts/blackbox/longrun-refresh/===
README.md[CG5T]: F:Documents the long-running refresh black-box scenarios, their Volumes fixture, and the required final alignment evidence | R:- | A:- | S:-
main.go[CG5L]: F:Runs deterministic long-lived cognition refresh scenarios against a real stdio MCP server on a governed Volumes fixture and emits identity-bound evidence | R:code:internal/mcptools/overview_attestation_v1.go,code:Makefile | A:go run ./scripts/blackbox/longrun-refresh,make longrun-refresh | S:Nightly only; its Attestation must echo the Challenge's index_sha256, entry_sequence_sha256 and entry_count, and repair findings decode as raw JSON: the two drifts that left it unrunnable for months

===/<repository>/scripts/===
check-deps.sh[CG5S]: F:Enforces the direct-module set, SQLite driver included, the reviewed local openGauss Connector replacement, and the no-model-client boundary of core and engine | R:code:go.mod,code:third_party/openGauss-connector-go-pq/go.mod | A:- | S:A version-only require is insufficient: a missing replace could restore unsafe upstream behavior; the direct-module list changes only with go.mod; AI_PKGS stays empty since 0.2.0
check-licenses.sh[CG5M]: F:Checks FSL metadata and that the six-platform release module set equals the THIRD-PARTY-NOTICES inventory, with bound openGauss and SQLite license handling | R:code:.goreleaser.yml,code:THIRD-PARTY-NOTICES,code:scripts/check-opengauss-connector.sh | A:make licenses | S:Offline inventories after prefetch; GOROOT bound to GO_BIN; the connector needs its exact module, version, path, MIT result and hash; SQLite's MIT-0 needs its exact version and hash, no replace
check-public-text.sh[CG5T]: F:Runs the public-text safety scanner over release-facing source and assets | R:- | A:- | S:-
check-opengauss-connector.sh[CG8S]: F:Verifies local connector identity or downloads exact v1.0.8, authenticates origin and sums, replays the patch, and compares the complete tree | R:code:go.mod,code:third_party/openGauss-connector-go-pq.PROVENANCE.md,code:third_party/patches/openGauss-connector-go-pq-v1.0.8-aoci.patch,code:third_party/openGauss-connector-go-pq/go.mod | A:make opengauss-connector,--local-only | S:Local-only proves checked-in hashes and replacement; the full gate additionally downloads the pinned tag and requires byte-for-byte patch reproduction
bench-baseline.json[CG3M]: F:Records the advisory median ns/op of the 42 first-party benchmark results that scripts/bench-compare.py compares against | R:code:scripts/bench-compare.py | A:- | S:One developer machine's medians; CI only annotates
bench-compare.py[CG5M]: F:Runs the first-party benchmark groups, takes medians, writes bench-results.json, and compares against the committed baseline with warning annotations | R:code:scripts/bench-baseline.json,code:.github/workflows/full-confidence.yml | A:python3 scripts/bench-compare.py,--update-baseline,--from-results,--threshold | S:Never fails on slowness, only on a failing go test: runners are noisy; the 10,000-object migration fixtures run one iteration, one sample; names drop the -GOMAXPROCS suffix
check-coverage-floors.sh[CG5S]: F:Fails when any listed package's statement coverage is below its floor, from a fresh go test -cover run or an existing coverprofile | R:code:scripts/coverage-floors.txt,code:Makefile,code:.github/workflows/full-confidence.yml | A:bash scripts/check-coverage-floors.sh,--profile | S:Exit 1 on a package below floor, a listed package that does not exist, a failing test, or a missing floors file; exit 2 on bad arguments; --profile aggregates blocks with Go's statement weighting
coverage-floors.txt[CG5T]: F:Lists the safety-core and large packages with the minimum statement coverage each must keep, measured by go test -short -cover | R:code:scripts/check-coverage-floors.sh,code:.github/workflows/full-confidence.yml | A:- | S:A floor is the measured value minus two points, raised when coverage rises and never lowered to pass; cognitionbaseline sits at 0.0 because it has no package tests yet
dependency-review.sh[CG5S]: F:Reports, read-only, how far the go directive, direct modules, the connector pin, and every Action pin sit behind upstream, plus the open dependabot proposals | R:code:scripts/blackbox/ladder.json,code:go.mod,code:third_party/openGauss-connector-go-pq.PROVENANCE.md,code:.github/dependabot.yml,code:scripts/check-licenses.sh,code:internal/safety/files.go | A:bash scripts/dependency-review.sh | S:Upgrades nothing, each bump keeps its gate; a failed lookup exits 1, so a half review is never recorded; tags come peeled from git ls-remote, a floating major tag never counts; no gh skips section 5
check-index-quality.sh[CG5T]: F:Holds this repository's own index to the floors in scripts/index-quality-floors.txt by reading aoci --json index score on the tree as it stands | R:code:scripts/index-quality-floors.txt,code:internal/cli/index_score.go,code:.github/workflows/ci.yml,code:scripts/blackbox/ladder.json | A:bash scripts/check-index-quality.sh [binary] | S:Zero coverage and freshness need an aligned tree (CI: the committed one; a closure: after governance); no floors file exits 1, no binary or failed score 2; the score goes by file, stdin is the program
index-quality-floors.txt[CG5T]: F:Records the most violations each score dimension may report, the most C7+ Entries without an S in percent, and the budget status the index must keep | R:code:scripts/check-index-quality.sh | A:- | S:A floor only tightens; loosening one says why in the commit message, because the index got worse and the gate let it

===/<repository>/scripts/release/archive-smoke/===
main.go[CG5M]: F:Rejects release archives unless they contain only the binary, bilingual READMEs and logos, changelog, and all five legal assets, then executes Linux amd64 | R:code:.goreleaser.yml | A:go run ./scripts/release/archive-smoke --dist <dir> | S:Every entry must be regular, and exactly one Linux amd64 archive must report an aoci version

===/<repository>/scripts/release/===
clean-room-smoke.sh[CG8S]: F:Builds and exercises aoci in an isolated repository and verifies the bounded current-machine Volume Guide contract | R:code:internal/buildinfo/buildinfo.go | A:- | S:The fixture preserves the production-role split: ordinary source enters Index, counter_test.go enters Observe, tests/fixtures remains Exclude, and the MCP surface stays at nine tools; the Guide assertion pins the machine default cap of 50 over EXPECTED_AUTHORING_TARGETS, which counts business sources plus every governed file init generates, so changing either breaks here; its ldflags target internal/buildinfo like every build; the Guide pattern reads the continuation fields before database_volume_state since #162

===/<repository>/scripts/release/manifest/===
main.go[CG8L]: F:Generates and offline-verifies release manifest v2-v4 identities, tool contracts, artifact hashes, and signed-release descriptors | R:code:scripts/release/manifest/signed_release.go,code:scripts/release/manifest/signed_bundle.go,code:Makefile,code:internal/machinecontract/capabilities.go,code:internal/machinecontract/managed_scope.go | A:go run ./scripts/release/manifest,go run ./scripts/release/manifest --verify <manifest> | S:Generation rejects dirty source and commit mismatch; signed v4 is fail-closed while legacy v2 and v3 remain verify-compatible; baseline_scope_plan is no longer filled since 0.2.0-rc1 but stays an omitempty field so earlier manifests still decode under DisallowUnknownFields
signed_bundle.go[CG8M]: F:Validates Sigstore signature and GitHub provenance bundle structure against exact certificates, digests, subjects, workflow, ref, and commit | R:code:scripts/release/manifest/signed_release.go,code:scripts/release/manifest/main.go,code:.github/workflows/release.yml | A:- | S:Structural bundle validation does not replace the workflow's Cosign and gh cryptographic verification; certificate material must contain exactly one leaf
signed_release.go[CG9L]: F:Defines and verifies manifest v4 with six archive-SBOM pairs, 12 checksum subjects, 14 provenance subjects, and exactly 16 release assets | R:code:scripts/release/manifest/main.go,code:scripts/release/manifest/signed_bundle.go,code:.github/workflows/release.yml,code:scripts/release/archive-smoke/main.go | A:--signed-release,--publisher-repository,--publisher-workflow,--publisher-ref | S:Signature and provenance bundles cannot self-reference; only the canonical repository and workflow with exact main dry-run or version-matched Tag refs are admitted

===/<repository>/spec/public/===
README.md[CG8T]: F:Maps the public runtime contract set, including the engine library contract, and explicitly excludes private design and commercial material | R:- | A:- | S:-
aoci-code-cli-runtime-v1.txt[CG8M]: F:Specifies CLI identity, global flags, command and config behavior, bounded stdin, Legacy read-only, layout-scoped reads, exit status, and side-effect boundaries | R:- | A:- | S:aoci ui is loopback-only and read-only; aoci mcp opens no socket; scope activate: exit 2 with a saved preview awaits approval, approve asks yes, --reviewed-by records the Observe review; already_aligned writes nothing; config set --json reports the merged value; config set locale and index relocate are receipted, self-resuming transactions gating all others (exit 2); scope status carries repository_root; a Legacy layout is read-only save the Scope transaction; hooks fail open on a config failure; onboarding next_commands carry --repo; rule add --pattern batches pre-scan only
aoci-cognition-refresh-v1.txt[CG8M]: F:Specifies cognition checkpoint reasons, refresh decisions, receipts, generation semantics, the session line, the probe, compaction handoff limits, capacity stop | R:code:docs/cognition-refresh.md,code:spec/public/aoci-overview-delivery-v1.txt | A:- | S:The Host-capacity verdict lives in one server process and is never persisted; an incomplete Host-only confirmation leaves the reload attempt open, so the next compaction still interrupts it; the stop consumes the refresh generation with an uncertain receipt, carries no body, and never grants a cognition level; a confirmed complete delivery that large clears the verdict; a delta_since call is an explicit request, never a checkpoint, and the probe pass is its eligibility proof; the aligned Apply's terminal_proof is the alignment proof, Verify, Check, Guide no longer prescribed
aoci-cognition-state-v2.txt[CG8S]: F:Specifies independent delivery, usability, attestation, governance, and reliability cognition states | R:- | A:- | S:-
aoci-cognition-volumes-v1.txt[CG8L]: F:Specifies Volumes layout, starter Meta, batch plans, atomicity, repair bounds, terminal_proof, next_commands, observe review, optimization, parallel batches | R:code:spec/public/aoci-object-fras-v2.txt,code:spec/public/aoci-index-format-v1.txt | A:cognition-volumes/v1 | S:Starter expansion is init-only, Meta never retagged; a batch is cut by the transport budget, the contract travels once per process and generation; terminal_proof closes the final Apply, facts over inspector; orphans go as removals; next_commands is additive, Host-filled, and carries the executable and --repo <root>; observe_review takes the current digest and rides with the batch under auto; observe-only blocking answers review_observed_evidence, harder stops win, continuation leads; L4 siblings share a plan preimage, Apply accepts it or a replayed applied postimage
aoci-config-runtime-v1.txt[CG8T]: F:Specifies public configuration files, precedence, safe fields, and local-secret separation | R:- | A:- | S:Batch sizes and the transport budget are team-owned, the local layer cannot change them; exclude_root_dirs matches at the root and wherever git ignores that name, absence keeps the old any-depth identity; sensitive_name_rules is v1 or v2: new init persists v2, absence is v1 and the old identity, a later change is a Scope Change; human_approval_channel defaults tty_or_host_dialog; code_cognition_parallel_batches: absent or 1 is one batch, ceiling 4; locale is prospective, the Volumes switch rewrites only the Root marker, an absent team file takes that marker; the ai block is read only
aoci-database-cognition-authoring-v1.txt[CG8M]: F:Specifies evidence-bound Database Entry authoring, Bootstrap, validation, repair, and atomic Apply | R:code:spec/public/aoci-cognition-volumes-v1.txt,code:spec/public/aoci-database-evidence-v1.txt | A:Public Database Cognition Authoring v1 contract | S:Bootstrap advances a Root Baseline binding only when already managed and exact-preimage bound, never enrolls an absent Root, and permits later reconciliation solely for the exact canonical pre-fix state
aoci-database-evidence-v1.txt[CG8M]: F:Specifies catalog-only PostgreSQL, MySQL 5.7.6+, openGauss, and file-based SQLite Evidence identity, collection, snapshots, Baselines, drift, and acceptance | R:code:spec/public/aoci-database-table-fras-v1.txt,code:docs/database-evidence.md,code:internal/dbevidence/collector_opengauss.go,code:internal/dbevidence/collector_mysql_version.go,code:internal/dbevidence/collector_sqlite.go | A:Database Evidence v1 | S:openGauss is additive exact 6.0.5 A/PG support with strict connection and fail-closed catalog limits; MySQL gates CHECK, index expression and visibility queries by server version and refuses MariaDB and sub-5.7.6 servers before any table query; Evidence JSON identity and the nine-tool MCP surface remain unchanged; SQLite binds its exact configured path as the database identity, needs a collector-capable binary on every host, older decoders reject its untyped columns, and unsupported catalog features never yield partial Evidence
aoci-database-table-fras-v1.txt[CG8T]: F:Specifies model-authored table F/R/A/S and canonical object references over accepted PostgreSQL, MySQL, or openGauss Evidence | R:code:spec/public/aoci-database-evidence-v1.txt,code:spec/public/aoci-database-cognition-authoring-v1.txt | A:Database Table FRAS v1 | S:Automatic table cognition generation and formal Database Volume creation remain outside this contract
aoci-host-capability-and-interaction-v1.txt[CG8M]: F:Specifies capability discovery, host interaction, the terminal and host-dialog approval channels, and machine identity contracts | R:- | A:- | S:The terminal channel requires an actual character-device TTY and the answer yes to a plain summary, the digest bound by the approval record; --yes, piped model approval, and reuse are forbidden; the host dialog shows a change AOCI reads from disk, records only the person's answer, applies nothing, and counts only under human_approval_channel; high-risk content, reversal, and rollback stay terminal-only; Fresh policy-bound auto remains a distinct non-human mechanism; on 2026-07-28 the dialog is an input-request round whose answer counts only beside the requestState that round issued
aoci-host-cognition-messaging-v2.txt[CG8S]: F:Specifies concise user-facing messaging for cognition delivery and verification outcomes | R:- | A:- | S:-
aoci-index-format-v1.txt[CG8S]: F:Defines the public text interoperability contract for Cognition assets, Entries, Volume layout, directory roots, and validation compatibility | R:code:spec/public/aoci-cognition-volumes-v1.txt,code:spec/public/aoci-code-cli-runtime-v1.txt,code:internal/index/parser.go,code:internal/index/editor.go,code:internal/cognition/objects.go | A:AOCI Public Cognition Format v1 | S:Code section absolute roots are historical coordinates, not access paths or identities; a new index records the neutral root /<repository>, older ones keep theirs until index relocate, and the starter Meta names it in a comment line; readers use the invocation root for repository-relative CanonicalRefs, preserve formal bytes on clone, and fail closed on unsafe mapping; names are never escaped: a header reads to its final slash, a bracketed name to the tag before ': F:', and an Entry name is bare
aoci-managed-scope-and-budget-v1.txt[CG8M]: F:Specifies governed roles, authoring debt, coverage-reduction protection, ratifiable blockers, host-independent paths, posture, transactions, and budgets | R:code:internal/scopechange/authorization.go,code:internal/managedscope/evaluate.go,code:spec/public/aoci-cognition-volumes-v1.txt | A:- | S:Refusing auto is half the contract: review-ratifiable blockers set interaction_required, safety boundaries have no reviewer; under Volumes candidates are policy only and a changed Index source is source_stale_retained, not blocked; an ungoverned git-ignored path never enters the Envelope; Whole-Index thresholds only name a status; S hard limit = max(S band, Meta rune quota); the Legacy Entry candidate is the one Legacy index write since 0.2.0; under a Volumes Root formal assets are outside policy (index role, guard records, enabled file rule refused); a Legacy index stays rule-governed
aoci-mcp-runtime-v1.txt[CG8S]: F:Specifies MCP server identity, negotiated revisions, stdio JSON-RPC behavior, read-only configuration, nine-tool surface, description scope, per-layout writes | R:code:spec/public/aoci-cognition-volumes-v1.txt,code:spec/public/aoci-host-capability-and-interaction-v1.txt | A:- | S:initialize answers at most 2025-11-25, an unlisted sessionless revision gets -32022; on a Legacy layout write tools answer legacy_read_only_migrate_required (Maintain: a stopped finding with next_commands) while reads continue; aoci_report refuses on both; descriptions carry no procedure; tools/list shows cognition_receipt and probe_answers as plain objects, calls keep closed shapes; human_approval asks a person by form elicitation on both layouts, observe_review on Volumes only; include_instructions is additive; the server never writes configuration, a pre-Locale project reads as zh-CN
aoci-object-fras-v2.txt[CG8T]: F:Specifies canonical object identities, expanded starter dictionaries, compact tags, and FRAS v2 field limits | R:code:spec/public/aoci-cognition-volumes-v1.txt | A:repository-cognition-object/v2,compact A+B+C+[D]+E | S:Starter G means cross-domain and Z requires understood evidence with no named fit; insufficient evidence is never Z or an S constraint, and existing formal Meta remains authoritative
aoci-overview-delivery-v1.txt[CG8L]: F:Specifies Overview chunking, receipts, challenge ordinals, pass share, split proof, reused guarded deliveries, capacity stop, and incremental delivery (L5) | R:code:spec/public/aoci-cognition-refresh-v1.txt | A:- | S:v2 token opaque and ephemeral, chunk receipt stays v1, retention limits are machinecontract numbers; a failed cursor names overview_snapshot_changed or overview_session_unavailable_restart_required, both restart at Chunk 1; capacity_stop is a bodiless delivery mode; L5 keeps only base identities and line digests; a delta needs a probe pass, no pending compaction, under half the objects, a retained delivery; a partial delta Attestation drops the base; a deletion-only delta has no ordinal, passes on an empty answer list; the reuse guard checks sources via the fingerprint cache
aoci-safe-inventory-and-scope-refresh-v1.txt[CG8S]: F:Specifies safe filesystem inventory and marks the Baseline Scope Refresh v1 family retired in favour of Managed Scope | R:- | A:- | S:An ignored directory collapses into one exclusion only when every path beneath is hard-excluded, changing no identity; artifact names are configured, never built in: exclude_root_dirs for new repositories, exclude_dirs for old, an absent root list keeps the old identity; sensitive_name_rules v2 reads file names only, exempts templates, enters the rules identity, so a change is a Scope Change; a non-Git container reads child .git repositories through their Git, container-relative (#54); baseline-scope-*/v1 is retired since 0.2.0-rc1, a leftover scope-<id>.json intent is invalid
aoci-system-cognition-runtime-v1.txt[CG8T]: F:Specifies narrow relation, lineage, impact, and evolution projections over governed cognition | R:- | A:- | S:All projections are deterministic, sorted, derived, and read-only: they create no Apply, CAS, Recovery, Baseline, Ledger, approval, or persistence lifecycle and never invent missing relations
s-field-discipline.txt[CG8S]: F:Defines the admission rule and quota discipline for non-inferable safety facts in S fields | R:code:internal/index/quota.go | A:- | S:The two machine gates differ on purpose: the warning-level curation check honours a declaration both ways, while the error-level object gate honours only a looser one; the C6+ look at where behaviour is decided is writing discipline the machine never judges
s-field-discipline.en.txt[CG8S]: F:English rendering of the S-field and Entry writing discipline | R:code:spec/public/s-field-discipline.txt | A:- | S:The Chinese file is the normative original scanned by cross-layer quota tests; this rendering carries no machine-scanned declarations and must not fork rule authority
aoci-engine-library-v1.txt[CG8T]: F:Specifies the importable engine package: identity, additive stability, the read projections, in-process tools, version reporting, layouts, and import limits | R:code:engine/doc.go,code:spec/public/aoci-mcp-runtime-v1.txt | A:- | S:Additive within a major version; results are projections, so the format, Volumes, scope, delivery, and MCP contracts keep their authority; the connector replace is a packaging limitation, not a term

===/<repository>/textassets/===
README.txt[CG5S]: F:Explains generated public runtime text ownership, locale layout, manifests, and embedding rules | R:- | A:- | S:-
agents_assets.go[CG5T]: F:Defines stable IDs for locale-specific AGENTS, Codex MCP, and Codex compaction prompt and reload-hook templates | R:code:internal/hooks/codex.go,code:textassets/manifests/agents.json | A:TemplateAgentsMD,TemplateCodexMCPConfig,TemplateCodexCompactPrompt,TemplateCodexCompactHook | S:-
catalog.go[CG5L]: F:Loads the generated asset catalog and provides strict locale and manifest lookups, with the embedded manifest decoded and validated once per process | R:code:textassets/ui.go,code:internal/cli/command_localization.go | A:ReadManifest,Load | S:ReadManifest returns a clone of the memoized manifest, so callers never share state; custom asset trees still decode on every call; before the memo one command tree cost half a second per invocation
cli_help_final_assets.go[CG5T]: F:Embeds the three finalized localized CLI help contract IDs registered by the command layer | R:- | A:- | S:The retired command helps left with 0.2.0; what remains is release-locked by the final manifest test
guide_assets.go[CG5S]: F:Embeds the Guide text asset IDs and renders the observe-review and blocked-continuation instruction lines Guide and Maintain share | R:- | A:ObservedReviewInstructions,BlockedContinuationInstructions | S:The Legacy stage and stop instruction IDs left with 0.2.0; the four review lines and the one continuation line are message keys both locales must carry; the caller decides precedence
help_assets.go[CG5T]: F:Maps localized command help assets to their runtime consumers | R:- | A:- | S:Help IDs for the retired Legacy commands left with 0.2.0; remove-entry help now locks aoci_maintain, deleted, orphan, verify, and --preview as tokens; index relocate has short and long IDs
init_assets.go[CG5T]: F:Embeds initialization messages, templates, and automation-mode explanations | R:- | A:- | S:-
maintain_assets.go[CG5T]: F:Embeds localized Maintain descriptions, failure guidance, and final or duplicate Volumes proof actions | R:code:internal/mcptools/tools_auto_result.go,code:textassets/manifests/maintain.json | A:ContractMaintainActionApplyFinalProof,ContractMaintainActionApplyDuplicateFinalProof | S:Terminal actions forbid another formal cognition write but still require audit-capable Verify, Aggregate Check, and Guide before completion; Legacy dictionary and candidate assets left with 0.2.0
manifest.json[CG5S]: F:Defines the top-level runtime asset manifest: runtime rules and the Guide baseline-first assets consumed by blocked remediation | R:- | A:- | S:The prompt assets of the Legacy endpoint pipeline left with 0.2.0; runtime rules must carry the capacity_stop and host_context_capacity_exceeded tokens
mcp_assets.go[CG5T]: F:Embeds MCP descriptions, input-schema text, and Overview attestation prompts | R:- | A:- | S:-
model_prompt_assets.go[CG5T]: F:Embeds the database Entry authoring rules prompt ID | R:- | A:- | S:The Legacy endpoint prompt IDs left with 0.2.0
render.go[CG5T]: F:Renders strict text templates with validated variables and deterministic output | R:- | A:- | S:Scalar assets render without data; the endpoint prompt templates and their user-message renderers left with 0.2.0
ui.go[CG5L]: F:Loads localized user-visible messages through the generated catalog and relocalizes an exact message across locales | R:code:textassets/catalog.go | A:RelocalizeMessageExact | S:The reverse index (value to locale and key) is built once with the catalog in manifest locale order, so an ambiguous value reports its keys deterministically instead of in map order
validate.go[CG5L]: F:Validates locale parity, manifests, variables, protocol tokens, and duplicate fact sources | R:- | A:- | S:-

===/<repository>/textassets/manifests/===
agents.json[CG5S]: F:Enumerates AGENTS, Codex MCP, and Codex compaction templates and host integration assets across supported locales | R:code:textassets/agents_assets.go | A:- | S:-
cli-help-final.json[CG5T]: F:Enumerates the three finalized CLI help assets whose presence and symbols are release contracts | R:- | A:- | S:The ai and Legacy index command helps left with 0.2.0; index-agent-long locks guide:, not plan, stage, or curation
cli-help.json[CG5S]: F:Enumerates the broader localized CLI help asset set with its locked protocol tokens | R:- | A:- | S:remove-entry: aoci_maintain, deleted, orphan, verify, --preview; index-long: inventory:, header show:, score:, agent guide:, relocate:; index-relocate: /<repository>, .aoci/transactions, --dry-run
init.json[CG5S]: F:Enumerates localized initialization templates and status messages while locking the expanded starter Meta protocol tokens | R:- | A:- | S:Automation hints are Volumes-worded (aoci_update_entry, Apply); skeleton hint names cognition onboard start; the auto hint carries each auto status and terminal_proof; volume-meta locks /<repository>
maintain.json[CG5S]: F:Enumerates localized Maintain descriptions, actions, Optimization anchors, batch contracts, and the final Volumes terminal_proof actions | R:code:textassets/catalog.go,code:textassets/maintain_assets.go | A:Maintain text-asset manifest | S:Nine assets; used_by names production symbols, the write consumer being handleMCPUpdateBatchReviewed; final actions lock terminal_proof, check_passed, guide_complete
mcp-tools.json[CG5M]: F:Enumerates localized nine-tool descriptions and input-schema assets plus additive Maintain optimization and existing Code batch identity anchors | R:code:textassets/catalog.go | A:- | S:The messages asset's zh-CN locale anchor is the receipt phrase of guide.recovery_pending.cause; protocol tokens must name live message keys; update-entry's zh-CN anchor: the one-pass Finding phrase
model-prompts.json[CG5T]: F:Enumerates the one surviving model-authoring prompt, the database Entry authoring rules, with its protocol and locale anchors | R:code:textassets/model_prompt_assets.go | A:- | S:The Header and Entry endpoint prompts left with 0.2.0
read-observation.json[CG5T]: F:Enumerates read-operation observation and audit disclosure assets | R:- | A:- | S:-

===/<repository>/internal/bootstrapapply/===
approval.go[CG7M]: F:Creates and validates digest-bound terminal, host-dialog, and policy-bound-auto Bootstrap approvals, applies the team channel, rejects ineligible repositories | R:code:internal/bootstrapapply/transaction.go,code:internal/bootstrapapply/prepare.go,code:internal/bootstrapapply/eligibility.go,code:internal/config/automation.go,code:internal/config/approval.go | A:RecordApproval,RecordHostDialogApproval,RecordPolicyBoundAutoApproval,ValidateApproval,AdmitApprovalChannel,EvaluateAutoEligibility | S:Approval is an audit binding, not authentication; automation=off forbids Apply; policy-bound auto is limited to new projects with no mature governance history; the channel is judged when Apply starts
codec.go[CG7S]: F:Strictly encodes and decodes bootstrap preview, approval, intent, and receipt artifacts | R:code:internal/jsonstrict/duplicate.go | A:- | S:Decoders reject duplicate or case-colliding keys, unknown fields, trailing JSON, and unsupported contract versions; Encode emits indented newline-terminated JSON
eligibility.go[CG7M]: F:Evaluates whether a bootstrap envelope qualifies for policy-bound automatic authorization | R:- | A:- | S:Eligibility is read-only audit evidence; AutoReady requires verified host-model provenance and zero blockers; accepted Evidence is required only from collectable sources
prepare.go[CG7M]: F:Freezes bootstrap postimages, guards, risks, digests, and recovery direction before formal writes | R:- | A:- | S:Prepare performs no filesystem write and rejects any existing Baseline; it orders enabled Volume postimages before Root and places Baseline after Root
rollback.go[CG7S]: F:Restores an incomplete bootstrap to its proven absent or exact preimage | R:- | A:- | S:Only an incomplete active Bootstrap can roll back; third-party guard drift fails closed, exact preimages are restored, and absent preimages move to recovered quarantine rather than being deleted
status.go[CG7S]: F:Derives Bootstrap recovery and terminal transaction status from exact formal, staging, intent, and receipt bytes | R:code:internal/cognitiontxn/transaction.go,code:internal/bootstrapapply/transaction.go | A:Pending,Status | S:No saved mutable phase is trusted; a postimage followed by a preimage, missing or wrong staging, unknown bytes, or an unsafe file type is a recovery conflict
transaction.go[CG8L]: F:Executes and idempotently resumes digest-bound Cognition Bootstrap publication through staged atomic postimages and internal verification | R:code:internal/cognitionplan/plan.go,code:internal/cognitiontxn/transaction.go,code:internal/cognitionbaseline/verify.go,code:internal/fs/atomic.go | A:Apply,Resume | S:The immutable intent binds the exact envelope and approval; any preimage, staging, or postimage ambiguity fails closed, and completion, Ledger, and archive occur only after all formal assets and Baseline verify; a host-dialog approval is admitted by the team channel only before the Intent exists, so Resume never judges it again
types.go[CG7S]: F:Defines bootstrap envelopes, approvals, transaction intents, receipts, and status structures | R:- | A:- | S:-

===/<repository>/internal/codebatch/===
receipt.go[CG9L]: F:Builds and validates deterministic receipt-bound Code plans and unambiguous submission-binding diagnostics | R:code:internal/codebatch/types.go,code:internal/mcptools/tools_write_volume_commit.go,code:internal/jsonstrict/duplicate.go | A:BuildPlan,BuildPlanWithBudget,SelectWithBudget,PrefixWithinBudget,ValidateSubmission,LoadReceipt | S:A batch is a deterministic ordered prefix of the plan, chosen by Select for BuildPlan and any pre-issue judge alike, never consulting Entry semantics; the byte Budget cuts that prefix before the candidate that would exceed it, keeping at least one, changing the batch but never the plan identity, which hashes every target; binding repair needs current receipt sources, stale or unprovable state stays stopped; receipts reject case-colliding keys; matchSubmission is the half a sibling shares, savePlan records its logical plan outside the batch identity
types.go[CG8S]: F:Defines machine-visible Code authoring targets, receipts, plans, candidates, and binding-mismatch evidence | R:code:internal/codebatch/receipt.go | A:Target,Receipt,Plan,Submission,SubmissionIssue,SubmissionError | S:SubmissionError carries only pre-write machine binding facts; the receipt keeps one decode-only legacy field so plans issued while relations were still a machine constraint stay loadable across the upgrade instead of wedging in flight; a Plan's Candidates leave the wire (omitempty) so a response never repeats an Entry, and TransportBudgetBytes reports the team budget that cut the batch; LogicalPlan, SiblingOf and Siblings are the parallel facts, outside every batch identity and absent from a single batch
parallel.go[CG8L]: F:Keeps one logical plan of N sibling batches against a retained preimage, records each applied sibling's writes, and proves a later sibling's Volume by replay | R:code:internal/codebatch/receipt.go,code:internal/codebatch/types.go,code:internal/index/editor.go,code:internal/mcptools/tools_maintain_parallel.go,code:internal/mcptools/tools_write_volume_commit.go | A:SaveParallelPlan,LoadParallelPlan,ReplayProves,SaveApplied,BuildSiblingPlan,ValidateParallelSubmission | S:The plan, its preimage, and the applied records are runtime assets under .aoci/drafts/code-cognition that enter no identity and go when the plan completes or is invalidated; a sibling's receipt names the plan preimage, and the replay, in apply order through the same editor (create, update, delete), is the only proof of the Volume it meets; two plan records read as none; applied orders must be gapless; allowPostimage is recovery's own proof and skips the replay

===/<repository>/internal/cognitionplan/===
codec.go[CG7T]: F:Strictly decodes and version-checks cognition Plans, layout Candidates, and Previews | R:code:internal/cognitionplan/types.go,code:internal/jsonstrict/duplicate.go | A:DecodePlan,DecodeCandidate,DecodePreview | S:Duplicate and case-colliding keys are rejected before the strict decoder runs
facts.go[CG7L]: F:Captures immutable filesystem, source, configuration, and evidence facts for cognition planning | R:code:internal/cognitiontxn/transaction.go,code:internal/dbevidence/config.go | A:- | S:Snapshots formal assets before and after, rejects pending recovery (cognitiontxn.Pending) or concurrent formal changes, keeps formal objects out of Managed Scope; sources compare by shared manifest
identity.go[CG7T]: F:Provides length-framed domain-separated hashing and canonical JSON helpers for cognition identities | R:code:internal/cognitionplan/plan.go,code:internal/cognitionplan/provenance.go | A:- | S:Field kind, order, and exact bytes are identity inputs; canonical JSON appends one LF
mapping.go[CG7S]: F:Maps every Legacy header atom, section, Entry, and unparsed semantic line into a byte-reversible model-review mapping | R:code:internal/cognitionplan/types.go,code:internal/index/parser.go | A:- | S:No Entry is automatically preserved: every Legacy Entry starts model_regeneration_required, the Legacy self-Entry is Root-owned, and ambiguity remains explicit coverage debt
plan.go[CG8M]: F:Discovers uninitialized, Legacy, or Volumes layouts and builds deterministic bootstrap or migration plans | R:- | A:- | S:Plans and candidate frameworks are read-only authoring requests; MODEL_AUTHORING_REQUIRED placeholders are neither semantics nor approval, and Migration planning has no Apply path
provenance.go[CG8S]: F:Binds host-model semantic authoring provenance to Plan, Evidence, and complete Candidate bytes | R:- | A:- | S:The Host supplies the authoring run, origin, and final receipt; deterministic code may validate and bind them but never manufactures semantic provenance or makes Candidate identity self-referential
replay.go[CG7S]: F:Compares approved migration Preview content while excluding append-only runtime Ledger growth from replay identity | R:code:internal/cognitionplan/plan.go,code:internal/cognitionplan/types.go | A:PreviewReplayMismatches | S:Only content identities may replay: candidate, physical/logical diff, mapping, and approval mismatches are exposed as digests and counts without candidate or evidence bodies
types.go[CG7M]: F:Defines cognition Plan, authoring task, candidate, mapping, preview, and evidence structures | R:- | A:- | S:-
validate.go[CG8L]: F:Validates complete candidate layouts, mappings, source guards, budgets, and approval digests | R:- | A:- | S:Validation is read-only and cannot accept approval or Apply; preview_ready requires zero risks and a fully valid projected CognitionSet, and a dangling or ambiguous R is never a risk

===/<repository>/internal/curation/===
classify.go[CG7M]: F:Classifies special files for semantic inclusion, exclusion, review, or technical skip | R:- | A:- | S:Precedence is config exclusion, a source-SHA-current decision, then profile; stale decisions are ignored, and Pending stays within Skipped so the Missing three-way partition is conserved
decode.go[CG7T]: F:Strictly decodes and normalizes one Curation document for draft or formal use | R:code:internal/curation/model.go,code:internal/jsonstrict/duplicate.go | A:DecodeDocument | S:Stage may omit audit fields only when requireAudit=false; duplicate, case-colliding, or unknown keys, multiple top-level values, trailing JSON, and invalid Decisions always fail
model.go[CG7S]: F:Defines Curation decisions, evidence, confidence, review, and document identity | R:- | A:- | S:A decision is valid only for its source SHA; config curation_exclude has precedence, and Pending Curation remains a subset of Skipped Missing so the three-way Missing partition stays conserved
profile.go[CG7S]: F:Provides stable Curation profiles and rules for common repository object classes | R:code:internal/baseline/fingerprint_cache.go | A:ProfilePath,BuildProfiles,OpenProfiler | S:Targets hash first: empty is zero bytes, oversize exceeds 1 MiB, binary lacks a normalized digest (NUL in 8000 bytes); ProfilePath is pure, a Profiler keeps one cache per batch; errors stay explicit
store.go[CG7M]: F:Loads and atomically stores reviewed Curation decisions | R:- | A:- | S:Persistent decisions require audit fields and exact source SHA; Save backs up before atomic write, Merge keeps one path-current decision, and output is path-sorted for stable diffs

===/<repository>/internal/databasebootstrap/===
prepare.go[CG7M]: F:Builds guarded Database Cognition Bootstrap previews and redacted diagnostics from aligned Code governance and accepted catalog Evidence | R:code:internal/dbevidence/store.go,code:internal/volumegovernance/facts.go,code:internal/databasebootstrap/transaction.go,code:internal/baseline/baseline.go | A:Prepare,Diagnose | S:A Root Baseline binding advances only from its exact raw preimage, keeping its role, and an absent one is not enrolled; only collectable sources are bound; no network, business-row, or DDL/DML access
rollback.go[CG7S]: F:Restores an interrupted Database Volume bootstrap to exact preimages | R:- | A:- | S:Rollback accepts only exact preimage/postimage states; unknown bytes stop, and a created Database Volume is moved into the transaction's recovered directory instead of being deleted in place
transaction.go[CG7L]: F:Executes and idempotently resumes staged Database Bootstrap across Database, Root, and Baseline postimages with evidence guards and verification | R:code:internal/cognitiontxn/transaction.go,code:internal/dbevidence/store.go,code:internal/baseline/baseline.go,code:internal/jsonstrict/duplicate.go | A:Apply,Resume,Pending | S:Writes stay Database→Root→Baseline; new previews verify Database and managed-Root bindings; pre-fix v1 recovery keeps its exact frozen Baseline postimage; recovery JSON rejects case-colliding keys
types.go[CG7T]: F:Defines Database bootstrap evidence, preview, recovery, result, and redacted Diagnostic wire types | R:code:internal/cognitiontxn/transaction.go,code:internal/machinecontract/cognition_planner.go | A:EvidenceSource,Preview,RecoveryIntent,Result,Diagnostic | S:Diagnostic carries only allowlisted stable cause_code and safe_next_action tokens; these structures never generate table FRAS or read database content

===/<repository>/internal/dbcognition/===
receipt.go[CG7M]: F:Selects evidence-bounded Database cognition candidates and persists or validates their deterministic complete-batch receipt | R:code:internal/dbcognition/state.go,code:internal/dbevidence/store.go,code:internal/jsonstrict/duplicate.go | A:BuildPlan,ValidateSubmission,SaveReceipt,LoadReceipt | S:Candidate identity binds the Database Volume SHA and exact table Evidence; every target is submitted; unrelated drift does not invalidate a target-bound batch; receipts reject case-colliding keys
state.go[CG7M]: F:Derives Database cognition alignment from Volume, evidence, and binding state | R:- | A:- | S:Evidence counts only when selection matches its manifest and bindings match source, evidence version, table and Entry digests; a collectorless source blocks nothing and alone means no configuration
types.go[CG7T]: F:Defines Database cognition assessments, evidence-bound receipts and candidates, batch plans, bindings, and submission identities | R:code:internal/dbcognition/state.go,code:internal/dbcognition/receipt.go | A:Assessment,Receipt,Candidate,Plan,Submission | S:-

===/<repository>/internal/hooks/===
claude.go[CG7S]: F:Installs and idempotently merges project-scoped AOCI MCP and Claude PreToolUse hook configuration | R:code:internal/hooks/status.go,code:textassets/catalog.go | A:InstallClaudeMCP,InstallClaudeHook | S:Writes merge into existing .mcp.json and settings with backups instead of overwriting; MCP uses explicit binary and repository paths, and hook detection shares the exact status predicate
codex.go[CG7M]: F:Installs the idempotent repository-local Codex MCP configuration table and the AOCI-managed Codex compaction prompt and reload hook | R:code:internal/hooks/installer.go,code:textassets/agents_assets.go,code:internal/cli/hook.go | A:InstallCodexMCP,InstallCodexCompaction,ValidateCodexCompactionInstall | S:Existing bytes are preserved and only missing AOCI-managed tables are appended; project trust remains a user action; bare and quoted table headers count, a commented one does not
installer.go[CG7M]: F:Installs or updates supported host integration files, including the Codex compaction assets, without overwriting unrelated configuration | R:code:internal/hooks/opencode.go,code:internal/hooks/codex.go | A:Detect,Install | S:Only the marked AGENTS block may be replaced; Windows paths are slash-normalized before TOML or JSON rendering; qoder reuses the Claude Code .mcp.json and has no hooks; backups are written 0600
pretool.go[CG7M]: F:Injects the target Entry and drift warning before Agent writes, with optional strict stale blocking | R:code:internal/baseline/baseline.go,code:internal/index/parser.go,code:internal/config/config.go,code:internal/cognition/loader.go,code:textassets/ui.go | A:HandlePreTool | S:Fails open on bad paths, config, Index, Baseline or catalog text; config loads read-only, never migrated; reads the Code Volume under Volumes v1; only real stale plus hook_strict blocks
status.go[CG7T]: F:Inspects installed host integration state and reports drift or missing assets | R:code:internal/hooks/opencode.go | A:- | S:All read or parse failures return false rather than installed, and each predicate reuses the same marker or parser as its installer to prevent status/write drift
opencode.go[CG7M]: F:Validates and atomically installs the project-root OpenCode V1 mcp.aoci local server bound to absolute AOCI binary and repository paths | R:code:internal/hooks/installer.go,code:internal/hooks/status.go,code:internal/fs/atomic.go,code:internal/jsonstrict/duplicate.go | A:ValidateOpenCodeMCPInstall,InstallOpenCodeMCP | S:Duplicate keys (exact check; case-distinct user keys are legal), JSONC, V2 mcp.servers, alternate paths, conflicts, unsafe targets fail closed; exact config is a no-op; create or merge is CAS-bound

===/<repository>/internal/indexgen/===
inventory.go[CG7M]: F:Builds deterministic index inventory views from Safe Inventory and parsed cognition | R:- | A:- | S:With Managed Scope, only Index-role files form the missing-candidate universe; Observe and Exclude are counted but never emitted as Items, while Legacy falls back to WalkRepo
missing.go[CG7S]: F:Computes actionable missing and orphan Entry sets under current scope and Curation | R:- | A:- | S:Actionable, CurationExcluded, and Skipped exactly partition raw Missing; Included is a subset of Actionable and Pending a subset of Skipped, never additional totals
score.go[CG7L]: F:Calculates cognition coverage, structural quality, and bounded diagnostic scores | R:- | A:- | S:Coverage counts only actionable Missing, while freshness adds unresolved Pending, Orphan, Stale, Unbaselined, and policy-required Observe drift; line-ending-only changes never add debt
score_types.go[CG7S]: F:Defines score categories, findings, inventories, and machine-readable result structures | R:code:internal/index/quota.go | A:- | S:A rejected quota dimension name reads as present and unreadable, never absent; quoted spellings must survive the active Locale; Layout, Volumes, Budget are omitempty so a Legacy score keeps its bytes
ui.go[CG7T]: F:Formats Locale-bound index-generation messages and exposes text-asset lookup failures inline | R:code:textassets/catalog.go | A:- | S:-
score_volumes.go[CG7M]: F:Scores a Volumes v1 set on the nine Legacy dimensions, every drift, budget, and E scale number projected from the governance facts, never measured again | R:code:internal/indexgen/score.go,code:internal/indexgen/score_types.go,code:internal/volumegovernance/score_input.go,code:internal/cli/index_score.go | A:BuildVolumeScore,VolumeScoreInput | S:Objects are judged under their scoped dictionary, a table's format path its name; coverage, freshness, escale are Code facts; Missing is actionable, raw adds held sources; escale needs numeric bands

===/<repository>/internal/jsonstrict/===
duplicate.go[CG7M]: F:Rejects duplicate JSON object keys, exactly or under case folding, before decoding governance or protocol artifacts | R:- | A:RejectDuplicateKeys,RejectDuplicateKeysFold | S:The fold variant mirrors encoding/json's case-insensitive field match for struct targets; map targets keep the exact check; syntax, types, unknown fields, trailing JSON stay the strict decoder's job

===/<repository>/internal/ledger/===
ledger.go[CG7L]: F:Best-effort appends versioned local JSONL audit and measurement events and reads recent valid history | R:- | A:Append,Recent,EstimateTokens | S:Non-authoritative: failed writes never block; a corrupt or over-1 MiB line is skipped and counted; secrets, source, prompts, chat bodies are never recorded; schema 9 adds governance outcome tokens

===/<repository>/internal/migrationapply/===
approval.go[CG7S]: F:Creates and validates terminal or host-dialog digest-bound Legacy migration approval audit records and admits them per the team channel | R:code:internal/migrationapply/transaction.go,code:internal/cognitiontxn/transaction.go,code:internal/config/approval.go | A:RecordApproval,RecordHostDialogApproval,ValidateApproval,AdmitApprovalChannel | S:Approval is an audit binding, not cryptographic authentication; envelope, mapping, write set, recovery policy, actor, and UTC time are revalidated under Apply; the channel is judged before the Intent
codec.go[CG7S]: F:Canonicalizes and strictly version-decodes Migration snapshots, mappings, apply, recovery, receipt, and reversal artifacts | R:code:internal/migrationapply/types.go,code:internal/machinecontract/cognition_planner.go,code:internal/jsonstrict/duplicate.go | A:Encode,DecodeLegacySnapshot,DecodeMapping,DecodeApplyEnvelope,DecodeRecovery,DecodeReceipt | S:Decoders reject duplicate or case-colliding keys, unknown fields and trailing JSON; Legacy Snapshot remains v1 while current Migration, Recovery, Receipt, and Reversal artifacts require v2
mapping.go[CG7L]: F:Builds model-review migration mapping tasks and validates byte/field preservation, regeneration groups, coverage, and canonical identity | R:code:internal/migrationapply/snapshot.go,code:internal/migrationapply/prepare.go,code:internal/cognitionplan/mapping.go,code:internal/cognition/loader.go | A:BuildMappingTemplate,ValidateMapping,VerifyMapping | S:Templates give coordinates only; roles, destinations, split/merge, and review stay model-owned; Apply grade needs full, unambiguous coverage; field atoms are indexed once, never rescanned per Entry
prepare.go[CG7M]: F:Freezes migration postimages, mapping, guards, risks, and recovery direction | R:- | A:- | S:Prepare is zero-write and requires exact Snapshot, Plan, Candidate, guards, and Ledger; targets must be absent or match runtime-boundary bytes, and the final write order keeps Root then Baseline last
replay.go[CG7T]: F:Emits digest-only diagnostics for migration envelope and approval replay mismatches | R:code:internal/migrationapply/transaction.go,code:internal/cognitionplan/validate.go | A:ReplayMismatchItem,ReplayMismatchReport,ReplayMismatchError | S:Diagnostics never expose source, FRAS, Snapshot, Evidence, credential, or database bodies and always report formal_writes_started=false; residual deep inequality becomes a runtime-metadata mismatch
reversal.go[CG7L]: F:Plans, approves, applies, resumes, and audits exact Legacy restoration for a completed cognition migration | R:code:internal/migrationapply/transaction.go,code:internal/cognitiontxn/transaction.go,code:internal/ledger/ledger.go | A:PrepareReversal,RecordReversalApproval,ApplyReversal,ResumeReversal,ReversalStatus | S:Reversal requires exact migration postimages and external guards plus Ledger proof of no later cognition write; Root and Baseline CAS precede no-replace archival of Volume files
rollback.go[CG7S]: F:Restores incomplete migration writes to their proven Legacy preimages | R:- | A:- | S:Rollback never operates on an archived completed transaction, rejects other pending or guard drift, and moves postimage Volumes into recovery only after exact Legacy/Baseline restoration
schema.go[CG7T]: F:Derives closed JSON Schema documentation and test artifacts for versioned migration contracts from Go types | R:code:internal/migrationapply/types.go | A:JSONSchemas | S:The strict decoder and typed validators, not these derived schemas, remain executable authority; required fields follow omitempty and each schema const-binds its contract version
snapshot.go[CG7L]: F:Captures immutable Legacy index, baseline, configuration, and source evidence before migration | R:- | A:- | S:Capture is read-only and fails closed on mixed layout, recovery, drift, or unsafe sources; exact Legacy/Baseline bytes and lexical ranges are identity-bound for reversible Apply mapping
status.go[CG7S]: F:Derives migration transaction and recovery status from disk identities | R:- | A:- | S:Status trusts current file bytes and immutable receipts, never a saved phase; active staging and write order are checked, and archived transactions require a terminal receipt or rollback result
transaction.go[CG7L]: F:Applies and idempotently resumes approved Legacy-to-Volumes postimages through staged CAS, verification, receipts, Ledger, and recovery archival | R:code:internal/cognitiontxn/transaction.go,code:internal/cognitionbaseline/verify.go,code:internal/fs/atomic.go | A:Apply,Resume | S:Volume files publish dormant before Root activates; staging and intent precede formal writes; Baseline is last; unknown or third-party bytes fail closed; the approval channel is judged pre-Intent only
types.go[CG7M]: F:Defines migration snapshots, mappings, envelopes, approvals, intents, receipts, and results | R:- | A:- | S:-

===/<repository>/internal/onboarding/===
store.go[CG7M]: F:Persists onboarding sessions and immutable plan, evidence, candidate, receipt, and human-approval artifacts, and exposes a review awaiting its person | R:code:internal/jsonstrict/duplicate.go | A:AwaitingApproval,HumanApprovalPath,SaveHumanApproval,HumanApprovalArtifact | S:Session JSON rejects duplicate, case-colliding, unknown, and trailing fields; artifacts are immutable, updates use CAS, targets stay sorted, security counters stay zero for network, rows, DDL/DML
types.go[CG7S]: F:Defines persistent onboarding sessions, batches, completion receipts, and status results | R:- | A:- | S:Session automation policy is immutable: pre-policy sessions remain legacy even if config changes; these structures persist Host progress and bindings but never generate or judge model semantics
workflow.go[CG7L]: F:Runs context-budgeted Bootstrap or Migration onboarding, safe auto continuation, and evidence-based PostgreSQL, MySQL, openGauss, or SQLite source proposals | R:code:internal/dbevidence/types.go,code:internal/dbevidence/collector.go | A:- | S:Auto needs Fresh Bootstrap and zero blockers, else a person approves; channel checked before Apply records approval; a recorded apply result is answered again, repairing an older pending state

===/<repository>/internal/safety/===
files.go[CG7S]: F:Selects release-facing files and forbidden content patterns for the public text scan | R:- | A:- | S:Default scanning excludes backups and spec/private, skips missing or nonregular explicit paths, and adds public text extensions, MCP and engine Go sources, and the embedded page
safety.go[CG7T]: F:Scans public text for centrally defined prohibited claims and renders bounded, source-labeled findings | R:code:internal/machinecontract/lexical.go | A:CheckForbiddenClaims,FormatHits | S:Phrase terms use case-insensitive substring matching, short names use case-sensitive word boundaries, and excerpt truncation is rune-safe to avoid false matches and broken UTF-8

===/<repository>/internal/safetycmd/===
main.go[CG7T]: F:Provides the standalone safety scanner entry point used by release scripts | R:- | A:- | S:-

===/<repository>/internal/cognitionoptimization/===
checkpoint.go[CG8M]: F:Persists the lightweight CAS-bound active progress checkpoint for aligned Code cognition optimization batches | R:code:internal/cognitionoptimization/selector.go,code:internal/mcptools/tools_cognition_optimization.go,code:internal/fs/atomic.go,code:internal/jsonstrict/duplicate.go | A:Create,Load,BindBatch,RebindBatch,Advance,RestartCompleted | S:The checkpoint is disposable draft progress, never formal cognition or recovery proof; replacement batches advance only after the reused Update transaction and Managed Scope governance succeed, while all-no-change batches advance after read-only binding and governance with zero Index/Baseline writes; the last submission digest rejects altered replay; case-colliding keys are refused on load; explicit_object_refs records an opening with object_refs so a redelivered batch keeps its reason
selector.go[CG8M]: F:Measures and deterministically ranks aligned Code Entries for explicitly requested cognition optimization without changing their semantics | R:code:internal/cognitionbudget/policy.go,code:internal/cognitionbudget/report.go,code:internal/index/parser.go,code:internal/mcptools/tools_cognition_optimization.go | A:AlignedEntry,EntryCost,Candidate,SelectOptions,Selection,Select | S:C and byte/3 budget costs only choose review order; explicit object_refs choose membership but not priority, and selection never creates, truncates, retags, or rewrites F/R/A/S; a C>=HighImportanceMinC Entry with S:- ranks after budget pressure and before C order, then an E letter its line count contradicts (EScaleMismatch); both are facts, not verdicts; s_max_tokens is the band floored by the Meta quota passed in SelectOptions.SQuota, which never enters the checkpoint or the plan identity

===/<repository>/third_party/===
openGauss-connector-go-pq.PROVENANCE.md[CG8T]: F:Binds the official connector tag, commit, module sums, license, upstream tree, canonical patch, and complete patched-tree identities | R:code:scripts/check-opengauss-connector.sh,code:third_party/patches/openGauss-connector-go-pq-v1.0.8-aoci.patch,code:third_party/openGauss-connector-go-pq/AOCI-PATCHES.md,code:go.mod | A:Connector patch provenance record | S:go mod verify cannot authenticate files behind the local replacement, so full proof requires exact upstream acquisition, canonical patch replay, and complete-tree comparison; a patch change rewrites the patch and tree identities here and nothing else

===/<repository>/third_party/openGauss-connector-go-pq/===
.gitignore[CG1T]: F:Ignores editor and operating-system metadata within the carried connector source tree | R:- | A:- | S:-
AOCI-PATCHES.md[CG8T]: F:Records AOCI's hardening delta over connector v1.0.8: strict configuration, bounded I/O, cancellation, authentication, stderr logging, bounded DSN parsing | R:code:third_party/openGauss-connector-go-pq/config.go,code:third_party/openGauss-connector-go-pq/connector.go,code:third_party/openGauss-connector-go-pq/conn.go,code:third_party/openGauss-connector-go-pq/conn_go18.go,code:third_party/openGauss-connector-go-pq/logger.go,code:third_party/openGauss-connector-go-pq/ssl.go | A:- | S:The upstream module path and legacy ParseConfig behavior remain intact; LICENSE.md stays authoritative
LICENSE.md[CG5T]: F:Carries the MIT license terms governing the included openGauss connector source | R:code:THIRD-PARTY-NOTICES,code:third_party/openGauss-connector-go-pq.PROVENANCE.md | A:MIT | S:The copyright and permission notice must accompany copies or substantial portions
Makefile[CG3T]: F:Provides connector-local formatting and self-documenting help targets | R:- | A:make fmt,make help | S:-
README.cn.md[CG3S]: F:Documents in Chinese the upstream connector installation, openGauss authentication, multi-host behavior, SSL features, and database/sql example | R:code:third_party/openGauss-connector-go-pq/README.en.md,code:third_party/openGauss-connector-go-pq/AOCI-PATCHES.md | A:- | S:AOCI uses strict parsing, not legacy examples
README.en.md[CG3S]: F:Documents in English the upstream connector installation, openGauss authentication, multi-host behavior, SSL features, and database/sql example | R:code:third_party/openGauss-connector-go-pq/README.cn.md,code:third_party/openGauss-connector-go-pq/AOCI-PATCHES.md | A:- | S:AOCI uses strict parsing, not legacy examples
README.md[CG3S]: F:Presents the inherited connector overview, supported openGauss authentication and transport features, multi-host syntax, and usage example | R:code:third_party/openGauss-connector-go-pq/README.en.md,code:third_party/openGauss-connector-go-pq/AOCI-PATCHES.md | A:- | S:The gitee import is historical upstream text
TESTS.cn.MD[CG3T]: F:Explains in Chinese how to run connector tests and benchmarks against a live openGauss instance or disposable container | R:code:third_party/openGauss-connector-go-pq/TESTS.md | A:go test,go test -bench | S:Live tests need an explicitly prepared database
TESTS.md[CG3T]: F:Explains how to run connector tests and benchmarks against a live openGauss instance or disposable container | R:code:third_party/openGauss-connector-go-pq/TESTS.cn.MD | A:go test,go test -bench | S:Live tests need an explicitly prepared database
array.go[CG5L]: F:Implements database/sql array Scanner and Valuer adapters for typed slices and reflection-backed generic arrays | R:code:third_party/openGauss-connector-go-pq/encode.go | A:Array,ArrayDelimiter,GenericArray | S:Scanning supports only one-dimensional arrays whose lower bound is one; backend array whitespace and NULL spelling remain significant
buf.go[CG8T]: F:Provides mutable big-endian read and write buffers for openGauss wire-protocol fields, strings, message types, and length framing | R:code:third_party/openGauss-connector-go-pq/conn.go | A:- | S:Helpers consume or extend buffers in place and assume callers already proved the protocol frame has sufficient bytes
config.go[CG9L]: F:Parses legacy libpq-compatible or AOCI strict connection strings into Config, network targets, runtime parameters, TLS settings, and fallback policy | R:code:third_party/openGauss-connector-go-pq/connector.go,code:third_party/openGauss-connector-go-pq/ssl.go,code:third_party/openGauss-connector-go-pq/defaults.go,code:third_party/openGauss-connector-go-pq/pgpassfile/pgpass.go,code:third_party/openGauss-connector-go-pq/pgservicefile/pgservicefile.go | A:Config,ParseConfig,ParseConfigStrict,ParseURLToMap,NetworkAddress | S:ParseConfigStrict ignores ambient environment, home, service, passfile, and logger state; non-loopback TCP requires verify-full, only numeric loopback or Unix sockets may disable TLS, and no multi-host fallback is created; a quoted value ending in a backslash is refused, the upstream parser sliced past the end and panicked from every entry point
conn.go[CG9L]: F:Implements the openGauss wire connection, startup and authentication state machines, transactions, prepared statements, queries, and protocol responses | R:code:third_party/openGauss-connector-go-pq/buf.go,code:third_party/openGauss-connector-go-pq/connector.go,code:third_party/openGauss-connector-go-pq/conn_go18.go,code:third_party/openGauss-connector-go-pq/encode.go,code:third_party/openGauss-connector-go-pq/rows.go,code:third_party/openGauss-connector-go-pq/rfcdigest.go | A:ErrNotSupported,ErrInFailedTransaction,QuoteIdentifier,QuoteLiteral | S:SHA256, MD5-SHA256, and SM3 challenges must be length-checked before slicing; server PBKDF2 counts outside 1..1,000,000 are rejected before derivation
conn_go18.go[CG9M]: F:Implements context-aware database/sql operations, transaction options, ping, and deadline-bounded query cancellation for connections and statements | R:code:third_party/openGauss-connector-go-pq/conn.go,code:third_party/openGauss-connector-go-pq/connector.go,code:third_party/openGauss-connector-go-pq/config.go,code:third_party/openGauss-connector-go-pq/ssl.go | A:driver.QueryerContext,driver.ExecerContext,driver.ConnBeginTx,driver.Pinger | S:Cancellation uses a fresh deadline-bound socket and performs any TLS negotiation on that socket rather than upgrading the main transport; connection-level cancellation marks the main connection bad
conn_validate.go[CG5S]: F:Validates target_session_attrs by querying transaction read-only state or recovery state before accepting a connected server | R:code:third_party/openGauss-connector-go-pq/config.go,code:third_party/openGauss-connector-go-pq/connector.go,code:third_party/openGauss-connector-go-pq/rows.go | A:ValidateConnectTargetSessionAttrsReadWrite,ValidateConnectTargetSessionAttrsReadOnly,ValidateConnectTargetSessionAttrsPrimary,ValidateConnectTargetSessionAttrsStandby | S:Validation runs only after authentication; a role mismatch rejects that connection candidate so fallback selection can continue
connector.go[CG9M]: F:Registers openGauss drivers and establishes database/sql connections through configuration, DNS, dialing, TLS, authentication, startup, and fallback selection | R:code:third_party/openGauss-connector-go-pq/config.go,code:third_party/openGauss-connector-go-pq/conn.go,code:third_party/openGauss-connector-go-pq/conn_go18.go,code:third_party/openGauss-connector-go-pq/ssl.go | A:Driver,Connector,NewConnector,NewConnectorConfig,Open,DialOpen | S:Caller context and ConnectTimeout cover DNS, dial, TLS, authentication, and startup; deadlines clear only after complete success, while incomplete attempts close the transport
copy.go[CG5M]: F:Implements buffered asynchronous text COPY FROM imports, response handling, raw CopyData, and schema-qualified statement construction | R:code:third_party/openGauss-connector-go-pq/conn.go,code:third_party/openGauss-connector-go-pq/encode.go | A:CopyIn,CopyInSchema | S:COPY is allowed only inside an explicit transaction and only in text FROM mode; callers must execute with no values or close to flush pending data and surface deferred errors
defaults.go[CG3T]: F:Supplies Unix legacy-parser defaults for socket host discovery, OS user, pgpass and service files, port, target role, and buffer sizes | R:code:third_party/openGauss-connector-go-pq/config.go | A:- | S:ParseConfigStrict bypasses all defaults here
defaults_windows.go[CG3T]: F:Supplies Windows legacy-parser defaults for localhost, normalized OS user, APPDATA pgpass, home service file, port, target role, and buffers | R:code:third_party/openGauss-connector-go-pq/config.go | A:- | S:ParseConfigStrict bypasses all defaults here
doc.go[CG3M]: F:Documents the pq package's connection strings, query parameters, result types, errors, COPY imports, notifications, and optional Kerberos support | R:code:third_party/openGauss-connector-go-pq/config.go,code:third_party/openGauss-connector-go-pq/connector.go | A:package pq | S:Legacy docs do not override ParseConfigStrict
encode.go[CG7L]: F:Encodes and decodes query and COPY values across scalar, temporal, bytea, blob, UUID, character-set, infinity, and openGauss B-mode representations | R:code:third_party/openGauss-connector-go-pq/oid/types.go,code:third_party/openGauss-connector-go-pq/conn.go,code:third_party/openGauss-connector-go-pq/copy.go,code:third_party/openGauss-connector-go-pq/uuid.go | A:EnableInfinityTs,ParseTimestamp,FormatTimestamp,NullTime | S:EnableInfinityTs is process-global, one-shot, and must run before connections; text decoding treats openGauss B-mode value 1 as true and preserves server-offset semantics
error.go[CG8L]: F:Parses backend errors and SQLSTATE, converts protocol panics, wraps connection failures, and redacts passwords in configuration diagnostics | R:code:third_party/openGauss-connector-go-pq/conn.go,code:third_party/openGauss-connector-go-pq/config.go | A:Error,ErrorCode,ErrorClass,PGError | S:Configuration errors must preserve password redaction; bad-connection classification is retained so database/sql cannot reuse a transport after qualifying runtime or network failures
go.mod[CG8T]: F:Declares the carried official connector module identity, Go language level, and pinned crypto, text, test, and error dependencies | R:code:go.mod,code:third_party/openGauss-connector-go-pq.PROVENANCE.md | A:module gitcode.com/opengauss/openGauss-connector-go-pq | S:The root module consumes this exact local source through replace; identity and dependency pins must remain aligned with provenance and replay checks
go.sum[CG5T]: F:Authenticates the exact dependency module contents recorded by the carried connector module | R:code:third_party/openGauss-connector-go-pq/go.mod,code:third_party/openGauss-connector-go-pq.PROVENANCE.md | A:- | S:-
krb.go[CG3T]: F:Defines the optional package-level GSSAPI provider extension used by connector authentication | R:code:third_party/openGauss-connector-go-pq/conn.go | A:RegisterGSSProvider,GSS | S:Register before concurrent connections
logger.go[CG8S]: F:Defines log levels, query-argument formatting and truncation, the connector Logger interface, and the patched stderr printf logger | R:code:third_party/openGauss-connector-go-pq/config.go,code:third_party/openGauss-connector-go-pq/connector.go,code:third_party/patches/openGauss-connector-go-pq-v1.0.8-aoci.patch | A:Logger,LogLevel,NewPrintfLogger | S:The AOCI patch sends printf logging to stderr because MCP stdout is JSON-RPC-only; ParseConfigStrict also rejects ambient logger settings
notice.go[CG3T]: F:Wraps connectors and live driver connections with synchronous server-notice callbacks | R:code:third_party/openGauss-connector-go-pq/config.go,code:third_party/openGauss-connector-go-pq/conn.go | A:NoticeHandler,SetNoticeHandler,ConnectorWithNoticeHandler | S:Handlers are synchronous; non-pq access panics
notify.go[CG5L]: F:Implements LISTEN/NOTIFY handlers, a serialized listener connection, reconnecting subscriptions, and event delivery | R:code:third_party/openGauss-connector-go-pq/config.go,code:third_party/openGauss-connector-go-pq/conn.go,code:third_party/openGauss-connector-go-pq/connector.go | A:Notification,Listener,NewListener,Listener.Listen,Listener.Unlisten,Listener.Close | S:Handlers execute synchronously, and a nil notification after reconnect signals that notifications may have been lost
parallel.go[CG3M]: F:Runs batches of parameterized vector SELECT queries across a caller-sized connection pool and returns results in input order | R:code:third_party/openGauss-connector-go-pq/doc.go | A:ExecuteMultiSearch | S:Trusted inputs only; invalid input calls log.Fatal
rfcdigest.go[CG8M]: F:Implements openGauss SHA-256 and SM3 PBKDF2/HMAC challenge responses plus the legacy MD5-SHA256 derivation | R:code:third_party/openGauss-connector-go-pq/conn.go | A:RFC5802Algorithm,Md5Sha256encode | S:These helpers trust challenge lengths and serverIteration; conn.go must retain its size checks and 1..1,000,000 PBKDF2 bound before calling them
rows.go[CG8M]: F:Decodes result protocol messages, exposes database/sql row metadata, and advances across command and result-set boundaries | R:code:third_party/openGauss-connector-go-pq/conn.go,code:third_party/openGauss-connector-go-pq/encode.go,code:third_party/openGauss-connector-go-pq/oid/types.go | A:database/sql/driver Rows interfaces | S:Close drains messages through ReadyForQuery rather than merely closing the cursor so the underlying connection remains protocol-synchronized
ssl.go[CG9L]: F:Constructs legacy and strict TLS configurations, loads CA and client certificates, manages custom TLS entries, and verifies peers | R:code:third_party/openGauss-connector-go-pq/config.go,code:third_party/openGauss-connector-go-pq/connector.go,code:third_party/openGauss-connector-go-pq/ssl_permissions.go,code:third_party/openGauss-connector-go-pq/ssl_windows.go | A:RegisterTLSConfig,DeregisterTLSConfig | S:Strict mode disables home certificate discovery, enforces TLS 1.2+, and returns certificate errors without stdout output; ParseConfigStrict separately enforces verify-full or loopback-only disable
ssl_permissions.go[CG7T]: F:Enforces ownership-sensitive Unix client-key permissions, allowing at most 0600 normally or 0640 for root-owned keys | R:code:third_party/openGauss-connector-go-pq/ssl.go | A:- | S:Unknown ownership metadata fails closed instead of permitting a key whose confidentiality cannot be established
ssl_windows.go[CG5T]: F:Provides the Windows-specific no-op client private-key mode check matching libpq behavior | R:code:third_party/openGauss-connector-go-pq/ssl.go | A:- | S:Windows key confidentiality depends on Windows ACLs and explicit provisioning because this path performs no Unix-style mode validation
url.go[CG5T]: F:Converts legacy postgres and postgresql URLs into deterministically ordered libpq-style key-value connection strings | R:code:third_party/openGauss-connector-go-pq/config.go | A:ParseURL | S:ParseURL is compatibility parsing only; strict protocol and parameter allowlisting is enforced separately by ParseConfigStrict
user_other.go[CG1T]: F:Returns explicit username-detection failure on JS, Android, Hurd, and z/OS builds | R:code:third_party/openGauss-connector-go-pq/error.go | A:- | S:-
user_posix.go[CG3T]: F:Resolves the current username on supported POSIX targets through os/user with USER as a fallback | R:code:third_party/openGauss-connector-go-pq/error.go | A:- | S:-
user_windows.go[CG3T]: F:Resolves a Windows NameSamCompatible identity and strips its domain component to match libpq username behavior | R:code:third_party/openGauss-connector-go-pq/error.go | A:- | S:-
uuid.go[CG5T]: F:Validates and converts an exact 16-byte binary UUID into canonical hyphenated lowercase text | R:code:third_party/openGauss-connector-go-pq/encode.go | A:- | S:-

===/<repository>/third_party/openGauss-connector-go-pq/certs/===
README[CG3T]: F:Declares the bundled connector certificate material as fixtures for SSL-related tests | R:code:third_party/openGauss-connector-go-pq/certs/root.crt,code:third_party/openGauss-connector-go-pq/ssl.go | A:- | S:Test-only; never seed production trust
bogus_root.crt[CG3T]: F:Provides an intentionally unrelated CA certificate for negative connector TLS trust tests | R:code:third_party/openGauss-connector-go-pq/certs/README,code:third_party/openGauss-connector-go-pq/ssl.go | A:- | S:Expired negative fixture; never a production root
postgresql.crt[CG3T]: F:Provides a pq test-CA-signed client certificate for connector mutual-TLS fixture coverage | R:code:third_party/openGauss-connector-go-pq/certs/README,code:third_party/openGauss-connector-go-pq/ssl.go | A:- | S:Expired fixture; never a production client cert
root.crt[CG3T]: F:Provides the pq fixture certificate authority used to validate bundled client and server test certificates | R:code:third_party/openGauss-connector-go-pq/certs/README,code:third_party/openGauss-connector-go-pq/ssl.go | A:- | S:Expired fixture; never a production trust anchor
server.crt[CG3T]: F:Provides the pq test-CA-signed server certificate used by connector SSL fixtures | R:code:third_party/openGauss-connector-go-pq/certs/README,code:third_party/openGauss-connector-go-pq/ssl.go | A:- | S:Expired fixture; never a production server cert

===/<repository>/third_party/openGauss-connector-go-pq/example/listen/===
doc.go[CG1T]: F:Carries an inherited godoc LISTEN/NOTIFY worker example showing reconnect-aware notifications, periodic checks, and work polling | R:code:third_party/openGauss-connector-go-pq/notify.go | A:- | S:Upstream postgres example is not AOCI acceptance

===/<repository>/third_party/openGauss-connector-go-pq/example/===
main.go[CG1T]: F:Demonstrates a basic database/sql connection through the openGauss driver and scans the server current date | R:code:third_party/openGauss-connector-go-pq/doc.go | A:- | S:Demo password and sslmode=prefer are not for AOCI

===/<repository>/third_party/openGauss-connector-go-pq/example/multi_ip/===
multi_ip.go[CG1T]: F:Demonstrates a legacy multi-host database/sql connection and periodically probes cluster recovery state from an environment DSN | R:code:third_party/openGauss-connector-go-pq/config.go,code:third_party/openGauss-connector-go-pq/doc.go | A:- | S:AOCI strict mode rejects multi-host fallback

===/<repository>/third_party/openGauss-connector-go-pq/hstore/===
hstore.go[CG3S]: F:Implements database/sql Scanner and driver Valuer conversion between hstore wire text and nullable string maps | R:- | A:hstore.Hstore,hstore.Hstore.Scan,hstore.Hstore.Value | S:Value encoding order is nondeterministic

===/<repository>/third_party/openGauss-connector-go-pq/oid/===
conv.go[CG3T]: F:Converts ordered wire type OIDs to comma-separated diagnostic names using the generated type table | R:code:third_party/openGauss-connector-go-pq/oid/types.go,code:third_party/openGauss-connector-go-pq/conn.go | A:oid.ConvertOidsToString | S:-
doc.go[CG5T]: F:Defines the uint32 Oid type shared by connector wire decoding and catalog type mapping | R:code:third_party/openGauss-connector-go-pq/oid/types.go,code:third_party/openGauss-connector-go-pq/rows.go | A:oid.Oid | S:-
gen.go[CG3T]: F:Generates OID constants and type-name mappings from a live server pg_type catalog | R:code:third_party/openGauss-connector-go-pq/oid/doc.go,code:third_party/openGauss-connector-go-pq/oid/types.go | A:go run gen.go | S:Manual generator overwrites types.go from live DB
types.go[CG7L]: F:Carries generated openGauss and PostgreSQL OID constants plus the canonical uppercase type-name map used in decoding and diagnostics | R:code:third_party/openGauss-connector-go-pq/oid/gen.go,code:third_party/openGauss-connector-go-pq/rows.go,code:third_party/openGauss-connector-go-pq/encode.go | A:oid.TypeName,oid.T_* | S:-

===/<repository>/third_party/openGauss-connector-go-pq/pgpassfile/===
pgpass.go[CG3S]: F:Parses PostgreSQL passfiles with escaped delimiters and resolves the first wildcard-capable credential match | R:code:third_party/openGauss-connector-go-pq/config.go | A:ReadPassfile,ParsePassfile,Passfile.FindPassword | S:ParseConfigStrict never reads passfiles

===/<repository>/third_party/openGauss-connector-go-pq/pgservicefile/===
pgservicefile.go[CG3T]: F:Parses PostgreSQL service-file sections and provides named connection-setting lookup | R:code:third_party/openGauss-connector-go-pq/config.go | A:ReadServiceFile,ParseServiceFile,ServiceFile.GetService | S:ParseConfigStrict never reads service files

===/<repository>/third_party/openGauss-connector-go-pq/scram/===
scram.go[CG3M]: F:Implements a generic three-step RFC 5802 SCRAM client with nonce, proof, and server-signature verification | R:- | A:scram.NewClient,scram.Client.Step,scram.Client.Out,scram.Client.Err | S:This package is not used by active openGauss auth

===/<repository>/third_party/patches/===
openGauss-connector-go-pq-v1.0.8-aoci.patch[CG9L]: F:Records the canonical AOCI hardening delta for connector v1.0.8: strict config, bounded I/O and auth, safe TLS cancel, stderr logging, bounded DSN parsing | R:code:third_party/openGauss-connector-go-pq.PROVENANCE.md,code:scripts/check-opengauss-connector.sh,code:third_party/openGauss-connector-go-pq/AOCI-PATCHES.md | A:- | S:It must apply to upstream commit 1b2ca1e407de54157316fcb4a808d8a87e007dac and reproduce patched-tree SHA-256 e6c7393c6b4a56d4bc3126a37f3ba56f64b4ada1fcd06a7f41f679b2e27a5f4c; regenerate it from the pristine module in a temp git repository, never by hand

===/<repository>/scripts/blackbox/===
README.md[CG5M]: F:Documents the five Python suites and two Go runners: commands, counts, upgrade shapes, self-axis, ladder, real-repo and perf tracks, scenario groups L, M, G | R:code:scripts/blackbox/generate_repo_c.py,code:scripts/blackbox/mcp_upgrade.py,code:scripts/blackbox/ladder.json,code:scripts/blackbox/legacy-migration/main.go,code:README.md,code:README.zh-CN.md | A:- | S:Conformance, scenarios and the axis fail when counts published here disagree with a run; lifecycle fails on an unnamed fixture; new suites register in the ladder; database takes --mysql-image
generate_repo_c.py[CG5L]: F:Generates the frozen 453-file layered fixture that lets the scale suite reach the real batch limit with realistic cross-batch relations | R:- | A:python3 scripts/blackbox/generate_repo_c.py | S:Regenerating changes the fixture identity the scale suite asserts; generated names must avoid the built-in sensitive and runtime patterns, and a NUL byte makes Curation silently skip the file
mcp_conformance.py[CG8L]: F:Drives the built binary as a real MCP stdio client over the handshake and sessionless lanes: nine tools, schemas, response shapes, malformed input, locale twins | R:code:scripts/blackbox/README.md,code:README.md,code:README.zh-CN.md,code:internal/mcptools/server.go,code:scripts/blackbox/stdio_deadline.py,code:scripts/blackbox/stdio_capture.py | A:python3 scripts/blackbox/mcp_conformance.py,AOCI_REPO,AOCI_BIN,AOCI_EXPECT_VERSION | S:Read-only on the host repository (multi-chunk Overview); unaligned, the four receipt-bound checks SKIP, counted, exit 0; the 48 KiB host window is measured on a real host; the published count (62) is a suite property, documents must match; the zh-CN lane builds en-US and zh-CN twin fixtures and demands identical machine fields with localized sentences; two checks pin the rules' sub-item labels; the sessionless lane attests a full chain to cognition_level 4; two checks pin the one-batch default and the batch_id refusal under it; two refuse delta_since with check_only or a cursor
mcp_lifecycle.py[CG8L]: F:Runs lifecycles on three fixtures, bring-up lanes (submodules, root lists, credential names, removal, machine docs, zh-CN, Locale switch), and a model track | R:code:scripts/blackbox/README.md,code:scripts/blackbox/generate_repo_c.py,code:scripts/blackbox/mcp_scenarios.py,code:internal/cli/init.go,code:internal/fs/safe_inventory.go,code:internal/managedscope/starter.go | A:python3 scripts/blackbox/mcp_lifecycle.py,--suites,--model,--compare,--mysql-image | S:repo-a/b cover drift and re-alignment, repo-c multi-batch; the database suite needs Docker and --mysql-image, mapping two 8.0-only statements to 5.7, and runs the returned accept command filled; committed fixtures must be named; governance walks pending-policy and held-source probes to aligned; repo-a's package-lock.json is observed, never a candidate; the submodule lane needs protocol.file.allow; the zh-CN leak check skips doctor's host names; the root-list lane pins exclude_root_dirs; the Locale-switch lane expects only AGENTS.md new; author_all drops Code orphans via removals
mcp_scenarios.py[CG8L]: F:Drives hostile fixtures: cursors, rejected writes, crashes, races, Scope Change, activation, dialog, observe review, held sources, batches, next commands, page | R:code:scripts/blackbox/README.md,code:README.md,code:README.zh-CN.md,code:internal/mcptools/tools_next_commands.go,code:internal/mcptools/tools_maintain_budget.go,code:internal/ui/server.go,code:internal/cli/hook.go,code:internal/mcptools/overview_session_v2.go | A:python3 scripts/blackbox/mcp_scenarios.py,--group,--list,AOCI_SCENARIO_WORK,AOCI_SCENARIO_KEEP | S:Writers use own fixtures; a crashed group FAILs, later groups run; Scope Change keeps a changed source's fingerprint; O2 pins S-absent, E mismatch, C; N1 pins terminal_proof against the CLI; N2 drives the review inside the batch; N4: returned commands from another cwd; A6: compacted reload gets capacity_stop; F15 voids a moved observe review; T1: plan id and yes on the PTY; B5 drops the orphan via removals, refuses a live Entry; L: two Sessions, siblings, foreign edit, race, drift; M: delta base, probe, re-anchor, drop, empty, restart; G: child repos container, G2 pre-scan exclude batch
mcp_upgrade.py[CG8L]: F:Proves the upgrade axis both ways: repositories authored by released binaries stay governable by the binary under test, and each release reads one it wrote | R:code:scripts/blackbox/README.md,code:internal/cognitionbudget/policy.go,code:internal/config/scope_budget.go,code:.github/workflows/full-confidence.yml,code:scripts/blackbox/stdio_deadline.py,code:scripts/blackbox/stdio_capture.py,code:internal/index/parser.go,code:internal/fs/safe_inventory.go | A:python3 scripts/blackbox/mcp_upgrade.py,--versions,--recent,--self,--fetch,AOCI_UPGRADE_CACHE | S:Only nobudget reaches LegacyPolicy; spacedroot and cutsegment carry roots truncated up to rc13; inflight applies an unsubmitted batch via MCP; legacydirs pins the released policy's roles: any-depth to rc19, root list from rc20; downgrade expects aligned from the first 0.2.0 candidate (sensitive_name_rules), before it a named scope_change_required refusal with zero formal writes; release_number is a (major, minor, patch, rc) tuple so 0.2.0-rc1 outranks every 0.1.0 release and a final release its candidates; --self labels the candidate from the CHANGELOG top; fetch failures fail the run
stdio_deadline.py[CG5T]: F:Wraps MCP RPC I/O in a wall-clock watchdog that kills and reaps the server on expiry and includes captured stderr in its method-specific TimeoutError | R:code:scripts/blackbox/mcp_conformance.py,code:scripts/blackbox/mcp_scenarios.py,code:scripts/blackbox/mcp_upgrade.py | A:rpc_deadline | S:A clock check around readline cannot interrupt a silent or partial line and select does not cover Windows pipes, so expiry kills the server; an expired session is unusable by design
stdio_capture.py[CG5T]: F:Drains an MCP test server's stderr on a daemon thread, retains a bounded 16 KiB tail, and appends it to early-EOF diagnostics | R:code:scripts/blackbox/mcp_conformance.py,code:scripts/blackbox/mcp_scenarios.py,code:scripts/blackbox/mcp_upgrade.py | A:BoundedStderr,stderr_failure | S:An unread stderr pipe fills the OS buffer and blocks both sides; failure joins briefly and tolerates a session without a collector so bare test construction stays valid
ladder.json[CG7M]: F:Registers every test contract that must be run by name: command, what it proves, cadence, preconditions, where it runs, and the last verification on record | R:code:scripts/blackbox/ladder.py,code:AGENTS.md,code:Makefile | A:test-ladder/v1 | S:A suite absent here is one nobody runs; records come only from ladder.py --mark, a stale record means an unrecorded run; release cadence judges by the newest ## v heading, not an Unreleased top
ladder.py[CG5S]: F:Checks, lists, and marks the run-by-name test ladder: overdue release contracts, aged closure, nightly, and quarterly records, and never-recorded entries | R:code:scripts/blackbox/ladder.json,code:CHANGELOG.md,code:Makefile | A:python3 scripts/blackbox/ladder.py --check,--strict,--list,--mark | S:--check exits 0 unless --strict, so make verify reports without failing; manual contracts are listed and never overdue; quarterly ages out at 92 days; the top release skips an Unreleased section
realrepo.py[CG5M]: F:Clones a real repository, template-authors it to alignment, runs an update wave, an optimization batch and the hook probe, reporting rounds and calls to closing | R:code:scripts/blackbox/mcp_upgrade.py,code:scripts/blackbox/ladder.json | A:python3 scripts/blackbox/realrepo.py <name-or-path> [binary],--wave,--label,--sources,--work,--parallel | S:template Entries prove transport, not quality; wave paths map via the neutral root or stop; --parallel plays every sibling; removals and observe_review ride the batch; stops at the aligned Apply
perf_calls.py[CG5S]: F:Times each governance call a user waits on (scan, cold, warm and steady Maintain, Overview check, verify, check, Guide, status) against a real tree's file count | R:code:scripts/blackbox/realrepo.py,code:scripts/blackbox/mcp_upgrade.py,code:scripts/blackbox/ladder.json | A:python3 scripts/blackbox/perf_calls.py,--binary,--label | S:Not a CI gate: nothing is authored, so it times per-call reload, not rounds; the clone is aged and git's index refreshed, --no-age keeps the racy shape; Maintain lines carry bytes and included
ledger_timings.py[CG5T]: F:Summarizes a repository's own Ledger per governance operation (count, median, p90, max duration_ms) with the index source count, as one JSON line a user pastes | R:code:internal/ledger/ledger.go,code:scripts/blackbox/perf_calls.py,code:docs/troubleshooting.md | A:python3 scripts/blackbox/ledger_timings.py [<repository>],--since,--ops | S:Reads .aoci/ledger.jsonl only, writes nothing; the source count is the largest paths_count of any event, whatever --ops keeps; events carry no binary_version, so it asks for aoci --version too

===/<repository>/.github/===
PULL_REQUEST_TEMPLATE.md[CG3T]: F:Puts the contribution change-evidence checklist in front of reviewers at pull-request time | R:code:CONTRIBUTING.md | A:- | S:-
dependabot.yml[CG3T]: F:Proposes weekly Go module and GitHub Action updates without merging them | R:code:scripts/check-deps.sh | A:- | S:Connector bumps belong to its supply-chain gate

===/<repository>/internal/ui/===
cache.go[CG5S]: F:Caches repository snapshots behind fast fingerprints, bounded rechecks, and per-root rebuild locks; reuses unchanged results with ETags and filters entries | R:code:internal/ui/snapshot.go,code:internal/ui/server.go | A:EntryView | S:Fingerprints miss indexed source edits, so recheck after 2 s or refresh=1; byte-equal rebuilds keep the ETag; one root serializes while different roots build concurrently
discover.go[CG5T]: F:Recognises an aoci mcp command line and extracts the repository root it declares | R:code:internal/ui/discover_linux.go,code:internal/ui/server.go | A:Instance,parseServerCommandLine | S:Only argv naming an aoci binary and running mcp is a server; the base name splits on both path separators; a relative --repo stays as declared; resolving here would bind it to the page's cwd
discover_linux.go[CG5T]: F:Lists the current user's running aoci mcp processes from /proc with each one's repository, executable, and start time | R:code:internal/ui/discover.go | A:discoverRunningServers,discoverRunningServersFrom | S:Ownership must match os.Geteuid before cmdline is read; missing metadata skips it. exe (deleted) reports replacement; relative roots use /proc cwd; deleted or unreadable cwd skips
discover_other.go[CG3T]: F:Reports no running servers where no portable, permission-safe process scan exists | R:code:internal/ui/discover.go | A:- | S:Only named repositories are shown
embed.go[CG3T]: F:Embeds the status page into the binary so it needs no external file or network resource | R:code:internal/ui/page.html | A:- | S:The page must stay offline and self-contained
page.html[CG5L]: F:Renders the status page: a verbatim index pane with an All tab on the left; recommended input, status, and environment in a self-scrolling right column | R:code:internal/ui/server.go | A:- | S:All is the Overview body; raw failures never cache or copy; views bind to root and cache generation; the token lives in session storage, rides each fetch as Bearer, and a 401 shows the access notice
server.go[CG5M]: F:Serves loopback-only read-only routes behind a per-process capability: page, repositories, state with ETag, entries, formal assets verbatim, Overview body | R:code:internal/baseline/fingerprint_cache.go,code:internal/ui/cache.go,code:internal/ui/snapshot.go,code:internal/ui/discover.go,code:internal/ui/registry.go | A:Serve,Options,NormalizeRoots,ErrNotLoopback,ErrNoRepository | S:Host must match the listener; non-loopback binds fail; GET/HEAD only; every route but / needs the Bearer capability in the ready URL; raw Volumes serve validated bytes; fingerprint-cache saves are off
snapshot.go[CG5M]: F:Builds one repository's read-only picture: governance facts, chunk plan, source coverage, per-locale suggestions, the Guide, and host integrations | R:code:internal/volumegovernance/facts.go,code:internal/cli/ui.go,code:internal/mcptools/overview_plan_export.go,code:internal/fs/countlines.go | A:Snapshot,Coverage,Suggestion,GuideFunc | S:Assess is called directly, since check and verify append Ledger events; unreadable sources are counted, never guessed; Overview text stays out of JSON; evidence_required suggests the snapshot alone
detach.go[CG5T]: F:Starts the page as its own session detached from the calling shell and waits for its readiness line before returning its URL and PID | R:code:internal/ui/registry.go,code:internal/cli/ui.go | A:Detach,DetachResult | S:The child is the same binary running the same command, so a detached page behaves exactly like a foreground one; a child that exits or stays silent past the deadline is killed and reported
detach_unix.go[CG3T]: F:Puts the page in its own session on Unix and asks it to stop with SIGTERM so it unregisters itself | R:code:internal/ui/detach.go | A:- | S:-
detach_windows.go[CG3T]: F:Starts the page without a console in its own process group on Windows and ends it with Kill, which has no graceful form | R:code:internal/ui/detach.go | A:- | S:-
registry.go[CG5M]: F:Registers a running page in the user cache directory so a later detach reuses it and stop can end it, proving liveness through the page | R:code:internal/ui/server.go,code:internal/ui/detach.go,code:internal/cli/ui.go,code:internal/fs/lock.go | A:RegistryDir,Register,Registered,Live,HasAccessToken,Stop | S:Liveness is the page answering for the root, never the PID, which may be reused; Register writes 0600; the probe sends the fragment token and follows no redirect; Stop removes only its captured PID

===/<repository>/internal/testkit/===
testkit.go[CG5M]: F:Provides shared test helpers for repository fixtures: git init and commits, file writing, tree copying, locale pinning, stdout capture, and a fixture builder | R:code:textassets/catalog.go,code:internal/cli/root.go | A:Git,Commit,WriteFile,CopyTree,PinLocale,NewFixture | S:Imports only the standard library and textassets so cli and mcptools tests share it without a cycle; PinLocale restores the process locale via t.Cleanup, so pinned tests never run in parallel

===/<repository>/engine/===
cognition.go[CG8S]: F:Projects the loaded cognition set into public assets and Entries: layout, exact asset digests, object Volumes, and each Entry's identity, tag, and F/R/A/S | R:code:internal/cognition/loader.go,code:internal/cognition/types.go,code:internal/index/types.go | A:Cognition,Asset,Entry,Finding,LayoutVolumesV1,LayoutLegacy | S:Pure projection of the loader's objects, never a second parser; the Meta Volume is Cognition.Meta, not an object Volume; Legacy objects come from the Root asset with Domain code and Kind file, their ObjectRef being the repository-relative path
doc.go[CG8T]: F:Declares the engine package: the embeddable kernel offering the CLI and MCP core as a third entry point without a second implementation | R:code:spec/public/aoci-engine-library-v1.txt | A:package engine | S:The package calls no model, holds no credential, reaches no remote; Open binds the process-wide text catalog, so one process serves one repository Locale at a time
errors.go[CG7T]: F:Defines ErrLayoutUnsupported, the answer of the Volumes-only operations on a Legacy layout | R:- | A:ErrLayoutUnsupported | S:Cognition, Identity, and the nine tools still answer on Legacy; only Overview and Governance refuse
governance.go[CG8T]: F:Projects the shared governance fact set into its decision, findings, drift counts, and flags, carrying the complete facts as JSON | R:code:internal/volumegovernance/facts.go | A:Repository.Governance,Governance,GovernanceFinding,DriftCounts | S:Assess is called directly so no Verify History or Ledger event is written; Facts is the verify --json governance object byte for byte; Volumes only
identity.go[CG8T]: F:Reports what a published cognition is: each formal asset digest, the composite and complete-scope identities, the Baseline digest, Entry count, engine version | R:code:internal/cognition/identity.go,code:internal/config/paths.go | A:Repository.Identity,Identity | S:Identities are the loader's own values, never recomputed here; the Baseline digest is the raw file digest and is empty when no Baseline exists
mcp.go[CG8S]: F:Hosts the nine MCP tools from the shared server constructor over stdio, a caller transport, or an in-memory session whose Call returns the tool's own result | R:code:internal/mcptools/server.go | A:Repository.NewMCPServer,Repository.ServeStdio,Repository.Connect,Session.Call,Session.Tools,ToolResult | S:A tool refusal is a result with IsError, not a Go error; the session keeps the server's per-process state (refresh generation, reused deliveries), so one session per repository outlives its calls; ServeStdio records the host binary as the service identity
overview.go[CG8T]: F:Returns the complete delivered Overview body of a scope with the digest, byte count, scope identity, and chunk plan the delivery path computes | R:code:internal/mcptools/overview_plan_export.go,code:internal/mcptools/overview_delivery_v1.go | A:Repository.Overview,Overview | S:FramedOverviewBody frames and hashes exactly as a full delivery does, so SHA256 equals a Host's body_sha256; the unframed OverviewBody differs by the markers; Volumes only
repository.go[CG8T]: F:Opens a repository the way the CLI does without --repo and holds its root and read-only effective configuration for every read | R:code:internal/config/paths.go,code:internal/config/config.go,code:textassets/catalog.go | A:Open,Repository.Root,Repository.Locale,Repository.IndexPath | S:LoadReadOnly keeps Open from materializing the Locale upgrade; one shared loader call serves every read, so a damaged layout fails closed exactly as it does for the tools
version.go[CG8T]: F:Reports the engine version from the build-injected identity, else the module version the Go toolchain recorded for an importer, else dev | R:code:internal/buildinfo/buildinfo.go,code:internal/machinecontract/capabilities.go | A:Version,Commit | S:A replaced module (v0.0.0 or (devel)) reads as dev, so an importer pinned through a local replace never reports a release it is not

===/<repository>/examples/engine-embed/===
go.mod[CG5T]: F:Declares the embed example module, pinned to this checkout, its SQLite driver, and its reviewed openGauss connector through two replace directives | R:code:go.mod,code:third_party/openGauss-connector-go-pq/go.mod | A:- | S:The connector replace is mandatory for every importer until the patched connector is published as a module
go.sum[CG3S]: F:Authenticates the dependency content the embed example resolves through the engine module graph, the SQLite driver included | R:code:examples/engine-embed/go.mod | A:- | S:-
main.go[CG5T]: F:Shows a program embedding the kernel: prints a repository's layout, Entry count, identity, and alignment, or serves the nine tools over stdio | R:code:engine/doc.go | A:go build ./...,--repo,--mcp | S:Under --mcp stdout is JSON-RPC, so every message goes to stderr; the replace directives in go.mod bind it to this checkout and the connector tree

===/<repository>/internal/buildinfo/===
buildinfo.go[CG8T]: F:Holds the build-injected version, commit, and build date that the CLI and the engine library report as one identity | R:code:Makefile,code:.goreleaser.yml,code:scripts/release/clean-room-smoke.sh | A:Version,Commit,BuildDate | S:These are the only ldflags -X targets; moving this package or its names must change the three injection sites and the manifest test that pins them, or every binary reports dev

===/<repository>/scripts/blackbox/legacy-migration/===
main.go[CG7L]: F:Drills the only exit from read-only Legacy: a released binary builds an aligned Legacy repository per Locale, the binary under test migrates each to Volumes v1 | R:code:internal/onboarding/workflow.go,code:internal/migrationapply/mapping.go,code:internal/mcptools/tools_human_approval.go,code:internal/cli/onboard_next_commands.go,code:scripts/blackbox/mcp_upgrade.py,code:Makefile | A:make legacy-migration,go run ./scripts/blackbox/legacy-migration,--binary,--legacy-binary,--keep,--locale | S:Past the Guide's onboard command it runs only next_commands, in sh at the root; rc22 Maintain omits the self-Entry its Verify demands, so the CLI writes it; apply must carry terminal_proof