@event4u/agent-config 5.10.1 → 6.0.0

package/docs/contracts/frontmatter-contract.md

@@ -19,8 +19,8 @@ from these alone — **no manual workspace or pack list is ever maintained**.
 
 | Key | Type | Vocabulary | Source |
 |---|---|---|---|
-| `workspaces` | `array<string>`, ≥1 | [`config/discovery/workspaces.yml`](../../config/discovery/workspaces.yml) | role-based axis |
-| `packs` | `array<string>`, ≥1 | [`config/discovery/packs.yml`](../../config/discovery/packs.yml) | functional axis |
+| `workspaces` | `array<string>`, ≥1 | [`src/config/discovery/workspaces.yml`](../../config/discovery/workspaces.yml) | role-based axis |
+| `packs` | `array<string>`, ≥1 | [`src/config/discovery/packs.yml`](../../config/discovery/packs.yml) | functional axis |
 | `lifecycle` | enum | `active` · `experimental` · `deprecated` · `archived` | review cycle |
 | `trust.level` | enum | `core` · `professional` · `experimental` · `advisory` · `restricted` | safety gate |
 | `trust.confidence` | enum | `high` · `medium` · `low` | curator signal |
@@ -31,7 +31,7 @@ from these alone — **no manual workspace or pack list is ever maintained**.
 Vocabularies are **closed**. New entries require an amendment to
 [`ADR-013`](../decisions/ADR-013-discovery-frontmatter-contract.md) in the
 same PR. The linter
-([`scripts/lint_artefact_frontmatter.py`](../../scripts/lint_artefact_frontmatter.py))
+([`scripts/lint_artefact_frontmatter.py`](../../src/scripts/lint_artefact_frontmatter.py))
 rejects free-text values.
 
 ## Worked examples
@@ -109,7 +109,7 @@ install:
 
 Artefacts that genuinely cannot yet carry frontmatter (early scaffolds,
 generated stubs) MUST be listed in
-[`config/discovery/unassigned-artefacts.yml`](../../config/discovery/unassigned-artefacts.yml)
+[`src/config/discovery/unassigned-artefacts.yml`](../../config/discovery/unassigned-artefacts.yml)
 with a `reason`. A quarantined entry MUST NOT also carry the five keys —
 the linter rejects that collision.
 
@@ -118,7 +118,7 @@ the linter rejects that collision.
 | Surface | What runs | When |
 |---|---|---|
 | Local | `task lint-artefact-frontmatter` | manual / pre-commit |
-| Pre-commit | `pre-commit-roadmap-progress` template | when `.agent-src.uncondensed/*.md`, `config/discovery/*.yml`, or the linter itself is staged |
+| Pre-commit | `pre-commit-roadmap-progress` template | when `.agent-src.uncondensed/*.md`, `src/config/discovery/*.yml`, or the linter itself is staged |
 | CI | `task ci` → `lint-artefact-frontmatter` | every push / PR |
 
 Install the pre-commit hook with:
@@ -136,5 +136,5 @@ are staged.
 Frontmatter survives the `task sync` condensation pipeline. Path-bearing
 keys (`load_context`) may be rewritten relative to the projected location,
 but the five Phase-1 keys above are byte-stable between
-`.agent-src.uncondensed/`, `.agent-src/`, and `.augment/`. Enforced by
+`.agent-src.uncondensed/`, `dist/agent-src/`, and `.augment/`. Enforced by
 `tests/test_frontmatter_roundtrip.py`.

package/docs/contracts/ghostwriter-schema.md

@@ -326,7 +326,7 @@ cluster registration.
 ## Gitignore
 
 `agents/reference/ghostwriter/*.md` (except `README.md`) is added to the
-package-managed `.gitignore` block ([`config/gitignore-block.txt`](../../config/gitignore-block.txt))
+package-managed `.gitignore` block ([`src/config/gitignore-block.txt`](../../config/gitignore-block.txt))
 and ignored by default. A `--shared` opt-in to commit profiles is
 deferred to v2.
 

package/docs/contracts/gui-wizard.md

@@ -27,7 +27,7 @@ retired; the single real installer is `scripts/install.py`.
 - Atomic / 2PC writes: [`src/server/io/atomicWrite.ts`](../../src/server/io/atomicWrite.ts), [`atomicMultiWrite.ts`](../../src/server/io/atomicMultiWrite.ts)
 - SPA: [`src/ui/`](../../src/ui/) (entry `src/ui/pages/WizardPage.tsx`)
 - CLI boot + `WIZARD_READY` contract: [`src/cli/commands/uiServe.ts`](../../src/cli/commands/uiServe.ts)
-- The single installer (all real writes): [`scripts/install.py`](../../scripts/install.py)
+- The single installer (all real writes): [`scripts/install.py`](../../src/scripts/install.py)
 - Tests: [`tests/server/`](../../tests/server/) + [`tests/e2e/`](../../tests/e2e/)
 
 ## Local-only invariant

package/docs/contracts/harness-expectations.md

@@ -1,3 +1,8 @@
+---
+stability: beta
+keep-beta-until: 2026-09-04
+---
+
 # Harness Expectations — when AI tool behaviour looks like a package bug but isn't
 
 **Status:** Active (Phase D of `road-to-clean-skill-distribution-channels.md`)

package/docs/contracts/hook-architecture-v1.md

@@ -267,7 +267,7 @@ Rationale:
 - `install.py`'s existing tool projection lays down `.augment/`
   unconditionally; piggy-backing on that directory means consumers
   do not need a separate "scripts" install step.
