@event4u/agent-config 3.0.0 → 3.1.0

package/docs/decisions/ADR-015-discovery-manifest-contract.md

@@ -0,0 +1,146 @@
+---
+adr: 015
+status: accepted
+date: 2026-05-21
+decision: discovery-manifest-contract
+supersedes: —
+superseded_by: —
+phase: v2.x · monorepo-phase-2-virtual-packs-discovery Phase 1
+type: prospective
+---
+
+# ADR-015 — Discovery Manifest Contract
+
+## Status
+
+**Accepted** · 2026-05-21 · in-session AI Council pass. Folds the Phase-2
+intake invariant (`agents/tmp/refactor-package.txt`, last paragraph) and
+the additive-vs-rewrite call into the schema. Phase-1 prerequisite for
+[`monorepo-phase-2-virtual-packs-discovery`](../../agents/roadmaps/monorepo-phase-2-virtual-packs-discovery.md).
+
+## Context
+
+[ADR-013](ADR-013-discovery-frontmatter-contract.md) locked the five
+per-artefact frontmatter keys. The release pipeline now needs a single
+JSON contract — `dist/discovery/discovery-manifest.json` — that the
+TypeScript installer (Phase 3), the browser wizard (Phase 6), the docs
+site, and any third-party consumer read instead of walking the source
+tree. The invariant from the founder intake:
+
+> Beim Erstellen eines Releases müssen alle Skills, etc. nach Workspace
+> und Pack untersucht werden, so dass das für den Installer gespeichert
+> wird und zur Verfügung steht. Es soll keine manuelle Package &
+> Workspace Liste gepflegt werden.
+
+**No manual list. Ever.** The pack and workspace shape grows by stamping
+frontmatter, not by editing a list.
+
+A v1 manifest schema already lives at
+[`docs/contracts/discovery-manifest.schema.json`](../contracts/discovery-manifest.schema.json)
+(carried over from the archived R3 discovery roadmap). The Phase-2
+roadmap §"Manifest shape" sketched an *ideal* shape that differs from
+the on-disk schema in several places (per-artefact `checksum`,
+optional `requires`, a `stats` block). The decision is whether to
+rewrite the schema or extend it additively.
+
+## Decision
+
+**Extend the v1 schema additively.** Three changes, no removals, no
+field renames, version stays `1`:
+
+1. **`artefact.checksum`** — `sha256:<hex>`, REQUIRED. Computed over the
+   on-disk file bytes after frontmatter normalization (sorted keys,
+   trailing newline). Drift detector for the Phase-3 installer.
+2. **`artefact.requires`** — `array<pack_id>`, OPTIONAL. Pack-level
+   dependency edges resolved by the installer; empty/absent means the
+   artefact has no extra pack requirements beyond its own `packs[]`.
+3. **`stats`** — REQUIRED top-level object. `total_artefacts`,
+   `by_category`, `by_lifecycle`, `by_trust_level`. Cheap sanity surface
+   for `task discovery-stats` + downstream dashboards.
+
+The Phase-2 roadmap's example also mentioned `id`, `owner`, and
+`install.managed`. **Not adopted.** The path is the canonical artefact
+identity (matches ADR-013), ownership is already encoded in
+`workspaces[]` + `packs[]`, and `install.managed` adds a third
+install-axis without a current consumer. Re-evaluate in Phase 5.
+
+### Source-of-truth tree
+
+The generator walks `.agent-src.uncompressed/`, **not** `.agent-src/`.
+The Phase-2 roadmap text §Phase 2 says "the compressed canonical tree"
+— that is a documentation slip. `augment-source-of-truth` rule states
+that uncompressed is canonical; the compressed tree is a build output
+and may be regenerated. Manifest pipelines that read build outputs are
+fragile to bootstrap order.
+
+### No git in the manifest
+
+The roadmap example included `source_commit`. **Not adopted.** The
+existing `scanner_version` (first 12 hex of `sha256(build_discovery_manifest.py)`)
+already pins generator identity. Embedding `git rev-parse HEAD` breaks
+hermetic determinism tests in environments without a git checkout
+(CI shallow clones, vendor tarballs). A consumer that needs the commit
+can pin from the surrounding release artefact (changelog, tag).
+
+## Consequences
+
+### Positive
+
+- Existing consumers (the Phase-1 linter, the round-trip test, the
+  `lint_discovery_manifest.py` validator) keep working — top-level
+  `version` stays `1`, all v1 fields stay required.
+- Per-artefact `checksum` makes the Phase-3 installer drift-detection
+  trivial — one hash compare per file.
+- `requires` is opt-in: artefacts that don't need cross-pack deps cost
+  zero extra bytes.
+- Stats are computed from the artefact list — no second walk of the
+  tree, no risk of stats/list desync.
+
+### Negative
+
+- Every artefact entry grows by ~80 bytes (the checksum). For ~420
+  artefacts, the manifest grows ~33 KB. Acceptable.
+- The first build after this ADR rewrites every artefact entry; the
+  diff is large. Reviewed once and committed.
+
+### Neutral
+
+- `version` stays `1`. A future breaking change (rename `packs` to
+  `pack_ids`, drop `unassigned`, etc.) bumps to `2`. This ADR sets the
+  precedent that **additive** changes do not bump.
+
+## Determinism contract
+
+Two builds of the same source tree MUST produce byte-identical JSON
+when `generated_at` is normalized. Specifically:
+
+- All arrays sorted (`artefacts` by `path`, `workspaces`/`packs` in
+  vocabulary order, `requires`/`workspaces[]`/`packs[]` per-entry sorted).
+- JSON serialized with `sort_keys=True`, `indent=2`, trailing newline.
+- The global `checksum` covers the manifest minus `generated_at` and
+  itself (zeroed during hash input).
+- Per-artefact `checksum` covers the file content with frontmatter
+  normalized (sorted keys, trailing newline, no trailing whitespace).
+
+## Failure modes guarded against
+
+- **Manual drift** — no pack list to hand-edit; new packs/workspaces
+  enter via frontmatter stamps on artefacts.
+- **Stale manifest in release** — Phase 3 ships `task validate-discovery-manifest`
+  which re-builds to a tempdir and `diff`s against the committed file.
+- **Checksum collision with content edits** — per-artefact `checksum`
+  surfaces any file mutation; the installer can refuse to overwrite a
+  user-modified artefact (Phase 3).
+- **`version: 1` reused for breaking changes** — this ADR explicitly
+  scopes `version: 1` to additive evolutions; breaking → bump + new ADR.
+
+## References
+
+- [ADR-013](ADR-013-discovery-frontmatter-contract.md) — frontmatter
+  contract (the input side of this manifest).
+- [`docs/contracts/discovery-manifest.schema.json`](../contracts/discovery-manifest.schema.json)
+  — the locked schema.
+- [`docs/contracts/discovery-manifest.md`](../contracts/discovery-manifest.md)
+  — worked examples + consumer guide.
+- [`agents/roadmaps/monorepo-phase-2-virtual-packs-discovery.md`](../../agents/roadmaps/monorepo-phase-2-virtual-packs-discovery.md)
+  — the implementing roadmap.

