@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/migrate-command.md

@@ -1,233 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-09-04
----
-
-# `agent-config migrate` — Behavior Contract
-
-> **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`
-> command and codifies the **deletion-over-migration** policy: the
-> wizard recreates fresh project config, so legacy project-local state
-> is hard-deleted rather than preserved or relocated.
-
-## Design intent
-
-One opinionated command runs every cleanup step end-to-end. No flag
-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:
-
-- **One mental model.** The legacy split forced the user to remember
-  which slice each command performed. A single opinionated command
-  removes that cognitive load.
-- **Deletion over preservation.** The new wizard
-  (`agent-config setup`) recreates fresh project / global config on
-  next run. Preserving stale `.agent-settings.yml` only carries
-  forward old values the user already chose to leave behind.
-- **No setup-migration.** Project-local config is deleted; global
-  config is recreated fresh by the wizard. Different paths into the
-  same end state, but the deletion path requires no decisions from
-  the agent at migrate time.
-
-## Input signals — what counts as "needs migration"
-
-The command considers a consumer repo migratable when **any** of
-these are detected. The full set is the disjunction below; any one
-hit triggers the apply path.
-
-| # | Signal | Source |
-|---|---|---|
-| 1 | `@event4u/agent-config` entry in `package.json` `dependencies` or `devDependencies` | npm install era |
-| 2 | `event4u/agent-config` entry in `composer.json` `require` or `require-dev` | Composer install era |
-| 3 | Managed symlink (`.augment`, `.claude`, `.cursor`, `.clinerules`, `.windsurfrules`) pointing into `vendor/` or `node_modules/` | composer / npm install layout |
-| 4 | `.implement-ticket-state.json` file present at project root (v0 work-engine state) | pre-v1 engine schema |
-| 5 | `.agent-settings.yml` at project root (legacy project-local config) | pre-global-only consumer surface |
-| 6 | `.agent-user.yml` at project root (legacy project-local user prefs) | pre-global-only consumer surface |
-| 7 | `settings/.agent-settings.yml` or `settings/.agent-user.yml` (typed-subdir variant) | pre-global-only typed-subdir layout |
-| 8 | Empty `agent-config/` shell directory at project root | leftover from removed `composer/npm` install |
-
-The detector returns "already migrated" (exit 0, no writes) when
-none of the signals fire.
-
-## Output state — what the consumer looks like post-migration
-
-After `./agent-config migrate` (real apply) returns 0, the consumer
-repo carries **none** of these:
-
-- ❌ `@event4u/agent-config` in `package.json` (`dependencies` or
-  `devDependencies`); the section is removed if it becomes empty.
-- ❌ `event4u/agent-config` in `composer.json` (`require` or
-  `require-dev`); the section is removed if it becomes empty.
-- ❌ Managed symlinks pointing into `vendor/` or `node_modules/`.
-- ❌ `.implement-ticket-state.json` at the project root; if v0
-  payload was present, it is migrated to `.work-state.json` and the
-  v0 source is renamed `.implement-ticket-state.json.bak`. If no v0
-  payload existed (file absent), nothing is written.
-- ❌ Project-root `.agent-settings.yml` (hard-deleted).
-- ❌ Project-root `.agent-user.yml` (hard-deleted).
-- ❌ `settings/.agent-settings.yml` and `settings/.agent-user.yml`
-  (hard-deleted; the `settings/` directory is removed if it becomes
-  empty).
-- ❌ Empty `agent-config/` shell at the project root.
-
-The `.gitignore` block is refreshed to the canonical shape
-documented in `scripts/_cli/cmd_migrate.py::GITIGNORE_NEW_BODY`.
-
-## Action order — opinionated, fixed
-
-Apply path is deterministic — re-running the same input yields the
-same diff. Order is foundation-first so that earlier steps cannot
-break detection for later ones:
-
-1. **Detect** legacy signals from the matrix above; collect every
-   action that would fire.
-2. **Strip** `composer.json` / `package.json` package entries
-   in-place (preserves sibling keys + 2-space indent + trailing
-   newline).
-3. **Purge** managed symlinks whose target points into `vendor/` or
-   `node_modules/`. User-managed symlinks pointing elsewhere are
-   preserved with a warning.
-4. **Migrate state** — if `.implement-ticket-state.json` carries a
-   v0 payload, rewrite to `.work-state.json` and rename the v0
-   source to `.implement-ticket-state.json.bak`. If the file is
-   absent or already v1-shaped, skip.
-5. **Hard-delete** legacy project-local config files:
-   - `.agent-settings.yml` (project root)
-   - `.agent-user.yml` (project root)
-   - `settings/.agent-settings.yml` (typed-subdir variant)
-   - `settings/.agent-user.yml` (typed-subdir variant)
-   - `settings/` directory itself if empty after the YAML removals.
-6. **Remove** the empty `agent-config/` shell directory at the
-   project root, if present and empty.
-7. **Refresh** the `.gitignore` agent-config managed block to the
-   canonical shape.
-8. **Summarize** — print every action taken, one per line, with a
-   leading bullet.
-
-## `--dry-run` semantics
-
-- Same detection + summary as the apply path.
-- **Zero filesystem mutations** — no file created, modified, or
-  deleted; no symlink removed; no directory removed.
-- Exit codes match the apply path: `0` for "nothing to migrate"
-  and `0` for "would migrate these N actions".
-- Non-zero only on detection errors (unreadable file, invalid JSON
-  in `composer.json` / `package.json`, etc.).
-- 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:
-
-1. Detector fires zero hits (every signal in the matrix is absent).
-2. Command prints `✅  already migrated — nothing to do.`
-3. Exits `0`.
-4. **No filesystem mutation occurs** — including on `--dry-run`.
-
-A partial migration (e.g., a previous run crashed between steps 3
-and 4) re-runs each remaining step on the next invocation. The
-apply order is chosen so partial state never poisons detection of
-the next pending action.
-
-## Excluded — what `migrate` does NOT do
-
-These cleanup actions exist elsewhere in the package today but are
-intentionally **outside** the unified `migrate` command:
-
-| Action | Where it lives instead | Why excluded |
-|---|---|---|
-| Lift project-local YAML into `~/.event4u/agent-config/` | wizard (`agent-config setup`) | New global config is created fresh by the wizard; preserving stale values defeats the deletion-over-migration policy. |
-| Write a fresh `.agent-settings.yml` | wizard (`agent-config setup`) | Same as above — the wizard is the source of truth for new project config. |
-| Run the perms gate (`lint_global_paths.py`) | `agent-config doctor` | Migration deletes project-local state; the perms audit is a separate diagnostic on the global tree. |
-| `.legacy-pre-global-only/<stamp>/` snapshot | (removed) | Snapshot-and-rollback was a `migrate-to-global` semantic. The deletion path needs no snapshot — git history is the rollback surface. |
-| `agents/.event4u-bridge.yml` legacy marker removal | `install.py` | Marker is retired (ADR-020 amendment 2026-07-13); install now deletes any legacy leftover instead of writing it. Global root resolves from `~/.event4u/agent-config`. |
-| `settings:migrate` (read-only copy of project YAML into global) | (removed; superseded by wizard) | The read-only copy was a stepping stone for the destructive move. With the deletion policy, neither step survives. |
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| `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` | `--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
-even if a sibling step's predicate is already satisfied.
-
-## Test surface
-
-`tests/migrate/test_unified_migrate.py` covers, against a fixture
-consumer dir under `tests/fixtures/migrate/`:
-
-- **Full apply** — fixture carries every input signal; assert each
-  output-state predicate holds post-run; summary lists each action.
-- **`--dry-run`** — same fixture, assert zero filesystem mutations
-  (snapshot dir tree before and after; bit-identical).
-- **Idempotency** — run twice; assert second run is the
-  "already migrated" no-op.
-
-## Rollback
-
-Restoring the previous command surface:
-
-1. Restore the previous `scripts/_cli/cmd_migrate.py` from git
-   history.
-2. Restore `scripts/_cli/cmd_migrate_to_global.py`,
-   `cmd_migrate_state()` / `cmd_migrate_to_global()` in
-   `scripts/_dispatch.bash`, and the corresponding registry entries
-   in `src/cli/registry.ts`.
-3. Delete this contract doc.
-4. Restore `scripts/_cli/cmd_settings_migrate.py` if also removed
-   (note: this command was originally cited only as a discussion
-   item in Phase 1 cross-check; see "Excluded" table above).
-
-## See also
-
-- `road-to-one-migrate-command.md` — the roadmap this contract
-  realizes.
-- `road-to-global-only-install.md` — the predecessor roadmap that
-  shipped `migrate-to-global`; superseded by this contract.
-- `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.
-- `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