-- The other two paths (`.agent-src/scripts/`,
+- The other two paths (`dist/agent-src/scripts/`,
   `.agent-src.uncondensed/scripts/`) only populate in
   source-checkouts of the package itself.
 

package/docs/contracts/host-agent-protocol.md

@@ -41,6 +41,15 @@ their semver, not derived from unstable stdout parsing.
 | **Cline (VS Code ext)** | None. Hooks (`~/Documents/Cline/Hooks/`) are post-event. | None at the protocol layer. | **Tier 3** — observe-only. |
 | **Windsurf (Cascade)** | None. Hooks (`.windsurf/hooks.json`) are post-event. | None at the protocol layer. | **Tier 3** — observe-only. |
 
+> **Detection (ADR-068).** This table is mirrored by `HOST_INVENTORY` in
+> `src/cli/python/workspace_hosts.py`; `tests/test_workspace_hosts.py` asserts
+> the two agree, so this markdown stays the source of truth. `workspace_hosts.py
+> detect <id>` returns a host's **effective tier** (its inventory tier, demoted
+> to 3 if the Tier-1 CLI is absent from PATH — fail-closed), side-effect-free
+> (PATH probe only, never spawns a host CLI). `POST /api/v1/workspace/launch`
+> reports it (`effective_tier` / `cli_present` / `mode`); it does **not** drive
+> the host (the Tier-1 drive loop is unbuilt).
+
 ## Tier definitions
 
 - **Tier 1 — first-class.** Both `launch` and `emit_trace` are stable.
@@ -58,6 +67,15 @@ their semver, not derived from unstable stdout parsing.
 
 - The workspace v0 ships against **Claude Code** as the single Tier-1 host.
   Codex and Gemini are wired but secondary (no skill surface — see ADR-024).
+  The single-turn drive executor lands in
+  [`ADR-070`](../decisions/ADR-070-tier1-drive-loop.md)
+  (`src/cli/python/workspace_drive.py`): it spawns the host CLI, parses the
+  envelope by named keys, and fails closed to the Tier-3 inbox on any error.
+  All three Tier-1 hosts are wired —
+  [`ADR-072`](../decisions/ADR-072-codex-gemini-drive-configs.md) adds the
+  `codex` (`codex exec --json`, NDJSON) and `gemini`
+  (`gemini -p … --output-format json`) configs alongside `claude-code`.
+  Multi-turn / tool execution remain v1.
 - Tier-3 hosts get the **inbox handoff** fallback only: workspace writes the
   rendered prompt + skill body into the inbox file and surfaces a one-line
   copy-to-clipboard banner. No tighter integration is attempted in v0.
@@ -83,7 +101,7 @@ their semver, not derived from unstable stdout parsing.
   [`ADR-023`](../decisions/ADR-023-host-agent-protocol.md) ·
   [`ADR-024`](../decisions/ADR-024-workspace-v0-feature-floor.md) ·
   [`ADR-025`](../decisions/ADR-025-workspace-chrome.md).
-- Skill: [`ai-council`](../../.agent-src/skills/ai-council/SKILL.md) — uses
+- Skill: [`ai-council`](../../dist/agent-src/skills/ai-council/SKILL.md) — uses
   the same CLI subprocess shape (claude / codex / gemini) for council
   members; the workspace inherits the proven invocation paths.
 - Hooks: [`hook-architecture-v1`](hook-architecture-v1.md) — covers the

package/docs/contracts/install-scopes.md

@@ -1,3 +1,8 @@
+---
+stability: beta
+keep-beta-until: 2026-09-04
+---
+
 # Install Scopes — user-global vs project-local
 
 **Status:** Active (locked 2026-05-25 via Phase B of `road-to-clean-skill-distribution-channels.md`)
@@ -71,7 +76,7 @@ The scope guard does **not** make the picking decision; it enforces "one scope p
 ## See also
 
 - [`docs/contracts/skill-distribution-channels.md`](skill-distribution-channels.md) — per-tool canonical channel.
-- [`scripts/_lib/scope_guard.sh`](../../scripts/_lib/scope_guard.sh) — guard implementation.
-- [`scripts/cleanup_other_scope.sh`](../../scripts/cleanup_other_scope.sh) — companion cleanup.
+- [`scripts/_lib/scope_guard.sh`](../../src/scripts/_lib/scope_guard.sh) — guard implementation.
+- [`scripts/cleanup_other_scope.sh`](../../src/scripts/cleanup_other_scope.sh) — companion cleanup.
 - [`tests/test_cleanup_other_scope.py`](../../tests/test_cleanup_other_scope.py) — safety regression.
 - [`README.md` § Installation](../../README.md) — consumer-facing install path.

package/docs/contracts/installed-tools-lockfile.md

@@ -9,7 +9,7 @@ Canonical wire-format spec for `agents/installed-tools.lock` — the
 project-committed bill of materials for AI tooling installed into this
 repository.
 
-- **Authoritative module:** [`scripts/_lib/installed_tools.py`](../../scripts/_lib/installed_tools.py)
+- **Authoritative module:** [`scripts/_lib/installed_tools.py`](../../src/scripts/_lib/installed_tools.py)
 - **ADR:** [`docs/decisions/ADR-008-installed-tools-manifest.md`](../decisions/ADR-008-installed-tools-manifest.md)
 - **Workflow guide:** [`docs/guidelines/agent-infra/installed-tools-manifest.md`](../guidelines/agent-infra/installed-tools-manifest.md)
 - **Active roadmap:** P1.1 of the `road-to-multi-package-coexistence`