package/docs/decisions/ADR-016-installer-architecture.md

@@ -0,0 +1,189 @@
+---
+adr: 016
+status: accepted
+date: 2026-05-21
+decision: installer-architecture
+supersedes: —
+superseded_by: —
+phase: v2.x · monorepo-phase-3-typescript-installer
+type: prospective
+---
+
+# ADR-016 — TypeScript Installer Architecture
+
+## Status
+
+**Accepted** · 2026-05-21 · external AI Council pass (`claude-sonnet-4-5`
++ `gpt-4o`, 2 rounds, `design` lens, actual cost $0.13) on
+[`agents/roadmaps/monorepo-phase-3-typescript-installer.md`](../../agents/roadmaps/monorepo-phase-3-typescript-installer.md).
+Council issued **conditional approval** with five blockers; this ADR
+folds each blocker into the design before Phase 3.1 starts.
+
+Session: [`agents/runtime/council/responses/phase-3-installer-design.json`](../../agents/runtime/council/responses/phase-3-installer-design.json) <!-- council-ref-allowed: ADR decision-trace -->
+
+## Context
+
+Phase 3 of the monorepo plan replaces the shell-based `install.sh` with
+a TypeScript Core Installer that drives interactive TUI, non-interactive
+CI flags, and a structured **agent-mode** JSON protocol over stdio. It
+consumes [`dist/discovery/discovery-manifest.json`](../../dist/discovery/discovery-manifest.json)
+(locked by [ADR-015](ADR-015-discovery-manifest-contract.md)) and
+writes managed files into the consumer's `.augment/` and `.agent-src/`,
+tracked in `agents/agent-config.lock.yml`.
+
+The council raised five architectural risks that, left unaddressed,
+would force post-merge rework in Phase 5 (trust) and Phase 6 (browser
+wizard). This ADR locks the resolution of each.
+
+## Decision
+
+### 1. Lockfile schema v1 records provenance, not just paths
+
+```yaml
+schema_version: 1
+agent_config_version: 2.0.0
+manifest_sha256: <hex>           # sha256 of the consumed discovery-manifest.json
+generated_at: 2026-05-21T12:00:00Z
+workspaces: [engineering, governance]
+packs:
+  - id: pack.laravel
+    version: 2.0.0
+    auto_selected: false
+    required_by: []
+files:
+  - path: .augment/skills/laravel/SKILL.md
+    pack: pack.laravel
+    pack_version: 2.0.0
+    sha256: <hex>
+    manifest_sha256: <hex>       # which manifest sourced this file
+    managed: true
+```
+
+`manifest_sha256` is per-file (not just per-lockfile) so Phase 5 trust
+gates can answer "which manifest claimed this artefact was safe?"
+without needing a lockfile rewrite.
+
+### 2. Overrides live in a separate file the installer never writes
+
+```yaml
+# agents/agent-config.overrides.yml — user-managed, installer reads but never writes
+schema_version: 1
+overrides:
+  - path: agents/overrides/skills/laravel/SKILL.md
+    shadows: .augment/skills/laravel/SKILL.md
+    reason: "Custom prompt for our team's Laravel style"
+```
+
+The lockfile (`.lock.yml`) is **append-only by the installer**;
+overrides (`.overrides.yml`) are **read-only to the installer**.
+`validate` cross-references the two. This resolves the source-of-truth
+ambiguity the council flagged on `managed: false`.
+
+### 3. Merge decision table replaces "three-way merge" handwaving
+
+| Disk    | Lock | Upstream | Override? | Action                               |
+|---------|------|----------|-----------|--------------------------------------|
+| A       | A    | A        | —         | no-op                                |
+| A       | A    | B        | no        | write B, update lock                 |
+| A       | A    | B        | yes       | write B to `.augment/`, leave override |
+| A       | A    | absent   | —         | offer prune                          |
+| X (drift) | A  | A        | —         | warn, suggest `validate --fix`       |
+| X (drift) | A  | B        | no        | error: manual merge required         |
+| X (drift) | A  | B        | yes       | error: override may be stale         |
+| absent  | A    | B        | —         | write B (recreate)                   |
+
+Encoded in `src/sync/merge-strategy.ts`; covered by
+`tests/sync-algorithm.test.ts` with one case per row.
+
+### 4. Agent mode: strict question-ID validation (stateless)
+
+Of the three options the council surfaced (session token, nonce,
+strict sequencing) we adopt **strict sequencing**: the CLI tracks the
+current question id in the manifest of expected answers; any
+`--answer` that does not match the current question id returns:
+
+```json
+{ "status": "error", "protocol_version": 1, "reason": "out_of_order",
+  "expected_question_id": "q1.workspaces", "received": "q2.packs" }
+```
+
+Stateless (no session file), enforceable, and easy to test. Nonces
+can be added later under the same protocol version if the threat model
+hardens.
+
+### 5. Atomic writes via staging directory
+
+Every command that writes to `.augment/`, `.agent-src/`, or the
+lockfile stages changes under `.augment/.agent-config-staging/<uuid>/`,
+verifies sha256s against intended manifest entries, then performs:
+
+1. Atomic rename: `staging/.augment/foo.md` → `.augment/foo.md`
+   (per-file `fs.renameSync` is atomic on POSIX and Windows ≥ 10).
+2. Lockfile written last (so a mid-flight crash leaves the lockfile
+   pointing at the previous-good state, not the partial new state).
+3. Staging directory removed on success.
+
+`init`, `sync`, and `prune` share the same `commitAtomic(staging)`
+helper.
+
+### 6. `protocol_version` field on every agent-mode response
+
+```json
+{ "status": "question", "protocol_version": 1, "id": "q1.workspaces", ... }
+```
+
+Pinned at 1 for Phase 3; bumped to 2 only on breaking change.
+Versioning the schema (not just `next_call`) lets Phase 5 add trust
+banners without breaking existing agents.
+
+## Consequences
+
+**Positive**
+
+- Phase 5 (trust) can add `trust_level` to lockfile packs without a
+  schema migration (already at `schema_version: 1`; trust fields
+  become optional v1 additions).
+- Phase 6 (browser wizard) reuses the same agent-mode JSON shape over
+  a local HTTP server; the strict-sequencing model maps to HTTP
+  request/response naturally.
+- `agents/agent-config.overrides.yml` becomes a Git-tracked
+  declaration of user intent — diffable, reviewable, and never
+  silently overwritten.
+- Atomic writes give `sync` and `prune` crash safety without a
+  rollback subcommand.
+
+**Negative**
+
+- One extra YAML file in the consumer repo (overrides).
+- Strict sequencing means agents must replay the conversation if they
+  lose state mid-call; this is the simplest threat-model resolution
+  but pushes complexity onto agent authors.
+- Per-file `manifest_sha256` adds ~64 bytes per lockfile entry; for a
+  500-file install that's 32 KB. Acceptable.
+
+**Deferred to Phase 5**
+
+- npm package signature verification (SLSA Level 3 / `npm
+  provenance`). Reviewer A's "sign the package, not just the
+  manifest" call. Phase 5 owns trust gates; Phase 3 only records
+  provenance.
+
+## Rejected alternatives
+
+- **Single lockfile with `overrides:` section** — the original spec.
+  Rejected because the installer cannot detect untracked
+  user-authored overrides without either scanning `agents/overrides/`
+  (which a malicious agent could pollute) or trusting user edits to
+  the lockfile (which breaks "lockfile is installer-generated").
+- **Nonce-based agent mode** — overkill for v1. Re-evaluate when
+  agent mode lands on a remote surface.
+- **Rollback subcommand with lockfile history** — atomic writes
+  already give us crash safety; full version history is a Phase 6
+  concern (the browser wizard wants a timeline).
+
+## References
+
+- Roadmap: [`agents/roadmaps/monorepo-phase-3-typescript-installer.md`](../../agents/roadmaps/monorepo-phase-3-typescript-installer.md)
+- Discovery manifest: [ADR-015](ADR-015-discovery-manifest-contract.md)
+- CLI shell precedent: [ADR-012](ADR-012-typescript-cli-shell.md)
+- Council session: [`agents/runtime/council/responses/phase-3-installer-design.json`](../../agents/runtime/council/responses/phase-3-installer-design.json) <!-- council-ref-allowed: ADR decision-trace -->