@@ -1,134 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-13
----
-
-# Multi-Tool Projection Fidelity Contract
-
-**Status:** beta · **Phase 4 of the `step-1-v2-feedback-followup`
-roadmap** (under `agents/roadmaps/`).
-
-Names the **per-tool guarantees** the projection pipeline (`scripts/condense.py --sync` + `scripts/condense.py --generate-tools`) actually delivers. Byte-equivalence is not behaviour-fidelity — each consumer tool has its own frontmatter grammar, its own activation model, and its own surface for skills / rules / commands.
-
-## Source of truth
-
-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 → `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 |
-| **Cline** | `.clinerules/*.md` | **not projected** | **not projected** | full router frontmatter preserved (`type`, `tier`, `description`, `triggers`, `routes_to`) |
-| **Gemini** | `GEMINI.md` (single-file digest) | embedded inline | embedded inline | digest only — no per-rule frontmatter |
-| **Copilot** | `AGENTS.md` / `copilot-instructions.md` | embedded inline | embedded inline | digest only |
-
-`AGENTS.md` is the **tool-agnostic root pointer** and exists at workspace root regardless of which projections are enabled.
-
-## Fidelity guarantees per axis
-
-### 1. Rule body fidelity
-
-| Tool | Body identical to source? |
-|---|---|
-| Augment | yes (copy or symlink) |
-| Claude | yes (copy) |
-| Cursor `.mdc` | yes |
-| Cline | yes |
-| Windsurf single-file | concatenated, separator `---` between rules |
-| Windsurf per-rule | yes |
-| Gemini / Copilot digest | summarised — **no fidelity guarantee** |
-
-### 2. Trigger fidelity (`triggers:` keyword / `path_prefix`)
-
-| Tool | `triggers:` preserved? |
-|---|---|
-| Augment, Claude, Cline, Windsurf-per-rule | **yes** — the host LLM sees the trigger set verbatim |
-| Cursor `.mdc` | **no** — Cursor's frontmatter grammar does not honour `triggers:`; activation falls back to `globs:` + `alwaysApply: <bool>` + description match |
-| Windsurf single-file `.windsurfrules` | **no** — concatenated body strips per-rule frontmatter |
-| Gemini, Copilot | **no** — digest format |
-
-**Consequence:** rules that depend on `triggers:` for activation (tier-2a path-prefix routing, tier-3 keyword routing) **silently degrade on Cursor and on the Windsurf single-file**. They still appear in body, but the host must infer activation from prose.
-
-### 3. `routes_to:` fidelity
-
-Same matrix as `triggers:` — preserved on Augment, Claude, Cline, Windsurf-per-rule; **dropped** on Cursor `.mdc` and Windsurf single-file.
-
-**Consequence:** the four tier-3 routing rules (`laravel-routing`, `symfony-routing`, `copilot-routing`, `devcontainer-routing`) added in Phase 3.3 will route deterministically on Augment / Claude / Cline; on Cursor / Windsurf-single-file the host must rely on description matching alone.
-
-### 4. Skill surface
-
-Cursor, Windsurf, Cline, Gemini, Copilot have **no native skill surface**. Skills are projected only for Augment and Claude. Consumers on the other tools see skill content only indirectly (via rule bodies that cite skills, or via the catalogue in `AGENTS.md`).
-
-### 5. Command surface
-
-| Tool | Where commands appear |
-|---|---|
-| Augment | `.augment/commands/*.md` (native slash-command surface) |
-| Claude | `.claude/skills/<command>/SKILL.md` (commands rendered as skills with `disable-model-invocation: true`) |
-| Cursor | `.cursor/commands/*.md` (106 files) |
-| Windsurf | `.windsurf/workflows/*.md` (106 files) |
-| Cline | none |
-| Gemini, Copilot | listed only inside `AGENTS.md` / `GEMINI.md` digest |
-
-### 6. `model_tier:` fidelity (ADR-035)
-
-The vendor-neutral `model_tier: lite | medium | high | inherit` capability band
-projects differently per tool. The **generator owns the only tier→model mapping**
-(`high → opus`, `medium → sonnet`, `lite → haiku`); no other surface maps a tier
-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 `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
-projection; the portable source and every other tool keep the neutral tier.
-No vendor model name leaves the band abstraction in source. The optional
-orthogonal `context: large` modifier is metadata only — it never changes the
-native `model:`. See ADR-035 and `road-to-model-capability-tiers.md`.
-
-## Automated probe — `task lint-projection-fidelity`
-
-`scripts/probe_projection_fidelity.py` reads `tests/fixtures/projection_fidelity/fixtures.yml` and asserts the per-tool guarantees above against the actual projected trees. The fixture covers five representative artefacts:
-
-| Fixture entry | Tier | Stress-tests |
-|---|---|---|
-| `rule:non-destructive-by-default` | kernel | always-active body fidelity across all five rule surfaces |
-| `rule:laravel-translations` | tier-2a | `path_prefix:` trigger preservation (Cline) vs drop (Cursor) |
-| `rule:laravel-routing` | tier-3 | `routes_to:` preservation (Cline) vs drop (Cursor, Windsurf-single) |
-| `skill:laravel` | skill | Augment + Claude only; rationale for absence on others |
-| `command:commit` | command | per-tool command surface divergence |
-
-Run: `./scripts-run src/scripts/probe_projection_fidelity` — exits non-zero on any divergence. Report at `agents/runtime/reports/projection-fidelity.json`.
-
-## Known divergences (do not file as bugs)
-
-These are **architectural facts**, not regressions. They are documented so installers and consumers know what to expect.
-
-1. **Cursor `.mdc` drops router metadata.** Cursor's third-party rule format only honours `description`, `globs`, `alwaysApply`. Adding `triggers:` or `routes_to:` to a Cursor rule has no effect at activation time. The body still loads when the description matches; the deterministic routing layer does not.
-2. **Windsurf single-file (`.windsurfrules`) strips per-rule frontmatter.** Legacy compatibility surface. The new `.windsurf/rules/*.md` per-rule files preserve the full frontmatter — consumers should prefer those.
-3. **Skills do not project to Cursor / Windsurf / Cline / Gemini / Copilot.** These tools have no native skill loader. Skill content reaches consumers indirectly via rule bodies and the `AGENTS.md` catalogue.
-4. **Augment historically did not load symlinked rules.** Default is to **copy** rules into `.augment/rules/`. Opt into symlinks via `augment.rules_use_symlinks: true` in `.agent-settings.yml`.
-5. **`task generate-tools` does not refresh `.augment/rules/`.** Only `task sync` (== `scripts/condense.py --sync`) copies rules into the Augment tree. Investigators who edit a rule, run only `generate-tools`, and then `ls .augment/rules/` will see stale state.
-
-## Acceptance criteria for this contract
-
-- [x] Fixture under `tests/fixtures/projection_fidelity/`
-- [x] Probe script under `scripts/probe_projection_fidelity.py`
-- [x] Report under `agents/runtime/reports/projection-fidelity.json`
-- [x] Per-tool guarantee table above
-- [x] Known-divergence list above
-
-## Related
-
-- [`source-projection`](../architecture/source-projection.md) — pipeline A (source condensation)
-- [`augment-projection`](../architecture/augment-projection.md) — pipeline B (Augment-specific)
-- [`multi-tool-projection`](../architecture/multi-tool-projection.md) — pipeline C (the per-tool emitters)
-- [`rule-router`](rule-router.md) — the `triggers:` / `routes_to:` grammar this contract pins
-- [`agents/runtime/council/sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md`](../../agents/runtime/council/sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md) — origin council feedback <!-- council-ref-allowed: contract origin trace -->

package/docs/contracts/namespace.md

@@ -1,125 +0,0 @@
----
-stability: stable
----
-
-# Namespace contract — skills, rules, commands, personas
-
-> Every artefact name is a **stable identifier**: routed to from
-> `dist/router.json`, cited from skills, surfaced in `/help`, embedded
-> in command paths, and back-referenced in test fixtures. Drift breaks
-> all five surfaces silently.
->
-> **Source:** Step-11 Phase 5 Step 1
-> (an internal parity roadmap (local-only)).
-> **Enforcer:** [`scripts/lint_namespace.py`](../../src/scripts/lint_namespace.py),
-> wired into `task lint-skills`.
-
-## 1. Shape
-
-```
-<stem>-<intent>    kebab-case, ASCII, lowercase
-```
-
-| Component | Rule |
-|---|---|
-| Charset | `[a-z0-9-]+` only |
-| Separator | single `-` between tokens; never `_`, `.`, or camelCase |
-| Length | skills: 3 ≤ name ≤ 64 · rules / commands / personas: 2 ≤ name ≤ 64 (two-letter slot reserved for intentional acronyms — `pr`, `ci`, `qa`, `me`) |
-| First char | `[a-z]` (digits and `-` forbidden at start) |
-| Last char | `[a-z0-9]` (trailing `-` forbidden) |
-| Run | no consecutive `--` |
-
-The `<stem>` carries the **subject** (`commit`, `eloquent`,
-`livewire`); the `<intent>` (optional) carries the **verb / lens**
-(`-writing`, `-architect`, `-routing`). Single-token names are
-permitted when the stem already encodes both (`commit`, `eloquent`,
-`docker`).
-
-## 2. Reserved names — forbidden as artefact names
-
-| Name | Reason |
-|---|---|
-| `pattern` | Reserved for trigger-pattern fixtures (see `tests/fixtures/triggers/`). |
-| `claude-memories` | Reserved for the `~/.claude/CLAUDE.md` shape — host-agent state, not a package artefact. |
-| `default` | Ambiguous with profile / mode defaults; collides with `.agent-settings.yml` keys. |
-| `index` | Reserved for auto-generated INDEX.md files. |
-| `router` | Reserved for `dist/router.json` and the router contract. |
-
-Reserved names apply at the **top level** of each artefact type. A
-sub-verb under a namespaced group (e.g. `council/default.md` →
-`/council:default`) is **not** a top-level identifier — the group
-prefix disambiguates it, and reserved-name enforcement is skipped
-for sub-verbs by the linter. A future artefact `pattern-foo` at the
-top level is fine; bare `pattern` is not.
-
-`README.md` and `INDEX.md` are documentation, not artefacts, and are
-skipped by the linter.
-
-## 3. Per-type conventions
-
-| Type | Source path | Naming nuance |
-|---|---|---|
-| Skill | `.agent-src.uncondensed/skills/<name>/SKILL.md` | Directory name == frontmatter `name`. |
-| Rule | `.agent-src.uncondensed/rules/<name>.md` | Filename stem == frontmatter `id` (when present). |
-| Command | `.agent-src.uncondensed/commands/<name>.md` or `<group>/<verb>.md` | Slash-command invocation `<name>` or `<group>:<verb>`. |
-| Persona | `.agent-src.uncondensed/personas/<name>.md` | Cited from skill frontmatter `personas:` list. |
-
-Sub-namespacing (`commit/in-chunks.md` →  `/commit:in-chunks`) uses
-the same charset rules per segment; the joining colon is implicit.
-
-## 4. Linter — `scripts/lint_namespace.py`
-
-Walks the four source roots above, asserts each artefact name:
-
-1. Matches the regex `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`.
-2. Length 3 ≤ name ≤ 64.
-3. Not in the reserved-names list.
-4. Skill: directory name matches frontmatter `name`.
-
-Exit codes:
-
-| Exit | Meaning |
-|---|---|
-| `0` | All names valid. |
-| `1` | At least one name fails a rule. |
-| `2` | Linter crashed (filesystem error, malformed frontmatter). |
-
-Diagnostic format: one issue per line — `<path>: <rule> — <detail>`.
-
-## 5. Adding a new artefact
-
-Pick the name; verify locally:
-
-```bash
-./scripts-run src/scripts/lint_namespace --name <candidate>
-# or full run:
-./scripts-run src/scripts/lint_namespace
-```
-
-If the candidate fails, the linter prints the rule it violated.
-**Renames after release are expensive** — touch `dist/router.json`,
-every skill citing the old name, the bench corpus, and consumer settings.
-Pay the naming cost once, upfront.
-
-## 6. Relationship to the frontmatter contract
-
-The **shape** lives here. The **frontmatter keys** that carry the
-name (`name:` in skills, `id:` in rules) live in
-[`frontmatter-contract.md`](../../agents/reference/docs/frontmatter-contract.md).
-Both contracts share the regex; this file is the source of truth for
-the regex string.
-
-## 7. Why this exists
-
-`dist/router.json` resolves `<kind>:<id>` strings at session start. Any
-artefact rename breaks every routing entry pointing at the old name
-without compile-time error. The linter catches the rename at the PR
-boundary, not at runtime in a consumer.
-
-## 8. Out of scope
-
-- File-system case sensitivity (we rely on lowercase-only names).
-- Cross-tool aliases (Augment / Claude / Cursor all consume the same
-  name — projection is by content, not by alias).
-- Versioning suffixes (`-v2`, `-legacy`). Use `status: superseded`
-  in frontmatter instead; never rename in place.

package/docs/contracts/no-runtime-boundary.md

@@ -1,61 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-17
----
-
-# No-Runtime Boundary Contract
-
-> **Audience:** Every Mission-Mode decision, skill author, and recipe reviewer.
-> Read this before asking "is X allowed in a mission step?"
-
-AC is a **file-first, no-runtime suite** — skills and missions emit text and
-files; they do not spawn processes, own state stores, or poll the environment.
-This contract makes that boundary explicit for the Mission-Mode layer.
-
-See also: `lethal-trifecta-guard` (no private-data + untrusted-content +
-external-comms in one autonomous path), and the internal agent-memory sunset
-decision (cross-session persistent stores rejected as architecturally unsound
-and violating the no-runtime principle).
-
----
-
-## Allowed
-
-| Category | Examples | Notes |
-|---|---|---|
-| **Codegen / file emit** | Write a migration file, emit a `UPGRADE.md` plan, produce a diff patch | The canonical mission output |
-| **File I/O** | Read `composer.json`, write `.work-state.json`, append to a report | Single-invocation scope only |
-| **Multi-turn prompting** | Agent asks user to run `php artisan migrate`, user pastes result back | Human stays in the loop; agent interprets the pasted output |
-| **git-as-state** | `git commit -m "mission:upgrade step=11 status=ok"`, `git revert HEAD`, `git reset --soft HEAD~1` | AC shells out to git constantly — structured commit messages are logging, not a daemon; rollback is `git revert` / branch reset on a provisional `mission/…` branch |
-| **Shell invocation (single-shot)** | `composer install`, `php artisan test --filter=…` run once per step and their output piped back | One-shot, result returned immediately; never a background job |
-| **Report / plan files** | Write `agents/evidence/mission-upgrade-decision.md`, emit a breaking-change checklist | Authoring-time output, not a runtime artifact |
-
----
-
-## Prohibited
-
-| Category | Why |
-|---|---|
-| **Background processes / daemons** | No spawned subprocesses that outlive the current agent turn |
-| **Cross-session persistent state stores** | No SQLite, pgvector, MCP memory servers, Redis, or any store that persists beyond the git working tree — agent-memory layer sunset applies here. **Carve-out (ADR-124 § 6): a gitignored, deterministic, rebuildable build/index artifact under `agents/runtime/state/` is a build output, not a state store** — it carries no authority, is reproducible from the working tree, and is never auto-written memory. State-store test: if deleting the artifact changes *what* the tool can answer rather than only *how fast* it answers, it is a state store and prohibited (a code-graph cache passes — deletion only slows recompute; a vector/embedding index fails — it enables query semantics absent from source, and stays Class C). |
-| **Event loops / polling** | No `while true; do …; done`, no `inotifywait`, no cron-inside-mission |
-| **Auto-PR / auto-push** | Hard-Floor (`non-destructive-by-default`): missions never push to remote or open PRs autonomously; those gates require explicit user confirmation every turn |
-| **Network egress from mission scripts** | Mission scripts may not initiate outbound HTTP calls; skills that need network access declare `allowed_tools` explicitly and go through the normal lethal-trifecta gate |
-
----
-
-## Gray — requires council review before adopting
-
-| Pattern | Risk | Gate |
-|---|---|---|
-| **Conditional branching on prior step outputs** | Missions could become implicit state machines, defeating the no-runtime constraint | Must be expressed as a skill decision tree with explicit LLM judgment — not a script `if`/`else`; council sign-off required per mission |
-| **File-based state within a single invocation** | `.work-state.json` already exists and may gain a `mission_history` key — that is allowed; adding new control-flow primitives (loops, conditional keys that drive execution) is **not** | Extension of `.work-state.json` for logging is OK; adding execution-control semantics requires a new ADR |
-| **Nested sub-missions** | Could create unbounded depth; Phase 1 PoC must first prove a flat sequence is sufficient | Defer until Phase 1 evidence shows a real need |
-
----
-
-## Decision authority
-
-A mission step that is unclear against this contract goes to the AI Council
-(`./scripts-run src/scripts/council_cli`) before any build work starts.
-The council verdict becomes an ADR if it changes this table.

package/docs/contracts/one-off-script-lifecycle.md

@@ -1,110 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# One-off-script lifecycle
-
-**Purpose.** Pin the naming, location, age, and purge policy for
-**one-off scripts** so the package does not accumulate a graveyard
-under `scripts/`. One-off here means: a script written for a
-specific migration, retrofit, audit, or council run, with no ongoing
-caller and no place in the durable Taskfile.
-
-**Scope.** Defines the file pattern, the directory, the maximum age,
-the TTL extension mechanism, and the CI purge gate. Does **not**
-specify the content of any specific one-off — that belongs to the
-script itself or the cleanup-mechanics context.
-
-Last refreshed: 2026-05-04.
-
-## Naming
-
-One-off scripts MUST match this regex:
-
-```
-^_one_off_[a-z0-9-]+\.py$
-```
-
-The `_one_off_` prefix is the load-bearing signal. Files outside
-this prefix are treated as durable scripts and MUST be referenced by
-the Taskfile or by another script.
-
-## Location
-
-```
-scripts/_one_off/<YYYY-MM>/_one_off_<slug>.py
-```
-
-`<YYYY-MM>` is the UTC month the script was first committed. The
-month directory groups one-offs for archival sweeps. Scripts MUST
-NOT live at `scripts/_one_off/_one_off_*.py` (no month) or under
-`scripts/` directly (no `_one_off/`).
-
-## TTL
-
-| State | Action |
-|---|---|
-| Age ≤ 60 days from month-directory date | active, no warning |
-| 60 < Age ≤ 90 days | warning emitted by `lint_one_off_age.py`, no failure |
-| Age > 90 days | `lint_one_off_age.py` fails CI; the script is purged in the next housekeeping pass |
-
-Age = `today − first-of-month(<YYYY-MM>)` in UTC days. The 60-day
-soft floor and 30-day grace window are intentional — they cover one
-release cycle plus a sprint of grace.
-
-## TTL extension
-
-A one-off MAY extend its TTL exactly once, by adding a frontmatter
-block at the top of the script:
-
-```python
-"""
----
-ttl_extended_until: 2026-08-31
-ttl_reason: blocked on PROJ-123 — re-runs after cutover
----
-"""
-```
-
-The linter respects `ttl_extended_until` if it is ≤ 180 days from
-the file's `<YYYY-MM>` directory date. Beyond 180 days, the linter
-hard-fails — no second extension. The intent is: if a "one-off" is
-still live at six months, it is a durable concern and belongs in
-`scripts/` or a Taskfile group.
-
-## Purge mechanism
-
-`lint_one_off_age.py` runs in `task ci`. On a clean working tree, it
-prints purge candidates as a list. Purge itself is a separate human-
-or-CI action — `task purge-one-offs` removes flagged files. The
-linter does not auto-delete.
-
-## Allowed exceptions
-
-Two patterns are exempt from the prefix requirement:
-
-- **Bundler / orchestrator helpers** under `scripts/ai_council/`
-  that exist to support the council CLI — they are not one-offs even
-  though council *runs* are one-offs.
-- **`scripts/_one_off/<YYYY-MM>/README.md`** — a free-form readme is
-  allowed in each month directory documenting why the scripts exist.
-
-Council run scripts that wrap a question and write the response file
-DO live under `scripts/_one_off/<YYYY-MM>/` and DO follow the prefix
-rule.
-
-## Cross-references
-
-- The contract that defines council CLI surface (and so what gets
-  archived as a one-off): the council CLI section of the package's
-  command catalog.
-- The cleanup-mechanics context for housekeeping passes:
-  `agents/settings/contexts/cleanup-mechanics.md`.
-- Linter implementation: `scripts/lint_one_off_age.py`.
-
-## Stability
-
-Beta. Breaking changes (e.g. raising the age cap, changing the
-prefix, or removing TTL extensions) require a minor-version bump and
-a `### Breaking` entry in `CHANGELOG.md`.