@@ -108,7 +108,7 @@ must reject manifests that contain array-index pointers.
 
 - `write_manifest(path, version, tools, *, deploy_roots=None)` always emits `schema_version: 2`.
 - Optional v2 fields (`deploy_roots`, per-tool `files` / `merged_keys` / `status`) are emitted only when non-empty, so a v1-shaped call produces a v2 file that is structurally minimal and v1-readable for the core fields.
-- All writes are crash-safe via [`scripts/_lib/fs_atomic.py`](../../scripts/_lib/fs_atomic.py) (`write_atomic`: tmp + fsync + rename + parent-dir fsync). See P1.0 of the multi-package roadmap.
+- All writes are crash-safe via [`scripts/_lib/fs_atomic.py`](../../src/scripts/_lib/fs_atomic.py) (`write_atomic`: tmp + fsync + rename + parent-dir fsync). See P1.0 of the multi-package roadmap.
 
 ## Determinism
 

package/docs/contracts/linear-ai-rules-inclusion.md

@@ -30,7 +30,7 @@ keep-beta-until: 2026-08-12
 Two transformations the digest builder (Phase 3 Step 2) must apply
 to *included-degraded* rules:
 
-1. Strip references to scripts, `.agent-settings.yml`, `.agent-src/`,
+1. Strip references to scripts, `.agent-settings.yml`, `dist/agent-src/`,
    `.augment/`, `agents/`, and `task <foo>` invocations.
 2. Replace `[link](path)` to other rules/skills/files with a footnote
    or inline summary, since the path won't resolve outside this repo.
@@ -88,7 +88,7 @@ and shipped from this repository. They have no meaning for a third-party
 agent that does not maintain `event4u/agent-config`.
 
 `agent-docs`, `architecture`, `artifact-drafting-protocol`,
-`augment-portability`, `augment-source-of-truth`, `capture-learnings`,
+`augment-portability`, `source-of-truth`, `capture-learnings`,
 `docs-sync`, `guidelines`, `package-ci-checks`, `preservation-guard`,
 `reviewer-awareness`, `roadmap-progress-sync`,
 `role-mode-adherence`, `rule-type-governance`, `runtime-safety`,

package/docs/contracts/linear-ai-three-layers.md

@@ -126,5 +126,5 @@ does not maintain `event4u/agent-config`.
 ## Source of truth
 
 - Per-rule decision: [`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md)
-- Builder script: [`scripts/build_linear_digest.py`](../../scripts/build_linear_digest.py)
+- Builder script: [`scripts/build_linear_digest.py`](../../src/scripts/build_linear_digest.py)
 - Generated digests: `dist/linear/{workspace,team,personal}.md` (gitignored)

package/docs/contracts/linter-structural-model.md

@@ -64,9 +64,9 @@ imperatives (`NEVER COMMIT.`).
 ## Phase 1 calibration (2026-05-08)
 
 Sweep covered all 310 lintable artifacts via
-[`scripts/measure_density.py`](../../scripts/measure_density.py); raw
+[`scripts/measure_density.py`](../../src/scripts/measure_density.py); raw
 data lives at `agents/runtime/density/snapshot.jsonl` (local-only — re-run
-`python3 scripts/measure_density.py --root .agent-src --jsonl
+`python3 scripts/measure_density.py --root dist/agent-src --jsonl
 agents/runtime/density/snapshot.jsonl` to regenerate).
 
 | Type | Count | Avg density | Median | Bucket [0.4-0.6] | Bucket [0.6-1.0] |

package/docs/contracts/load-context-budget-model.md

@@ -45,7 +45,7 @@ Where:
 - `transitive_closure` walks `load_context:` declarations on
   context files **up to depth 2** — see § Nesting cap below.
 - `RawSize` is the byte size of the condensed file
-  (`.agent-src/...`), measured by `os.path.getsize()`. The
+  (`dist/agent-src/...`), measured by `os.path.getsize()`. The
   uncondensed source paths in frontmatter are mapped to their
   condensed counterparts before sizing.
 - A context loaded by N always-rules counts **N times** (once per

package/docs/contracts/load-context-schema.md

@@ -60,7 +60,7 @@ opt-in and budget-gated.
     against `.agent-src.uncondensed/`).
   - `agents/settings/contexts/<file>.md` — project-local material (consumer
     repo only).
-  - `.agent-src/contexts/<file>.md` — condensed mirror; tolerated
+  - `dist/agent-src/contexts/<file>.md` — condensed mirror; tolerated
     defensively, not authored.
 - The `.agent-src.uncondensed/` prefix is **rejected** by the schema
   regex and by `lint_load_context.py` with a remediation hint pointing

package/docs/contracts/local-analytics.md

@@ -43,9 +43,17 @@ interactions:
 - `document.created` · `document.edited` · `document.exported`
 - `explain.opened` · `explain.mode_toggled` · `why.invoked`
 - `knowledge.queried` · `knowledge.source_clicked`
+- `rule.tier2_loaded` · `persona.cited` · `skill.activated` — **6.0.0-C
+  evidence-based-pruning measurement.** `rule.tier2_loaded` fires when a
+  router-gated (tier-2) rule is loaded; `persona.cited` when a persona is
+  cited-in-use by a skill/command; `skill.activated` when a skill activates
+  under the active profile. Payload fields: the artefact `id` (or `rule`,
+  `persona`, `skill`) and the active `profile` — nothing else. These feed the
+  thresholds in [`evidence-based-pruning.md`](evidence-based-pruning.md) so a
+  later, data-bearing roadmap cuts on usage, not on a guessed target.
 
 No prompt bodies. No response bodies. No PII. Only counters, role