package/docs/decisions/ADR-017-monorepo-physical-layout.md

@@ -0,0 +1,261 @@
+---
+adr: 017
+status: accepted
+date: 2026-05-21
+decision: monorepo-physical-layout
+supersedes: —
+superseded_by: —
+phase: v2.x · monorepo-phase-4-physical-package-layout
+type: prospective
+---
+
+# ADR-017 — Monorepo Physical Package Layout
+
+## Status
+
+**Accepted** · 2026-05-21 · external AI Council pass (`claude-sonnet-4-5`
++ `gpt-4o`, 2 rounds, `design` lens, actual cost $0.0961) on the Phase 4
+roadmap. Council issued **conditional approval** with four blockers and
+two refinements; this revision folds each into the design before the
+`--apply` step runs.
+
+Session: [`agents/runtime/council/responses/phase-4-physical-layout.json`](../../agents/runtime/council/responses/phase-4-physical-layout.json) <!-- council-ref-allowed: ADR decision-trace -->
+
+Companion artefacts:
+- [`agents/roadmaps/monorepo-phase-4-physical-package-layout.md`](../../agents/roadmaps/monorepo-phase-4-physical-package-layout.md)
+- [`dist/migration/move-plan.json`](../../dist/migration/move-plan.json) (94 moves, 432 core, 0 conflicts)
+- [`dist/migration/pre-move-snapshot.json`](../../dist/migration/pre-move-snapshot.json) (744 files hashed)
+- [`scripts/plan_physical_move.py`](../../scripts/plan_physical_move.py) (plan + apply)
+- [`scripts/verify_physical_move.py`](../../scripts/verify_physical_move.py) (post-move diff vs. snapshot)
+
+## Context
+
+Phases 1–3 produced the artefact metadata (`packs[]`, `workspaces[]`,
+`trust.level`, `install.removable`), the discovery manifest, and the
+TypeScript installer **without** moving a single file. The on-disk
+source tree is still flat:
+
+```text
+.agent-src.uncompressed/
+  rules/        # 72 entries
+  skills/       # 218 entries
+  commands/     # 129 entries
+  personas/     # 24 entries
+  contexts/     # 32 entries
+  templates/    # 24 scaffolds
+  …
+```
+
+This means the metadata says "this skill belongs to `pack.laravel`" but
+the file lives next to a Symfony skill and a finance persona. Consumers
+of the npm release, the consumer-side `.augment/` overlay, and the
+upcoming Phase 5 trust gates would all benefit from physical separation
+that mirrors the manifest. Phase 4 introduces that separation in one PR
+with a deterministic, history-preserving migration.
+
+The four risks the council flagged on Phase 3 (history loss, stale path
+refs, cross-pack drift, hand-edited paths) all bite hardest here.
+
+## Decision
+
+### 1. Layout — one core, one folder per pack
+
+```text
+packages/
+  core/
+    installer/                       # TS CLI (already there post-Phase 3)
+    .agent-src.uncompressed/         # rules + kernel skills + scaffolds
+  pack-php/.agent-src.uncompressed/
+  pack-laravel/.agent-src.uncompressed/
+  …
+  pack-ai-video/.agent-src.uncompressed/
+```
+
+No flag day: every commit between "before" and "after" the move builds
+and ships. The TS installer needs zero behavioural changes — only the
+`manifest-loader.ts` path roots flip.
+
+### 2. Mapping rules (deterministic, lockfile-stable)
+
+Implemented in [`scripts/plan_physical_move.py`](../../scripts/plan_physical_move.py):
+
+1. **Kernel rules** → `packages/core/` (allowlist, sanity-checked against
+   [`docs/contracts/kernel-membership.md`](../contracts/kernel-membership.md) §4).
+   The locked set is 10 entries; `user-interrupt-priority` was admitted
+   post-P2.2 and is included.
+2. **Core-trust artefacts** (`trust.level: core` AND
+   `install.removable: false`) → `packages/core/`.
+3. **Non-frontmatter trees** (`templates/`, `profiles/`, `presets/`,
+   `contexts/`, `user-types/`, `scripts/`, `ghostwriter/`, `packs/`,
+   `personas/`) → `packages/core/` verbatim. These are scaffolding and
+   product internals, not pack-routable artefacts.
+4. **Skill auxiliary files** (`prompts/*.md`, sub-pages inside a skill
+   directory) → inherit the destination of the nearest `SKILL.md` in
+   the parent directory tree. Codified to fix 9 false-positive conflicts
+   on Phase 4 dry-run.
+5. **Pack-routable artefacts** → `packages/pack-<id>/`, where `<id>` is
+   the first entry in `packs[]`. Tie-breaking by alphabetic pack id.
+6. **Quarantined scaffolds** (the 26 entries in
+   [`config/discovery/unassigned-artefacts.yml`](../../config/discovery/unassigned-artefacts.yml))
+   → `packages/core/` with `unassigned scaffold:` reason recorded in the
+   move plan. The top-level `.agent-src.uncompressed/README.md` was added
+   here during dry-run.
+7. **`primary pack: meta`** → `packages/core/` (package-internal
+   scaffolding, not a real pack).
+8. **Unknown / missing pack** → fall back to `packages/core/` AND emit
+   a conflict. `--apply` refuses to run if `conflicts > 0`.
+
+### 3. Mechanic — `git mv` only
+
+Every move uses `git mv` so `git log --follow` keeps working on every
+artefact post-move. The plan script's `--apply` mode is the only entry
+point; it refuses if any conflict remains. No human-edited paths.
+
+### 4. Byte-identity contract
+
+`task sync` + `task build-discovery` after the move must produce
+`.agent-src/`, `.augment/`, and `dist/discovery/discovery-manifest.json`
+byte-identical to the pre-move snapshot **except** for
+`artefacts[].path` values. [`scripts/verify_physical_move.py`](../../scripts/verify_physical_move.py)
+captures a post-move snapshot and diffs against
+`dist/migration/pre-move-snapshot.json`; the only allowed delta is the
+`path` field per artefact.
+
+### 5. Rollback
+
+The whole move is a single PR. `git revert <merge-sha>` restores the
+prior layout in one commit; the next `task sync` round-trip is back to
+the pre-move snapshot. No data migration, no manifest schema change, no
+installer behaviour change.
+
+## Consequences
+
+### Positive
+
+- Metadata-to-disk parity: a consumer can now `cd packages/pack-laravel`
+  and see exactly what `pack.laravel` ships, no manifest indirection.
+- Phase 5 (trust) lands cleanly inside `packages/core/installer/` and
+  reads per-pack metadata from `packages/pack-*/.agent-src.uncompressed/`.
+- Phase 6 (browser wizard) maps packs 1:1 to its left-nav.
+- Cross-pack drift is now lintable (`task lint-pack-boundaries` in
+  Phase 4.4 of the roadmap).
+- `git log --follow` keeps working — no history loss.
+
+### Negative
+
+- One large PR (~526 file moves). Reviewers need the move plan as the
+  primary review artefact, not per-file diff inspection.
+- Editors with the old tree open will hit broken paths until they pull.
+  Mitigated by docs-update in the same PR (`AGENTS.md`, `README.md`,
+  `docs/architecture.md`).
+- Path refs in CI workflows, Taskfile, and the discovery scanner need
+  one-line updates. The roadmap enumerates each.
+
+### Neutral
+
+- The npm tarball shape changes (paths only). The installer copies
+  files by manifest entry, not by source path, so consumers see no
+  difference.
+
+## Alternatives considered
+
+1. **Phased move (one pack per PR).** Rejected: 16 PRs, partial states
+   on disk for weeks, `task sync` invariants harder to enforce.
+2. **Symlink farm.** Rejected: Windows support, npm tarball duplication,
+   and the installer would have to dereference paths.
+3. **Stay flat, lift packs into manifest-only.** Rejected: this is the
+   current state; it forfeits the metadata-to-disk parity that Phase 5
+   and Phase 6 depend on.
+
+## Council resolution (Round 2)
+
+Four blocking items and two refinements raised by the council; each
+resolved before `--apply` runs.
+
+### B1 — Final source location of `.agent-src.uncompressed/`
+
+The council asked whether the source tree nests inside `packages/core/`
+(current design) or becomes a peer `pack-core/`. **Decision: keep
+`packages/core/.agent-src.uncompressed/`.** Three reasons:
+
+1. `packages/core/` is the engine + installer + kernel rules +
+   scaffolding (templates, profiles, presets, contexts, user-types).
+   None of that is pack-routable; making it a "pack" inverts the
+   product mental model.
+2. The installer in `packages/core/installer/` already lives next to
+   the manifest loader; co-locating the rules that bootstrap the
+   installer reduces cross-package import chains.
+3. The TS installer consumes `dist/discovery/discovery-manifest.json`,
+   not source paths, so the "location is privileged" critique does not
+   bite — the manifest is the API.
+
+### B2 — `git mv` rename detection at scale
+
+Default `diff.renameLimit` since git 2.9 is 1000. Plan: 94 explicit
+`git mv` operations + 1 directory rename for `core/`. Each move is
+content-identical (no edits during move). Test gate: after `--apply`,
+run `git diff --name-status HEAD~1` and assert `R100` (100 % rename
+similarity) on every moved file. Verification script enforces this.
+
+### B3 — Consumer-facing output contract
+
+`task sync` writes `.agent-src/` (compressed) and `.augment/` (overlay)
+at repo root — **unchanged** location and structure. The byte-identity
+contract covers exactly these two trees plus the discovery manifest.
+What changes:
+
+- `dist/discovery/discovery-manifest.json` `artefacts[].path` values
+  (path-only delta, enforced by `verify_physical_move.py`).
+- npm tarball internal paths (consumers never touch these; installer
+  uses manifest entries).
+
+What stays identical: `.agent-src/`, `.augment/`, manifest checksums
+of non-path fields, lockfile schema, installer behaviour.
+
+### B4 — Installer dual-layout support
+
+Not required. Consumers install via `npm install
+@event4u/agent-config@<version>`; each version ships a self-consistent
+tarball. There is no "consumer pulls mid-PR" scenario because consumers
+do not consume the source repo — they consume the published tarball.
+Source-tree contributors who pull the merge commit move atomically
+with the layout. The "dual-layout" complexity the council proposed
+exists in code-host-as-CDN ecosystems we do not target.
+
+### R1 — `primary_pack` frontmatter field
+
+`scripts/plan_physical_move.py` already uses `packs[0]` as the
+destination. Round-2 hardening: the plan also reads an explicit
+`primary_pack:` frontmatter field when present and prefers it over
+`packs[0]`. Lint that requires `primary_pack` on every pack-routable
+artefact lands in Phase 4.4 (out of scope for the move itself; the
+move uses today's data and the new fallback).
+
+### R2 — Pre-move pack-boundary lint
+
+The current plan dry-run finds 0 conflicts after the auxiliary-file
+inheritance rule landed. A cross-pack-reference lint (an artefact in
+`pack.laravel` citing one in `pack.symfony` without a declared
+dependency) is deferred to Phase 4.4 — the move itself does not edit
+file contents, so cross-pack references survive the move byte-identical.
+
+## Compliance + verification
+
+- `scripts/plan_physical_move.py` is the only mover. Hand-edited paths
+  fail `task verify-physical-move`.
+- `scripts/verify_physical_move.py` enforces the byte-identity
+  contract.
+- `task ci` runs both as a hard gate post-move.
+- Per-pack lint matrix lands in Phase 4.4 of the roadmap.
+
+## Future work
+
+- Phase 4.4 — per-pack `pack.yaml` + boundary lint.
+- Phase 4.5 — contributor scaffolders (`task new-skill`,
+  `task move-artefact`).
+- Phase 6 (optional) — split distribution per pack as separate npm
+  packages. Specification removed 2026-05-24 (drift audit, finding
+  F-1): the 150-line "documented-only" addendum had zero consumers
+  and ~6 months of unmaintained drift versus the bundled-tarball
+  model. Restore from git history at `d06af2c5` if a real consumer
+  ever asks for a single-pack install path.