feat(docs): verify pinned shared sources and local manifests

.github/workflows/documentation-tool.yml

@@ -0,0 +1,20 @@
+name: Documentation tool qualification
+on:
+  pull_request:
+    paths: ['scripts/repository_docs.py', 'tests/test_repository_docs.py', '.github/workflows/documentation-tool.yml']
+  push:
+    branches: [main]
+    paths: ['scripts/repository_docs.py', 'tests/test_repository_docs.py', '.github/workflows/documentation-tool.yml']
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+      - run: python3 -m pip install 'coverage>=7.6,<8'
+      - run: python3 -m coverage run --branch --source=scripts -m unittest discover -s tests -p test_repository_docs.py -v
+      - run: python3 -m coverage report --show-missing --fail-under=100

.github/workflows/repository-docs-shadow.yml

@@ -0,0 +1,22 @@
+name: Repository documentation shadow
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  parity:
+    continue-on-error: true
+    runs-on: ubuntu-24.04
+    timeout-minutes: 3
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+      - run: python3 -m pip install 'coverage>=7.6,<8'
+      - run: python3 -m coverage run --branch --include=scripts/repository_docs.py -m unittest discover -s tests -p test_repository_docs.py -v
+      - run: python3 -m coverage report --show-missing --fail-under=100
+      - run: python3 scripts/repository_docs.py

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+.coverage

AGENTS.md

@@ -0,0 +1,17 @@
+# Shared CI repository
+
+Keep consumer builds and releases independent. Preserve existing required checks
+and native merge queues. New fleet checks qualify in shadow before enforcement.
+Use full commit pins and separate consumer upgrade/rollback PRs (JOV-6555).
+Do not change credentials, branch protections, deployments or live controllers.
+
+For documentation tooling, read docs/DOCUMENTATION-PARITY.md and run its exact
+coverage commands. Local consumer README/AGENTS and manifests remain repo-owned.
+The older policy/POLICY.md and README distribution claims predate JOV-6555;
+this task does not certify their planned workflows as implemented.
+
+## Repository documentation
+
+See [source parity](docs/DOCUMENTATION.md) and the generated
+[source map](docs/REPOSITORY_SOURCES.md). Shared policy is pinned; local
+manifest, build, test and release instructions remain owned by this repository.

README.md

@@ -1,22 +1,36 @@
 # JovieInc/ci
 
-Centralized, opinionated CI for all Jovie repositories — one set of reusable GitHub Actions workflows, shared composite actions, and a single strict policy for gates, distribution, and agent mediation.
+Shared CI source for independently released company repositories. Consumers own
+their build commands, tests, required checks, deployment and rollback.
 
-**Principle:** update one workflow here → every repo benefits. Consumer repos keep only ~15-line caller stubs pinned to `@v1`.
+## Implemented on this branch
 
-## Layout
-- `.github/workflows/` — reusable workflows (`on: workflow_call`)
-- `actions/` — shared composite actions
-- `policy/` — POLICY.md (branch rules, gate tiers, agent PR contract), risk-rules.yml, gitleaks.toml
+- `.github/workflows/dependabot-auto-merge.yml`: callable dependency mediation.
+- `actions/setup-node-pnpm`, `actions/setup-ios-build`, `actions/asc-api-key`:
+  composite actions; inspect their own inputs and prerequisites before use.
+- `scripts/repository_docs.py`: offline manifest projection and pinned shared-file
+  parity. See [documentation parity](docs/DOCUMENTATION-PARITY.md) for tests,
+  scope, update procedure, shadow qualification and rollback.
+- `policy/`: source policy, risk rules and secret-scanner configuration.
 
-## Gate tiers
-1. **Pre-PR (local/agent harness)** — typecheck, lint, affected unit tests. Never burn a runner on what the agent can run itself.
-2. **PR (required)** — `rw-gate-fast` + risk classifier only. Deep gates run only when `rw-gate-risk` says risk ≥ standard.
-3. **Merge queue** (`merge_group`) — build + E2E smoke on the queued batch.
-4. **Post-merge** — deploy + canary + error gate, **fix-forward**: failures auto-file P1 + capped autofix; never retro-block the queue.
-5. **Scheduled** — nightly full suite, security, CodeQL.
+This list describes source, not consumer adoption or effective branch controls.
+Previously described `rw-gate-fast`, `rw-gate-risk`, `rw-gate-deep` and
+`rw-merge-queue` workflows are not present on this revision. JOV-2970/JOV-2975
+track shared CI; existing PRs retain ownership of their separate implementation.
 
-## Versioning
-Consumers pin `@v1` (moving major tag). Breaking changes bump major. Changes here run actionlint + smoke against consumer repos before tagging.
+## Distribution
 
-Tracked in Linear: JOV-2970 (epic), JOV-2975 (Phase 1).
+JOV-6555 supersedes the old moving-`@v1` proposal: consumers use reviewed full
+commit SHAs and separate upgrade PRs. A central commit does not automatically
+change consumers. Qualify a candidate with relevant tests and a consumer canary,
+then roll out independently; retain known-good pins for rollback.
+
+Existing consumer checks and release guarantees remain in force. New fleet
+requirements qualify in shadow before enforcement. No sibling repo's healthy
+build depends on every other consumer being green.
+
+## Repository documentation
+
+See [source parity](docs/DOCUMENTATION.md) and the generated
+[source map](docs/REPOSITORY_SOURCES.md). Shared policy is pinned; local
+manifest, build, test and release instructions remain owned by this repository.