-labels, task slugs (already public), and durations.
+labels, task slugs (already public), artefact ids, and durations.
 
 ## Storage
 

package/docs/contracts/low-impact-corpus-format.md

@@ -7,7 +7,7 @@ keep-beta-until: 2026-08-13
 
 Parser-visible invariants for `agents/decisions/low-impact-decisions.md` and any
 upstream seed at the same path. The hardened parser lives in
-[`scripts/ai_council/low_impact_corpus.py`](../../scripts/ai_council/low_impact_corpus.py)
+[`scripts/ai_council/low_impact_corpus.py`](../../src/scripts/ai_council/low_impact_corpus.py)
 and ships in two modes:
 
 | Mode | Entry point | Behaviour on drift |

package/docs/contracts/mcp-cloud-scope.md

@@ -38,8 +38,8 @@ prose-only.
 ### `mcp_scope: lite` — hosted, read-only knowledge surfaces
 
 - **What it serves:** the governance content as MCP `prompts` and
-  `resources` — skills (`.agent-src/skills/<name>/SKILL.md`), commands
-  (`.agent-src/commands/**/*.md`), rules (`.agent-src/rules/*.md`),
+  `resources` — skills (`dist/agent-src/skills/<name>/SKILL.md`), commands
+  (`dist/agent-src/commands/**/*.md`), rules (`dist/agent-src/rules/*.md`),
   guidelines (`docs/guidelines/`), and the docs index. Plus a small
   set of **read-only tools** (`memory_lookup`, `chat_history_read`,
   `list_*`, `read_resource_body`) that touch the content blob only.
@@ -64,7 +64,7 @@ prose-only.
   `prompts/get`, `resources/list`, `resources/read` **plus**
   execution-side tools (`lint_skills`, `chat_history_append`, and
   the MVP-2 deferred tool set). Reads from the live worktree
-  (`.agent-src/` projection), not a release-pinned blob.
+  (`dist/agent-src/` projection), not a release-pinned blob.
 - **What it requires:** a local install per Quickstart (`npx
   @event4u/agent-config init` or `task mcp:setup`) — Python runtime,
   the package's ~112 scripts on disk, and a consumer-side
@@ -118,8 +118,8 @@ prose-only.
   + `resources/read` — read-only, parity with the local stdio surface.
 - **Source data:** release-pinned content blob in R2 under the key
   shape `releases/v<X.Y.Z>-<sha>/` (immutable per release). The blob
-  bundles `.agent-src/skills/<name>/SKILL.md`,
-  `.agent-src/commands/**/*.md`, and `docs/guidelines/` (the same
+  bundles `dist/agent-src/skills/<name>/SKILL.md`,
+  `dist/agent-src/commands/**/*.md`, and `docs/guidelines/` (the same
   projection the local kernel reads). Never reads `.agent-src.uncondensed/`.
 - **Identity surface:** `serverInfo.version` reads from a Worker-
   bundled constant, `_meta.packageVersion` reads from a
@@ -202,7 +202,7 @@ runtime mode switch.
   surface) is gated.
 - **Token handling:** the secret is prompted for interactively by
   `wrangler` — never accepted via argv per
-  [`tool-safety`](../../.agent-src/rules/tool-safety.md). The
+  [`tool-safety`](../../dist/agent-src/rules/tool-safety.md). The
   Worker never logs the secret, never echoes it in error bodies,
   and never includes it in telemetry sinks.
 - **README allowed to recommend:** mode `bearer-auth` for private

package/docs/contracts/mcp-phase-1-scope.md

@@ -25,11 +25,11 @@ phase with its own design-call gate.
 
 - Transport: **stdio**. No SSE, no HTTP, no WebSocket.
 - MCP primitives: **`prompts/list`** + **`prompts/get`** — read-only.
-- Source data: **`.agent-src/skills/<name>/SKILL.md`** and
-  **`.agent-src/commands/**/*.md`** (condensed projections, never the
+- Source data: **`dist/agent-src/skills/<name>/SKILL.md`** and
+  **`dist/agent-src/commands/**/*.md`** (condensed projections, never the
   uncondensed source-of-truth tree).
 - Loaded set (Phase 2): every well-formed skill + command under
-  `.agent-src/` (Phase 1 hand-picked set retained as a smoke fixture
+  `dist/agent-src/` (Phase 1 hand-picked set retained as a smoke fixture
   in `prompts.py::PHASE_1_SKILLS`).
 - **Pagination** (B4): cursor-based `nextCursor` on `prompts/list`,
   default `page_size=100`. Cursor is an opaque stringified offset.
@@ -138,7 +138,7 @@ lift waits on SDK support):
   `scripts/mcp_server/__init__.py::__version__`. Bumps on
   **wire-surface** changes only: new tool, new resource MIME type,
   protocol-level break. Does **not** bump for content edits inside
-  `.agent-src/`.
+  `dist/agent-src/`.
 - **`packageVersion`** — read from `package.json::version` at boot.
   Bumps on every agent-config bundle release; build-ID semantics, not
   a stability signal.
@@ -159,7 +159,7 @@ change invalidates it.
 - **No HTTP / SSE listener** in the image. Stdio is the only wire.
 - The image embeds `scripts/mcp_server/`, the two tool dependencies
   (`scripts/skill_linter.py`, `scripts/chat_history.py`),
-  `.agent-src/`, `docs/guidelines/`, and `package.json`. Nothing
+  `dist/agent-src/`, `docs/guidelines/`, and `package.json`. Nothing
   outside the COPY-listed paths reaches the runtime stage.
 - The image runs as a non-root user (`mcp:mcp`); host volumes mounted
   for `chat_history_append` writes must be writable by that uid/gid.

package/docs/contracts/measurement-baseline.md

@@ -17,10 +17,10 @@ Four axes, all numeric, all reproducible from the same input:
 
 | Axis | Source | Definition | Units |
 |---|---|---|---:|
-| **selection accuracy** | [`scripts/bench_runner.py`](../../scripts/bench_runner.py) | Keyword-overlap ranker hits the expected skill in top-K | % |
-| **cost** | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) session jsonl | Token+USD per model, captured live | USD |
+| **selection accuracy** | [`scripts/bench_runner.py`](../../src/scripts/bench_runner.py) | Keyword-overlap ranker hits the expected skill in top-K | % |
+| **cost** | [`scripts/cost/track.mjs`](../../src/scripts/cost/track.mjs) session jsonl | Token+USD per model, captured live | USD |
 | **quality** | regex / rubric assertions per prompt | `quality_assertion` matches in agent output | % |
-| **projection fidelity** | [`scripts/bench_per_tool.py`](../../scripts/bench_per_tool.py) | `accuracy(tool) / accuracy(augment)` for skill-projecting tools | ratio |
+| **projection fidelity** | [`scripts/bench_per_tool.py`](../../src/scripts/bench_per_tool.py) | `accuracy(tool) / accuracy(augment)` for skill-projecting tools | ratio |
 
 Schemas: [`benchmark-report-schema.md`](benchmark-report-schema.md) ·
 [`benchmark-corpus-spec.md`](benchmark-corpus-spec.md). Reports land at
@@ -40,7 +40,7 @@ to either YAML restart the 60-day clock per
 
 ## What counts as drift
 
-[`scripts/bench_drift_check.py`](../../scripts/bench_drift_check.py)
+[`scripts/bench_drift_check.py`](../../src/scripts/bench_drift_check.py)
 compares the latest report against a sliding window of the prior N runs
 (default 5) for the same corpus.
 
@@ -64,7 +64,7 @@ TASK bench:baseline-ready EXIT 0 IS THE ONLY AUTHORITY.
 NO ANECDOTE, NO INDIVIDUAL REPORT, NO ROADMAP-SIDE OVERRIDE.
 ```
 
-[`scripts/bench_baseline_ready.py`](../../scripts/bench_baseline_ready.py)
+[`scripts/bench_baseline_ready.py`](../../src/scripts/bench_baseline_ready.py)
 returns exit 0 iff both:
 
 1. **Wall-clock soak:** `today − internal/bench/baseline-start.txt ≥ --min-days` (default 60)

package/docs/contracts/migrate-command.md

@@ -1,6 +1,11 @@
+---
+stability: beta
+keep-beta-until: 2026-09-04
+---
+
 # `agent-config migrate` — Behavior Contract
 
-> **Status:** active · **Owner:** maintainer (`scripts/_cli/cmd_migrate.py`) · **Opened:** 2026-05-29
+> **Status:** active · **Owner:** maintainer (`src/scripts/_cli/cmd_migrate.py`) · **Opened:** 2026-05-29
 >
 > Source: `road-to-one-migrate-command.md` Phase 1. Locks the union of
 > cleanup actions performed by the unified `./agent-config migrate`
@@ -11,10 +16,12 @@
 ## Design intent
 
 One opinionated command runs every cleanup step end-to-end. No flag
-matrix to pick between behaviors, no surprises. The single flag is
-`--dry-run` (preview vs. apply). The legacy three-command surface —
-`migrate`, `migrate-state`, `migrate-to-global` — is collapsed into
-one entry point.
+matrix to pick between behaviors, no surprises. The flags are
+`--dry-run` (preview vs. apply), `--check` (read-only probe with a
+verdict in the exit code), and `--from {4,5}` (advisory source-major
+declaration — 4.x = composer-era, 5.x = npx-era). The legacy
+three-command surface — `migrate`, `migrate-state`, `migrate-to-global`
+— is collapsed into one entry point.
 
 Rationale:
 
@@ -117,6 +124,35 @@ break detection for later ones:
 - The summary is prefixed with `would` instead of past-tense verbs
   so log scraping can distinguish dry-run from real runs.
 
+## `--check` semantics
+
+`--check` is a **read-only probe** for scripts / CI — same detection +
+`would …` action list as `--dry-run`, but the verdict lives in the
+**exit code** instead of requiring output parsing:
+
+- Already on the 6.0 layout (no legacy signal) → prints
+  `✅  on the 6.0 layout — no migration needed.` and exits **0**.
+- Legacy install detected → prints
+  `⚠️  legacy install detected — N pending action(s) …` followed by the
+  `would …` list, and exits **2**.
+- **Zero filesystem mutations**, like `--dry-run`.
+- `--check` and `--dry-run` are **mutually exclusive** (argparse group):
+  they share the read-only detection but differ in exit semantics, so
+  combining them is rejected.
+
+## `--from {4,5}` semantics
+
+`--from` declares the source major for documentation / log purposes —
+**4.x = composer-era**, **5.x = npx-era**. Detection itself stays
+signal-based (the authoritative source), so `--from` never changes
+which actions run:
+
+- The declared major is echoed (`ℹ️  declared source major: N.x`).
+- A mismatch with the detected signal (`--from 4` with no composer
+  entry, `--from 5` with no npm entry) prints an advisory note and the
+  command proceeds from the detected signals.
+- `--from` composes with `--dry-run`, `--check`, and the apply path.
+
 ## Idempotency contract
 
 Re-running on a fully-migrated consumer:
@@ -149,9 +185,9 @@ intentionally **outside** the unified `migrate` command:
 
 | Code | Meaning |
 |---|---|
-| `0` | Migration complete, or nothing to migrate (already migrated), or `--dry-run` plan computed. |
+| `0` | Migration complete, or nothing to migrate (already migrated), or `--dry-run` plan computed, or `--check` found the install already on the 6.0 layout. |
 | `1` | Detection error — unreadable file, invalid JSON in `composer.json` / `package.json`, work-engine v0 → v1 conversion error. |
-| `2` | Unused (reserved). |
+| `2` | `--check` only: a legacy install was detected (migration pending). Never returned by the apply or `--dry-run` paths. |
 
 The apply path never exits non-zero on a partial-migration recovery
 — a step that fires its predicate is allowed to complete cleanly
@@ -193,5 +229,5 @@ Restoring the previous command surface:
 - `road-to-portable-runtime-and-update-check.md` § P3.5–P3.6 — the
   original `migrate` command (composer / npm cleanup).
 - `scripts/_cli/cmd_migrate.py` — implementation.
-- `.agent-src/templates/scripts/work_engine/migration/v0_to_v1.py`
+- `dist/agent-src/templates/scripts/work_engine/migration/v0_to_v1.py`
   — state-file migration helper invoked from step 4.

package/docs/contracts/multi-tool-projection-fidelity.md

@@ -12,13 +12,13 @@ Names the **per-tool guarantees** the projection pipeline (`scripts/condense.py
 
 ## Source of truth
 