docs/DOCUMENTATION-PARITY.md

@@ -0,0 +1,64 @@
+# Repository documentation parity
+
+Decision (2026-09-24): COMPOSE Git-owned Markdown, existing repository freshness
+checks, SHA-pinned file projections and repo-local manifests. Extend JOV-6555's
+independent distribution boundary without replacing its shared-workflow work.
+
+The MIT-licensed `scripts/repository_docs.py` uses only Python 3.9+ stdlib. It
+fetches nothing, executes no imports, needs no credentials and changes no service.
+Consumers vendor the exact script and license using a full revision and SHA-256.
+`repository-docs.json` names local entry points, manifest/workflow sources, output
+and shared imports. Package facts are rendered directly; other sources have
+fingerprints. A fingerprint is a review trigger, not proof of prose accuracy.
+
+## Update, verify and roll back
+
+1. Review the upstream commit and preserve the known-good consumer commit.
+2. Update the selected import's full Git revision and SHA-256 in the registry.
+3. From the reviewed tooling checkout run:
+
+   ```sh
+   python3 scripts/repository_docs.py --root /path/to/consumer --write \
+     --upstream JovieInc/ci=/path/to/ci \
+     --upstream JovieInc/Jovie=/path/to/Jovie
+   ```
+
+4. Review the diff and run the vendored `python3 scripts/repository_docs.py`.
+5. Open an independently checked consumer PR. Revert that consumer commit to
+   roll back; sibling repos retain their pins and continue shipping.
+
+All source hashes are validated before writes. Only listed imports and the
+projection are written. README and AGENTS stay locally owned. Without upstream
+arguments the check proves offline parity to the declared pin, not freshness of
+the pin or remote availability. Update-time Git readback proves source bytes.
+After a local manifest/workflow edit, review its documentation and regenerate
+with `python3 scripts/repository_docs.py --write` in the consumer.
+
+## Qualification
+
+Run `python3 -m coverage run --branch --source=scripts -m unittest discover -s tests -p test_repository_docs.py -v`
+and `python3 -m coverage report --show-missing --fail-under=100`.
+Tests cover source drift, absent entry points, path escape, bad pins, independent
+upgrades and rollback. Consumer CI uses `continue-on-error` during shadow
+qualification. Do not require it in branch protection. Promotion requires actual
+ship samples, correctness/pass rate, p95 duration, throughput/cost and failure
+isolation, an accountable owner and a tested rollback. No numeric promotion
+threshold is asserted here. Existing gates remain enforced.
+
+## Adopt-first receipt
+
+- Preserve Jovie's existing `scripts/lib/doc-freshness.mjs` for local links and
+  computed markers, and JOV-6555 for pinned CI releases and consumer canaries.
+- GitHub [reusable workflows and composite actions](https://docs.github.com/en/actions/concepts/workflows-and-actions/reusing-workflow-configurations)
+  are the maintained CI substrate; they do not render offline repo docs.
+- [Copier template updates](https://copier.readthedocs.io/en/stable/generating/)
+  were evaluated but not adopted: whole-project templating is unnecessary for
+  a few shared files in independently maintained repositories.
+- Custom code is limited to offline projection and exact-byte copy verification.
+  No new service catalog, platform, scheduler, updater bot or paid service.
+  Only reviewed non-secret policy and tool files cross repository boundaries.
+  Git and ordinary files preserve portability and independent rollback.
+
+Ship now: shadow checks in separate consumer PRs. Re-evaluate after two update
+cycles with repeated drift or substantial manual work. Then extend the existing
+updater under JOV-6555 rather than creating a second bot.

docs/DOCUMENTATION.md

@@ -0,0 +1,42 @@
+# Documentation ownership and parity
+
+The repository owns README/AGENTS, local manifests, runtime declarations and
+release workflows. [The portable company contract](company/REPOSITORY_SOURCE_CONTRACT.md)
+is shared source policy; it does not change the local stack or release gates.
+
+`repository-docs.json` selects source-owned entry points, local manifests and
+workflows, generated output and immutable shared imports. The generated
+[repository source map](REPOSITORY_SOURCES.md) renders package facts directly and
+fingerprints other sources. Review related prose whenever a fingerprint changes.
+This is source evidence, not proof of deployment, current credentials or runtime.
+
+From the repository root (Python 3.9+; no network or secrets):
+
+```sh
+python3 scripts/repository_docs.py
+python3 scripts/repository_docs.py --write
+```
+
+Use `--write` after reviewing local source changes. Shared-file edits belong in
+the canonical repository named by each import, followed by a reviewed full Git
+revision and SHA-256 update. From the reviewed JovieInc/ci tooling checkout:
+
+```sh
+python3 scripts/repository_docs.py --root /path/to/this-repo --write \
+  --upstream JovieInc/ci=/path/to/ci \
+  --upstream JovieInc/Jovie=/path/to/Jovie
+```
+
+The default check verifies local copies against declared hashes offline. It does
+not claim that upstream pins are latest. Update-time Git readback verifies the
+exact upstream bytes. Only listed imports and generated output are written;
+README/AGENTS remain local. Review changes in a separate PR per repository.
+Revert the consumer commit to restore its previous pin; siblings remain usable.
+
+CI runs the same deterministic parity tests and coverage as shared tooling, then
+checks the local projection in shadow. No new required gate or branch protection
+is added. Existing required checks remain enforced. JOV-6607 tracks qualification;
+JOV-6555 owns shared-CI release distribution and updater integration. Promote only
+with representative ship samples, correctness/pass rate, p95, throughput/cost,
+failure isolation, an accountable owner and tested rollback. No approved numeric
+promotion threshold is implied. No scheduler, new bot or paid service is added.

docs/REPOSITORY_SOURCES.md

@@ -0,0 +1,26 @@
+# Repository source map
+
+Generated by repository_docs.py; edit the source files and regenerate.
+This is source evidence, not deployment or operational certification.
+
+Repository: `JovieInc/ci`
+
+## Source-owned entry points
+
+- `README.md`
+- `AGENTS.md`
+- `docs/DOCUMENTATION.md`
+
+## Manifest and workflow fingerprints
+
+A changed fingerprint requires review of its related documentation; it does not prove prose is accurate.
+
+- `.github/workflows/dependabot-auto-merge.yml` — Local manifest or workflow; review related instructions when changed (SHA-256 `432fca1d9fe7beb3dc78598971c321d5a7983d93d9fad2eb2f8ab6b5758139eb`)
+- `.github/workflows/documentation-tool.yml` — Local manifest or workflow; review related instructions when changed (SHA-256 `e4212c1929eddfabcd48a6d0dfdebd00a7359640f77d447c764906d471f8350b`)
+- `.github/workflows/repository-docs-shadow.yml` — Nonblocking parity qualification (SHA-256 `2b9ccbfcdef4df6d31e17ec1dbad5fffe82c01263af0c08b8b0481b31e7af48e`)
+
+## Pinned shared sources
+
+Updates are independent reviewable consumer changes. Local instructions remain source-owned.
+
+- `docs/company/REPOSITORY_SOURCE_CONTRACT.md` ← `JovieInc/Jovie@b193bc6a360b20df6933d45b4abefe0736c09493:docs/company/REPOSITORY_SOURCE_CONTRACT.md` (SHA-256 `f6bb8cdfdc317ed4ac3b99f8d2fc18a9647124c4fb807b1eef274892447b184f`)

docs/company/REPOSITORY_SOURCE_CONTRACT.md

@@ -0,0 +1,38 @@
+# Company repository source contract
+
+Owner: company engineering / Tim White. Updated: 2026-09-24.
+Scope: shared source/documentation boundaries, not product-specific configuration.
+
+Company canon is owned in Jovie's `canon/OPERATING_SYSTEM.md`,
+`canon/ENGINEERING.md` and `canon/FLEET.md`. This portable projection summarizes
+those boundaries for other repositories. Update this source first and distribute
+reviewed immutable revisions; never overwrite a consumer's local instructions.
+
+- Each repository owns its README, AGENTS, manifests, workflows, dependencies,
+  tests, build, release, rollback and runtime declarations. Source code and real
+  manifests outrank stale prose. A common standard does not imply one stack.
+- Company repositories ship independently under their current owners and gates.
+  A cross-repo hold requires fresh evidence of a specific shared bottleneck,
+  named owner, expiry and release condition. Concurrent CI alone is not evidence.
+- Shared policy/tool copies record canonical repository, path, full Git revision
+  and content hash. Updates and rollback are independent consumer PRs. A pinned
+  copy is reproducible; it is not automatically the newest revision.
+- Generated documentation is derived from local source. Review related prose
+  when source changes. Hash parity cannot establish semantic correctness.
+- New or changed fleet delivery gates qualify in nonblocking shadow first.
+  Existing required checks remain enforced. Promotion needs representative actual
+  ships, correctness, pass rate, p95 duration, throughput/cost, failure isolation,
+  accountable ownership and tested rollback. Do not invent approved thresholds.
+- Preserve meaningful tests and current coverage for executable changes. Clearly
+  distinguish source, local tests, hosted CI, review, native queue/merge,
+  deployment, observed runtime, persistence and customer outcome.
+- Preserve active writers and the existing deployment/commissioning controller.
+  Documentation does not grant credentials, host changes, service activation,
+  external messaging, release-control changes or production mutation authority.
+- Keep secrets, sessions, private memory, operational logs and host state out of
+  shared projections. Copy only reviewed non-secret source appropriate to the
+  destination's visibility. Retired instructions are history, never activation.
+
+Distribution mechanism: JovieInc/ci `docs/DOCUMENTATION-PARITY.md`, tracked by
+JOV-6607 alongside JOV-6555. Existing repo-local freshness checks remain in place.
+This source contract does not certify that a consumer implements any mechanism.