-Every projection starts from `.agent-src/` (condensed) which is generated from `.agent-src.uncondensed/`. The projection layer **never** writes to source; it only reads.
+Every projection starts from `dist/agent-src/` (condensed) which is generated from `.agent-src.uncondensed/`. The projection layer **never** writes to source; it only reads.
 
 ## Per-tool projection map
 
 | Tool | Rules surface | Skills surface | Commands surface | Frontmatter grammar |
 |---|---|---|---|---|
-| **Augment** (host) | `.augment/rules/*.md` (copies; symlink opt-in via `augment.rules_use_symlinks`) | `.augment/skills/<name>/SKILL.md` (symlink → `.agent-src/skills/`) | `.augment/commands/*.md` | full source frontmatter preserved |
+| **Augment** (host) | `.augment/rules/*.md` (copies; symlink opt-in via `augment.rules_use_symlinks`) | `.augment/skills/<name>/SKILL.md` (symlink → `dist/agent-src/skills/`) | `.augment/commands/*.md` | full source frontmatter preserved |
 | **Claude** (Code + Desktop) | `.claude/rules/*.md` | `.claude/skills/<name>/SKILL.md` | `.claude/skills/<name>/SKILL.md` (commands rendered as skills) | full source frontmatter preserved |
 | **Cursor** | `.cursor/rules/*.mdc` + legacy `.md` symlinks (130 files = 65 × 2) | **not projected** | `.cursor/commands/*.md` | `description`, `globs`, `alwaysApply` only — `triggers`, `routes_to`, `tier`, `type` are **dropped** |
 | **Windsurf** | `.windsurfrules` (single concatenated file) + `.windsurf/rules/*.md` (per-rule) | **not projected** | `.windsurf/workflows/*.md` | concatenated body; per-rule frontmatter only retained in `.windsurf/rules/`, not in the legacy `.windsurfrules` single-file |
@@ -84,7 +84,7 @@ to a concrete model.
 | Tool | Consumption |
 |---|---|
 | Claude | When `model.auto_switch: auto` AND the tier is `high`/`medium`/`lite`, the generator rewrites `model_tier: <tier>` to a **native `model:` key** (`high→opus`, `medium→sonnet`, `lite→haiku`) in the rendered `.claude/skills/<name>/SKILL.md` (sub-files stay symlinked; only `SKILL.md` is a rendered copy). `inherit`/absent emit nothing. `suggest` (default) / `off` emit nothing — pure symlink. |
-| Augment | Keeps the **neutral `model_tier:`** field (symlinked from `.agent-src/`); the `model-recommendation` rule names the tier as a one-question suggestion (Augment has no per-turn override). **No package-maintained per-vendor table** — the agent resolves the tier to its own model. |
+| Augment | Keeps the **neutral `model_tier:`** field (symlinked from `dist/agent-src/`); the `model-recommendation` rule names the tier as a one-question suggestion (Augment has no per-turn override). **No package-maintained per-vendor table** — the agent resolves the tier to its own model. |
 | Cursor / Windsurf / Cline / Gemini / Copilot | No skill surface — field is inert; if surfaced, the same suggestion-only contract applies. |
 
 The native Claude `model:` key exists **only** in the rendered Claude

package/docs/contracts/namespace.md

@@ -11,7 +11,7 @@ stability: stable
 >
 > **Source:** Step-11 Phase 5 Step 1
 > (`step-11-ruflo-parity.md`).
-> **Enforcer:** [`scripts/lint_namespace.py`](../../scripts/lint_namespace.py),
+> **Enforcer:** [`scripts/lint_namespace.py`](../../src/scripts/lint_namespace.py),
 > wired into `task lint-skills`.
 
 ## 1. Shape

package/docs/contracts/orchestration-dsl-v1.md

@@ -128,7 +128,7 @@ no shell-out.
 - `steps[]` length > 32 or < 1
 - `outputs` referencing an unknown step
 
-Exit codes mirror [`lint_hook_manifest.py`](../../scripts/lint_hook_manifest.py): `0` clean, `1` failure, `2` schema-load error.
+Exit codes mirror [`lint_hook_manifest.py`](../../src/scripts/lint_hook_manifest.py): `0` clean, `1` failure, `2` schema-load error.
 
 ## Privacy floor
 
@@ -148,6 +148,6 @@ majors.
 ## Cross-references
 
 - Command surface: [`/orchestrate`](../../.agent-src.uncondensed/commands/orchestrate.md).
-- Linter: [`lint_orchestration_dsl.py`](../../scripts/lint_orchestration_dsl.py).
+- Linter: [`lint_orchestration_dsl.py`](../../src/scripts/lint_orchestration_dsl.py).
 - Runtime dispatcher precedent: [`implement-ticket-flow.md`](implement-ticket-flow.md).
 - Subagent runtime: [`subagent-orchestration`](../../.agent-src.uncondensed/skills/subagent-orchestration/SKILL.md).

package/docs/contracts/package-self-orientation.md

@@ -40,7 +40,7 @@ Bash (install scripts) · Python 3.10+ (linters, condensation, pytest) ·
 Markdown (all content) · Taskfile (`task ci/sync/test`) · GitHub
 Actions (`.github/workflows/`). Non-text inputs (PDF, DOCX, XLSX,
 images, audio) route through the
-[`markitdown`](../../.agent-src/skills/markitdown/SKILL.md) skill.
+[`markitdown`](../../dist/agent-src/skills/markitdown/SKILL.md) skill.
 Wings 2–4 enforce a cognition-only floor (no SaaS auth, no vendor
 SDKs) — `skill_linter.py` enforces it mechanically. Distribution
 mechanics deep-dive: [`agents-md-tech-stack.md`](agents-md-tech-stack.md) (beta).
@@ -50,12 +50,12 @@ mechanics deep-dive: [`agents-md-tech-stack.md`](agents-md-tech-stack.md) (beta)
 | Directory | Purpose | Editable? |
 |---|---|---|
 | `.agent-src.uncondensed/` | Authoring layer — full verbose content | ✅ Yes — edit here |
-| `.agent-src/` | Condensed output — shipped in the package, consumed by agents | ❌ No — regenerated |
-| `.augment/` | Local projection of `.agent-src/` for Augment Code (gitignored) | ❌ No — regenerated |
+| `dist/agent-src/` | Condensed output — shipped in the package, consumed by agents | ❌ No — regenerated |
+| `.augment/` | Local projection of `dist/agent-src/` for Augment Code (gitignored) | ❌ No — regenerated |
 | `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` | Tool-specific projections | ❌ No — regenerated |
 | `agents/` | Package's own roadmaps, contexts, sessions | ✅ Yes |
 
-**Never edit `.agent-src/` or `.augment/` directly.** Edit
+**Never edit `dist/agent-src/` or `.augment/` directly.** Edit
 `.agent-src.uncondensed/` and run `task sync` (or `task ci`) to
 condense + regenerate the tool directories.
 
@@ -73,8 +73,8 @@ condense + regenerate the tool directories.
 docs/guidelines/            (47 guidelines — reference material, not packaged)
 docs/contracts/             (kernel-membership, rule-router, rule-classification, …)
 docs/decisions/             (ADRs — kernel overrides, scope decisions)
-.agent-src/                 ← condensed output shipped in the package
-.agent-src/router.json      ← compiled router manifest (consumed at runtime)
+dist/agent-src/                 ← condensed output shipped in the package
+dist/agent-src/router.json      ← compiled router manifest (consumed at runtime)
 .augment/                   ← local projection for Augment Code (gitignored)
 scripts/                    ← install.sh, install.py, condense.py, linters
 tests/                      ← pytest (324 tests) + test_install.sh
@@ -86,13 +86,13 @@ agents/                     ← this package's own roadmaps / sessions / context
 
 | Rule | File |
 |---|---|
-| `.agent-src/` must stay project-agnostic — no project names, domains, stacks | [`augment-portability`](../../.agent-src/rules/augment-portability.md) |
-| Root AGENTS.md + copilot-instructions.md must stay project-agnostic too | [`augment-portability`](../../.agent-src/rules/augment-portability.md) |
-| Edit `.agent-src.uncondensed/`, never `.agent-src/` or `.augment/` | [`augment-source-of-truth`](../../.agent-src/rules/augment-source-of-truth.md) |
-| Skills must declare frontmatter, be self-contained, pass the linter | [`skill-quality`](../../.agent-src/rules/skill-quality.md) |
-| Size budgets for skills, rules, commands | [`size-enforcement`](../../.agent-src/rules/size-enforcement.md) |
-| Keep `.agent-src/` / `agents/` cross-refs in sync on add/rename/delete | [`docs-sync`](../../.agent-src/rules/docs-sync.md) |
-| Creating a new skill/rule/command/guideline runs Understand → Research → Draft | [`artifact-drafting-protocol`](../../.agent-src/rules/artifact-drafting-protocol.md) |
+| `dist/agent-src/` must stay project-agnostic — no project names, domains, stacks | [`augment-portability`](../../dist/agent-src/rules/augment-portability.md) |
+| Root AGENTS.md + copilot-instructions.md must stay project-agnostic too | [`augment-portability`](../../dist/agent-src/rules/augment-portability.md) |
+| Edit `.agent-src.uncondensed/`, never `dist/agent-src/` or `.augment/` | [`source-of-truth`](../../dist/agent-src/rules/source-of-truth.md) |
+| Skills must declare frontmatter, be self-contained, pass the linter | [`skill-quality`](../../dist/agent-src/rules/skill-quality.md) |
+| Size budgets for skills, rules, commands | [`size-enforcement`](../../dist/agent-src/rules/size-enforcement.md) |
+| Keep `dist/agent-src/` / `agents/` cross-refs in sync on add/rename/delete | [`docs-sync`](../../dist/agent-src/rules/docs-sync.md) |
+| Creating a new skill/rule/command/guideline runs Understand → Research → Draft | [`artifact-drafting-protocol`](../../dist/agent-src/rules/artifact-drafting-protocol.md) |
 
 ## Maintainer telemetry (opt-in)
 
@@ -101,14 +101,14 @@ Default-off. `telemetry.artifact_engagement.enabled: true` in
 floor + pipeline:
 [`artifact-engagement-flow.md`](../../.agent-src.uncondensed/contexts/contracts/artifact-engagement-flow.md)
 (beta). Rule:
-[`artifact-engagement-recording`](../../.agent-src/rules/artifact-engagement-recording.md).
+[`artifact-engagement-recording`](../../dist/agent-src/rules/artifact-engagement-recording.md).
 
 ## Context-aware command suggestion
 
 When a free-form prompt matches a command's purpose, the agent
 surfaces matches as numbered options with a "run as-is" escape;
 **nothing auto-executes**. Engine: `scripts/command_suggester/`.
-Rule: [`command-suggestion-policy`](../../.agent-src/rules/command-suggestion-policy.md).
+Rule: [`command-suggestion-policy`](../../dist/agent-src/rules/command-suggestion-policy.md).
 Eligibility + scoring + hardening:
 [`adr-command-suggestion.md`](adr-command-suggestion.md) and
 [`command-suggestion-flow.md`](../../.agent-src.uncondensed/contexts/contracts/command-suggestion-flow.md)
@@ -116,7 +116,7 @@ Eligibility + scoring + hardening:
 
 ## Multi-agent tool support
 
-`task generate-tools` projects `.agent-src/` into Augment Code, Claude
+`task generate-tools` projects `dist/agent-src/` into Augment Code, Claude
 Code (Agent Skills standard), Cursor, Cline, Windsurf, Gemini CLI,
 and Claude.ai cloud bundles. Skills follow
 [agentskills.io](https://agentskills.io); commands are converted to
@@ -127,7 +127,7 @@ layout + cloud-bundle pipeline:
 ## Contributing
 
 1. Edit inside `.agent-src.uncondensed/` or `scripts/` or `tests/` —
-   never in `.agent-src/`, `.augment/`, `.claude/`, `.cursor/`, etc.
+   never in `dist/agent-src/`, `.augment/`, `.claude/`, `.cursor/`, etc.
 2. Run `task ci` locally. It must exit 0.
 3. Commit in logical chunks with Conventional Commits.
 4. Open a PR against `main`.

package/docs/contracts/pilot/language-and-tone.md

@@ -56,7 +56,7 @@ Examples + wrong-vs-correct: [`language-and-tone-examples`](../../docs/guideline
 
 ## `.md` files — ALWAYS English
 
-Every text inside `.md` under `.augment/`, `.agent-src/`, `.agent-src.uncondensed/`, `agents/`: headings, paragraphs, bullets, option labels, prompts, placeholders, ASCII labels, table headers / content. Agent translates at runtime.
+Every text inside `.md` under `.augment/`, `dist/agent-src/`, `.agent-src.uncondensed/`, `agents/`: headings, paragraphs, bullets, option labels, prompts, placeholders, ASCII labels, table headers / content. Agent translates at runtime.
 
 **Labeled-anchor exception** — quoting German inside English prose is forbidden. Either translate, OR use a labeled `DE: … · EN: …` anchor block (only allowed location for German prose).
 

package/docs/contracts/plain-language-surface.md

@@ -62,7 +62,7 @@ them.
 
 The matrix MUST NOT apply to:
 
-- `.agent-src.uncondensed/`, `.agent-src/`, `.augment/`, `.claude/`,
+- `.agent-src.uncondensed/`, `dist/agent-src/`, `.augment/`, `.claude/`,
   `.cursor/`, `.windsurf/`, `.clinerules/` — all skill / rule /
   command / persona artefacts.
 - `docs/contracts/`, `docs/decisions/`, `docs/architecture.md`,
@@ -113,5 +113,5 @@ Re-audit on each of:
 
 - [`docs/getting-started-by-role.md`](../getting-started-by-role.md) — the entry surface.
 - [`docs/contracts/role-experience.md`](role-experience.md) — role artefact shape.
-- [`scripts/lint_role_experiences.py`](../../scripts/lint_role_experiences.py) — lint enforcement.
+- [`scripts/lint_role_experiences.py`](../../src/scripts/lint_role_experiences.py) — lint enforcement.
 - `road-to-frictionless-employee-workspace.md` § Phase C — the roadmap step.