@event4u/agent-config 9.8.0 → 9.9.0

package/docs/decisions/ADR-028-root-layout.md

@@ -1,147 +0,0 @@
----
-adr: 028
-status: superseded
-date: 2026-05-25
-decision: root-layout
-supersedes: —
-superseded_by: ADR-045
-phase: v3.x · root-layout-cleanup Phase 1
-type: structural
-review_date: 2027-05-25
----
-
-# ADR-028 — Root layout — targeted prune now, multi-workspace deferred behind four audits
-
-## Status
-
-**Accepted** · 2026-05-25. Encodes the AI Council verdict from
-[`root-cleanup-organizing-principle-2026-05-25.synthesis.md`](../../agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md) <!-- council-ref-allowed: ADR decision trace -->
-and opens
-[`road-to-root-layout-cleanup.md`](../../agents/roadmaps/archive/road-to-root-layout-cleanup.md) (archived; complete).
-Time-boxed: review on **2027-05-25** or earlier if any trigger below fires.
-
-## Context
-
-A request to move "everything not needed at root into `./src/`" failed
-the reality check on three counts:
-
-1. **`./src/` is occupied** — the TypeScript application (CLI · Server · UI · shared) per
-   [`ADR-012`](ADR-012-typescript-cli-shell.md) / [`ADR-016`](ADR-016-installer-architecture.md).
-   Moving general tooling into `./src/` collides with the app boundary.
-2. **`router.json` is not at root** — lives under `./dist/`, governed by
-   [`ADR-019`](ADR-019-router-json-dist-location.md). Out of scope.
-3. **`setup.sh` is the curl entry point** — referenced by external installers
-   (`bash <(curl …setup.sh)`). Discovery surface, immovable.
-
-A council session (2 members, $0.13 actual) reframed the problem:
-
-> "Root noise" is not a *discoverability* problem (GitHub paginates
-> anyway, npm consumers never see it). It is a *maintainability*
-> problem — "where do new internal tools belong?"
-
-With that reframe, the cheap-and-safe move (Option 1 — targeted prune)
-becomes obvious, and the deep restructure (multi-workspace) drops to a
-conditional follow-up gated by evidence the package does not yet have.
-
-### Consumer-contract surface check (Phase 1 scope)
-
-Re-audit of `bench/`, `evals/`, `workers/`, `user-types/` against the
-installer / projector / CI:
-
-| Dir | `scripts/install.py` | `scripts/condense.py` projection | `.github/workflows/*` | Verdict |
-|---|---|---|---|---|
-| `bench/` | — | — | `bench-drift.yml` (path filter) | **movable** |
-| `evals/` | — | — | — | **movable** |
-| `workers/` | — | — | `deploy-mcp-worker.yml` (working-dir, 6+ refs) | **movable** (CI updates only) |
-| `user-types/` | `USER_TYPES_DIR = "user-types"` (line 52) | `AUGMENT_SYMLINK_DIRS` includes `"user-types"` | — | **immovable — public contract** |
-
-`user-types/` is dropped from Phase 1 — installer + projector reference
-it as a stable root path. Surfaced during execution, not in the
-council's original scope (the council recommended all four; the audit
-narrowed it).
-
-## Decision
-
-**Two-phase strategy.** Phase 1 ships now; Phases 2–3 are conditional.
-
-### Phase 1 — Targeted Prune (immediate, ≤ 1 day, no version bump)
-
-Move into a new `./internal/` umbrella:
-
-- `bench/` → `internal/bench/`
-- `evals/` → `internal/evals/`
-- `workers/` → `internal/workers/`
-
-Update:
-
-- `.github/workflows/bench-drift.yml` — path filter.
-- `.github/workflows/deploy-mcp-worker.yml` — `working-directory` + `cache-dependency-path`.
-- `taskfiles/engine.yml`, `taskfiles/mcp.yml` — `dir:` references.
-- `AGENTS.md` — placement rule pointer.
-
-Outcome: 3 fewer root entries; zero consumer risk; precedent for
-"maintainer-internal → `./internal/`".
-
-### Phase 2 — Pre-audits (gates Phase 3, no time-box)
-
-Four audits must complete and pass before Phase 3 opens:
-
-1. **Consumer-contract audit** — GitHub code search +
-   `node_modules/@event4u/agent-config/` path probing for
-   `scripts/`, `templates/`, `config/`, `schemas/` references.
-2. **Symlink-mobility test** — verify Cursor / Claude / Windsurf
-   honor symlinked projections (`.cursor/` → `./projections/.cursor/`).
-3. **Hash-sequencing audit** — confirm `.condensation-hashes.json`
-   uses paths that survive `.agent-src/` relocation (or document the
-   regeneration migration).
-4. **CI-path audit** — every hardcoded path in
-   `.github/workflows/*.yml` and `taskfiles/*.yml`.
-
-Each audit produces a verdict file under
-`agents/evidence/audits/2026-XX-root-layout-phaseN/`.
-
-### Phase 3 — Conditional multi-workspace (deferred, gated)
-
-Only if **all four audits pass**: restructure to npm-workspaces with
-`tooling/` (Python maintainer scripts), `runtime/` (TS app), and
-optionally `projections/` (host-agent configs). If any audit fails,
-Phase 3 closes as "not feasible" and a successor ADR documents the
-blocker.
-
-## Consequences
-
-- New top-level `./internal/` directory becomes the home for
-  maintainer-only tooling. `AGENTS.md` documents this with one line.
-- `.gitignore` and `eslint`/`pyproject` ignore rules updated as
-  needed.
-- The four Phase 2 audits are pre-requirements, not work. They are
-  *not* sprint tasks — they run on demand when someone wants to
-  re-open multi-workspace.
-- Review on **2027-05-25** or earlier if any trigger fires:
-  1. A new maintainer-only dir is added at root (signal: `./internal/`
-     convention is breaking down).
-  2. Phase 2 audits all return clean (signal: Phase 3 is ready).
-  3. A consumer reports breakage from a Phase 1 path change (signal:
-     audit missed a contract).
-  4. Council session re-opens the question with new evidence.
-
-## Alternatives considered
-
-| Option | Why rejected |
-|---|---|
-| Move everything into `./src/` (original request) | `./src/` is the TS app per ADR-012/016. Collision. |
-| Option 2 — `./tooling/` umbrella with `templates/` / `config/` / `schemas/` | Council: cost underestimated (duplicate-then-deprecate + 2-month window + major bump); installer paths in those dirs are unaudited. |
-| Option 3 — full category-coded migration | Council hard-reject: projection mobility unproven; condensation-hash sequencing risk; unshippable without symlink test. |
-| Option 4 — `MAP.md` documentation | Council: adds 51st entry; documentation-as-apology; AGENTS.md already serves this role. |
-| Skip Phase 1, jump to multi-workspace prototype | Loses the cheap visible win; Phase 2 audits unfunded; risks scope creep into Phase 3. |
-
-## References
-
-- [`agents/runtime/council/questions/root-cleanup-organizing-principle-2026-05-25.md`](../../agents/runtime/council/questions/root-cleanup-organizing-principle-2026-05-25.md) — council brief. <!-- council-ref-allowed: ADR decision trace -->
-- [`agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md`](../../agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md) — full synthesis. <!-- council-ref-allowed: ADR decision trace -->
-- [`agents/roadmaps/archive/road-to-root-layout-cleanup.md`](../../agents/roadmaps/archive/road-to-root-layout-cleanup.md) — execution roadmap (archived; Phase 1 ✅, Phase 2 ✅, Phase 3 closed).
-- [`agents/evidence/audits/2026-05-root-layout-phase2/`](../../agents/evidence/audits/2026-05-root-layout-phase2/) — Phase 2 audit verdict bundle.
-- [`ADR-029`](ADR-029-multi-workspace-deferred.md) — Phase 3 close-out (multi-workspace deferred indefinitely).
-- [`ADR-012`](ADR-012-typescript-cli-shell.md), [`ADR-016`](ADR-016-installer-architecture.md) — `./src/` is the TS app.
-- [`ADR-019`](ADR-019-router-json-dist-location.md) — `router.json` lives in `./dist/`.
-- `scripts/install.py:52` (`USER_TYPES_DIR`), `scripts/condense.py:1106` (`AUGMENT_SYMLINK_DIRS`) — evidence pinning `user-types/` to root.

package/docs/decisions/ADR-029-multi-workspace-deferred.md

@@ -1,122 +0,0 @@
----
-adr: 029
-status: accepted
-date: 2026-05-25
-decision: multi-workspace-deferred
-supersedes: —
-superseded_by: —
-phase: v3.x · root-layout-cleanup Phase 3 close-out
-type: structural
-review_date: 2027-05-25
----
-
-# ADR-029 — Multi-workspace restructure deferred; Phase 3 closed pending L0 symlink-mobility evidence
-
-## Status
-
-**Accepted** · 2026-05-25. Successor to
-[`ADR-028`](ADR-028-root-layout.md) Phase 3. Closes the multi-workspace
-restructure (Option 5 from the original council session) as **not
-feasible today**, with a re-open path documented below. Time-boxed:
-review on **2027-05-25** or earlier if any re-open trigger fires.
-
-## Context
-
-[`ADR-028`](ADR-028-root-layout.md) defined a three-phase strategy:
-
-1. **Phase 1** — move `bench/`, `evals/`, `workers/` to `internal/`. **Shipped.**
-2. **Phase 2** — run four pre-audits that gate Phase 3.
-3. **Phase 3** — conditional multi-workspace restructure
-   (`tooling/` · `runtime/` · `projections/`), only if all four
-   Phase 2 audits return clean.
-
-Phase 2 ran in the same PR as Phase 1 (under maintainer mandate).
-Verdict bundle:
-[`agents/evidence/audits/2026-05-root-layout-phase2/`](../../agents/evidence/audits/2026-05-root-layout-phase2/).
-
-| # | Audit | Verdict |
-|---|---|---|
-| 1 | Consumer-contract | ✅ Pass — published surface enumerated |
-| 2 | Symlink-mobility | ⚠️ Partial — subdirectory symlinks proven, top-level untested |
-| 3 | Hash-sequencing | ✅ Pass — source-relative keys, idempotent regeneration |
-| 4 | CI-path inventory | ✅ Pass — ~27 edit points enumerated |
-
-Audit 2 is the blocker. The multi-workspace option requires
-**L0 symlinks** (tool root directory itself becomes a symlink, e.g.
-`.cursor/ → projections/.cursor/`). The package today only proves
-**L1 symlinks** (subdirectory level, e.g. `.augment/skills/ →
-../.agent-src/skills/`). L0 has never been tested against current
-Cursor, Claude Code, or Windsurf builds — and one of those three
-(Augment Code) is already known to refuse symlinked rule files at L1,
-which is the precedent that motivates the audit in the first place.
-
-Without L0 evidence, executing Phase 3 would either ship a broken
-projection for at least one host agent or force a fallback to
-per-directory copies that defeat the "single source of truth" win the
-multi-workspace shape is meant to deliver.
-
-## Decision
-
-**Defer Phase 3 indefinitely.** Close the Phase 3 roadmap step as "not
-feasible today". Keep the audit bundle as the canonical evidence base
-so that a future maintainer can re-open the question without redoing
-the work.
-
-The four root-layout claims survive Phase 1 unchanged:
-
-- `bench/`, `evals/`, `workers/` are gone from root (under `internal/`).
-- `user-types/` stays at root (immovable per Audit 1 + ADR-028).
-- Top-level tool roots (`.augment/`, `.cursor/`, `.claude/`, `.clinerules/`)
-  stay as real directories with L1 symlinks pointing at `.agent-src/`.
-- The "maintainer-internal → `./internal/`" precedent is the new
-  placement rule for new internal dirs (already in `AGENTS.md`).
-
-## Re-open conditions
-
-Phase 3 becomes eligible when **all** of these hold:
-
-1. A maintainer (or community contributor) runs the L0 symlink test
-   documented in
-   [`02-symlink-mobility.md`](../../agents/evidence/audits/2026-05-root-layout-phase2/02-symlink-mobility.md)
-   against current Cursor + Claude Code + Windsurf, captures the
-   result, and amends Audit 2 to ✅ or ❌.
-2. If Audit 2 lands ✅: the ~27 CI-path edit points from Audit 4 are
-   accepted as in-scope for the migration window; no new hardcoded
-   paths added in the interim invalidate the inventory.
-3. A council session synthesizes the updated verdict bundle and
-   produces a fresh recommendation (multi-workspace vs. stay-as-is).
-4. The maintainer accepts the deprecation cycle cost (installer
-   version bump + dual-write window for the projection contract).
-
-## Consequences
-
-- The root layout stabilizes at the Phase 1 shape for ≥ 1 year (the
-  `2027-05-25` review date).
-- New maintainer-internal directories go under `internal/`. New
-  tooling that needs to ship to consumers goes under `scripts/`,
-  `config/`, or a new top-level entry that earns its own ADR.
-- The `projections/` umbrella idea is **not dead** — it is gated on
-  fresh L0 evidence, not on a new design decision.
-- The four audit files are reusable: Audit 1 (consumer surface),
-  Audit 3 (hash portability), and Audit 4 (CI path inventory) remain
-  valid until a structural change invalidates them; only Audit 2
-  needs runtime re-verification.
-
-## Alternatives considered
-
-| Option | Why rejected |
-|---|---|
-| Execute Phase 3 anyway with L0 untested | Ships projection breakage to one of three host agents in the worst case; the win (single source of truth) collapses if any agent forces a fallback to copies. |
-| Run the L0 test in CI | The L0 test requires the host agent's runtime (Cursor / Claude Code IDE plugins); CI cannot exercise it. |
-| Defer **all** of Phase 3 to a separate roadmap | Phase 2 already produced the audit bundle; closing Phase 3 with an ADR captures the verdict without leaving a stale roadmap open. |
-| Re-shape Phase 3 as L1-only | The council's recommendation specifically called out the `projections/` umbrella, which requires L0. Re-shaping to L1-only is a different decision the council did not weigh; would need a fresh council session. |
-
-## References
-
-- [`ADR-028`](ADR-028-root-layout.md) — parent decision.
-- [`agents/evidence/audits/2026-05-root-layout-phase2/`](../../agents/evidence/audits/2026-05-root-layout-phase2/) —
-  full audit bundle (4 verdict files + README).
-- [`agents/roadmaps/archive/road-to-root-layout-cleanup.md`](../../agents/roadmaps/archive/road-to-root-layout-cleanup.md) —
-  execution roadmap, archived (Phase 1 ✅, Phase 2 ✅, Phase 3 closed via this ADR).
-- [`agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md`](../../agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md) <!-- council-ref-allowed: ADR decision trace -->
-  — original council synthesis that proposed the multi-workspace shape.

package/docs/decisions/ADR-030-claude-code-command-projection.md

@@ -1,147 +0,0 @@
----
-adr: 030
-status: accepted
-date: 2026-05-28
-decision: claude-code-command-projection
-supersedes: —
-superseded_by: —
-phase: road-to-claude-code-global-distribution Phase 3
-type: structural
-review_date: 2026-06-11
----
-
-# ADR-030 — Claude Code command-projection strategy: native slash-only
-
-## Status
-
-**Accepted** · 2026-05-28. Three conditions enumerated below; all three
-verified empirically in the same session, so the decision lands
-**without** soak. The 14-day kill-switch keeps the revert path one
-commit away; review date 2026-06-11 closes the window.
-
-## Context
-
-The package ships commands as `.agent-src/commands/<cluster>/<sub>.md`
-(canonical source) and projects them per-tool through
-`scripts/condense.py`. Pre-2026-05-28 the Claude Code projection was a
-single path: `generate_claude_commands` rewrote each command into
-`.claude/skills/<flat-slug>/SKILL.md` with
-`disable-model-invocation: true` in the source frontmatter.
-
-The 2026-05-28 diagnostic surfaced the failure mode:
-
-- `.claude/commands/` was never populated — commands carried no
-  filesystem channel into Claude Code's native slash router.
-- The skills-projection target was filtered out of the
-  model-invokable skill list (`disable-model-invocation: true`).
-- `_CLAUDE_SKILL_BUNDLE` shipped `rules` / `skills` / `personas` but
-  **no** `commands` subtree.
-
-Net result: Claude Code received zero command surface from the package
-outside the cwd-local repo install. Augment Code and Cursor bundles
-already shipped `commands/`; Claude Code was the outlier.
-
-## Decision
-
-Adopt **Option B (native slash-only)**:
-
-1. Ship `.agent-src/commands/` directly into Claude Code's native
-   slash-command surface at `~/.claude/commands/` via the global
-   deploy bundle (`_CLAUDE_SKILL_BUNDLE` in `scripts/install.py` and
-   its TypeScript mirror in `src/install/wizard-plan.ts`).
-   Subdirectory layout maps 1:1 to the `/<cluster>:<sub>` namespace
-   per Claude Code's filesystem-channel convention. No separate
-   `condense.py` projector — the source tree already follows the
-   target layout, so the global-install copy is the projection.
-2. Keep `condense.py::generate_claude_commands` (skills-list
-   projection at `.claude/skills/`) unchanged **for now** —
-   backwards compat for any consumer already discovering commands
-   via `.claude/skills/`. Retirement deferred to a separate roadmap
-   if needed.
-
-Rejected alternatives:
-
-- **Option A — dual projection (slash + skills, both active).**
-  Conservative, but doubles maintenance surface and keeps the
-  filter-out-of-skill-list semantics. Verdict: only useful if Option B
-  fails the kill-switch window.
-- **Option C — commands_unsupported (no Claude Code command
-  surface).** Eliminates the bug class by removing the feature.
-  Verdict: regression in product surface; Claude Code consumers lose
-  parity with Augment / Cursor.
-
-### Council convergence
-
-Session 2026-05-28, design mode, 2 rounds, $0.06 actual.
-Members: `claude-sonnet-4-5` + `gpt-4o`. Both converged on Option B,
-CONDITIONAL on the three verifications below. Responses captured at
-`agents/runtime/council/responses/claude-code-distribution.json`. <!-- council-ref-allowed: ADR decision trace -->
-
-### Three conditions (all verified 2026-05-28)
-
-1. **Plugin loader reads `.claude/commands/` for globally-installed
-   plugins (not just cwd-local).**
-   Verified empirically: `~/.claude/commands/probe/sub.md` →
-   `/probe:sub` routed successfully via
-   `echo '' | claude --print "/probe:sub"`. Native filesystem channel
-   works for user-scope at top-level AND in subdirectories.
-2. **Command parser tolerates `disable-model-invocation: true` in
-   frontmatter (or strip during projection).**
-   Verified empirically: probe command carrying the package's full
-   rich frontmatter routed successfully. Subtle behaviour:
-   `disable-model-invocation: true` hides the command from `/help`
-   listing but keeps it slash-invokable when typed directly — the
-   desired UX for heavyweight commands. No frontmatter-strip step
-   required.
-3. **Kill-switch defined: if native slash doesn't resolve in
-   production within 14 days, fall back to dual-projection with
-   deprecation timeline.**
-   The kill-switch is the inverse of Phase 4 Step 1 — remove
-   `(".agent-src/commands", "commands")` from `_CLAUDE_SKILL_BUNDLE`
-   in `scripts/install.py` and `src/install/wizard-plan.ts`. One-line
-   revert per file. Tracked by review date 2026-06-11.
-
-## Consequences
-
-**Positive:**
-
-- `~/.claude/commands/<cluster>/<sub>.md` lands the package's full
-  command surface natively in Claude Code, matching Augment and
-  Cursor parity.
-- `disable-model-invocation: true` semantics preserved — heavyweight
-  commands stay invokable but hidden from auto-complete, the intended
-  UX.
-- No frontmatter mangling — the source command file is the artifact
-  that ships, no projection transform needed.
-
-**Negative / accepted:**
-
-- Two projection paths coexist (`.claude/commands/` for slash routing
-  + `.claude/skills/` for the legacy skills-projection list). Cost is
-  one extra subtree per install; benefit is no consumer-breaking
-  during the 14-day kill-switch window. Retirement of the skills
-  projection is a separate decision.
-- Frontmatter shipped to Claude Code carries package-internal fields
-  (`tier`, `cluster`, `sub`, `lifecycle`, `trust`, `install`, etc.)
-  the runtime ignores. Empirically tolerated; documented as
-  belt-and-braces against future runtime tightening.
-
-## Alternatives considered
-
-See § Decision above — Option A (dual projection) and Option C
-(commands_unsupported) explicitly rejected with stated rationale.
-
-## References
-
-- Roadmap:
-  `agents/roadmaps/road-to-claude-code-global-distribution.md` Phase 3.
-- Council session responses:
-  `agents/runtime/council/responses/claude-code-distribution.json`. <!-- council-ref-allowed: ADR decision trace -->
-- Empirical verification: `~/.claude/commands/probe/sub.md` route
-  test, 2026-05-28 (Condition 1 + Condition 2).
-- Mirror implementation: `scripts/install.py::_CLAUDE_SKILL_BUNDLE`
-  and `src/install/wizard-plan.ts::CLAUDE_SKILL_BUNDLE` — both
-  include `(".agent-src/commands", "commands")` so a global install
-  drops `~/.claude/commands/<cluster>/<sub>.md` directly.
-- Predecessor projection: `scripts/condense.py::generate_claude_commands`
-  (skills-list, retained pending separate retirement decision).

package/docs/decisions/ADR-031-validation-severity-tiers-and-projection-roundtrip.md

@@ -1,97 +0,0 @@
----
-adr: 031
-status: accepted
-date: 2026-05-29
-decision: validation-severity-tiers-and-projection-roundtrip
-supersedes: —
-superseded_by: —
-phase: continue-positioning-analysis
-type: structural
-review_date: 2026-06-12
----
-
-# ADR-031 — Adopt severity-tiered frontmatter validation + projection roundtrip test (from continuedev/continue analysis)
-
-## Status
-
-**Accepted** · 2026-05-29. Both changes are additive and verified
-empirically in the same session (validator exit 0 on 455 artefacts with
-0 fatal / 0 warnings; 9 roundtrip tests green), so the decision lands
-**without** soak. Review date 2026-06-12.
-
-## Context
-
-A competitive-positioning pass against `continuedev/continue` (evidence:
-[`agents/evidence/analysis/continue-positioning-2026-05-29.md`](../../agents/evidence/analysis/continue-positioning-2026-05-29.md))
-established that Continue is a **projection target**, not a competitor — its
-`.continue/rules/*.md` rules system consumes the artifact type this package
-produces. Our multi-tool projection + condensation model is the strategic
-moat and out-scopes Continue's single-target config.
-
-Two patterns from Continue's config layer were worth adopting independent of
-whether Continue is ever used here:
-
-1. **Severity-tiered validation** — Continue's `core/config/validation.ts`
-   splits fatal errors (halt load) from non-fatal warnings (logged, load
-   continues). Our `scripts/validate_frontmatter.py` was binary: any
-   `SchemaError` failed CI.
-2. **Roundtrip validation** — Continue round-trips markdown → frontmatter →
-   object → markdown in `packages/config-yaml/src/markdown/*.test.ts`. Our
-   projection emitters (`scripts/condense.py`) had no test asserting that a
-   source rule's load-bearing frontmatter survives the emit cycle.
-
-Baseline at decision time: 0 artefacts currently violate `minLength` /
-`maxLength`, so reclassifying length checks loosens nothing today.
-
-## Decision
-
-1. **Severity tiers in `scripts/validate_frontmatter.py`** — `SchemaError`
-   gains a `severity` field (`"error"` default). Structural keywords
-   (`required`, `type`, `enum`, `pattern`, `additionalProperties`,
-   `minItems`, `minimum`) stay **fatal** (exit 1). Length keywords
-   (`minLength`, `maxLength`) become **advisory warnings** (printed with
-   `⚠️`, exit 0). `_main` partitions and reports both; only fatals fail CI.
-2. **Projection roundtrip test** — `tests/test_projection_roundtrip.py`
-   asserts `condense._emit_cursor_mdc` and `_emit_windsurf_rule` preserve
-   `description` (newline-flattened) and the `alwaysApply` / `trigger`
-   derivation across emit → re-parse.
-
-Deferred (not adopted now):
-
-- **`.continue/` projection target** — gated on real Continue usage in our
-  projects. Until then it would be an unowned target = maintenance ballast.
-- **`uses/with/override` MCP composition** — watch, revisit if our
-  `scripts/mcp_render.py` needs composable blocks.
-
-## Consequences
-
-- Frontmatter quality nudges (length) no longer block CI; structural
-  correctness still does. A future over-long `description` surfaces as a
-  warning, not a red build — intentional, per Continue's fatal-vs-quality
-  split.
-- `SchemaError`'s new `severity` field is library-visible (`__all__`);
-  positional `(path, rule, message)` construction stays backward-compatible
-  via the default.
-- The roundtrip test fails loudly if a projection emitter drifts, instead of
-  shipping a malformed `.cursor/rules/*.mdc` or `.windsurf/rules/*.md`.
-- Reversal cost ~0: both changes are local and removable.
-
-## Alternatives
-
-- **Additive-only (no reclassification)** — add the severity capability but
-  keep every check fatal. Rejected: leaves the feature a no-op with no
-  warning source.
-- **Reclassify more checks** (e.g. `pattern`, `additionalProperties` →
-  warning) — rejected: those are structural correctness, loosening them
-  would let malformed frontmatter through.
-- **Skip the ADR, just code it** — rejected: changing a CI gate's strictness
-  is a deliberate decision that needs a written record.
-
-## References
-
-- [`agents/evidence/analysis/continue-positioning-2026-05-29.md`](../../agents/evidence/analysis/continue-positioning-2026-05-29.md)
-  — the positioning verdict table and adoption queue this ADR acts on.
-- `scripts/validate_frontmatter.py` — severity-tier implementation.
-- `tests/test_projection_roundtrip.py` — roundtrip implementation.
-- Upstream patterns: `continuedev/continue` `core/config/validation.ts`,
-  `packages/config-yaml/src/markdown/*.test.ts`.

package/docs/decisions/ADR-032-linked-projects-scope.md

@@ -1,122 +0,0 @@
----
-adr: 032
-status: accepted
-date: 2026-05-29
-decision: linked-projects-scope-go-option-a
-supersedes: —
-superseded_by: —
-phase: v3.x · multi-project-scope evaluation
-type: structural
-review_date: 2027-05-29
----
-
-# ADR-032 — Linked-projects scope: GO on opt-in auto-detection (Option A, passive awareness)
-
-## Status
-
-**Accepted** · 2026-05-29. Approves an opt-in auto-detection feature for
-IDE-attached sibling repositories, scoped to **passive awareness** (Option A).
-A same-day earlier draft recorded NO-GO; that verdict was reversed after the
-proactivity-gap argument (below). Time-boxed: review on **2027-05-29** or
-earlier if a kill-switch trigger fires.
-
-Not to be confused with [`ADR-029`](ADR-029-multi-workspace-deferred.md): that
-defers a restructure of the **package's own root layout**. This ADR is about
-the **agent's working scope over a sibling project repository**.
-
-## Context
-
-Developers routinely check out sibling repos that change together (e.g.
-`galawork-api` + `galawork-web`) and attach them in the IDE. Detection is
-deterministic from on-disk config (`.idea/modules.xml` + `vcs.xml`,
-`*.code-workspace`).
-
-A Phase-0 spike found Claude Code can already read/write a sibling outside its
-working directory **unconditionally** — no rule needed. An initial reading
-concluded the feature was therefore only an "awareness signal" a doc could
-deliver, and drafted NO-GO.
-
-## The reversal — proactivity gap
-
-That NO-GO mis-framed the value. The point is **not** capability (the agent can
-write everywhere); it is **proactivity**: the agent does **not** consider a
-sibling unless explicitly told, so cross-repo dependencies — an API change that
-breaks the frontend, a shared type that drifts — are missed by default. A
-manual doc/snippet presupposes the very awareness the target user lacks: the
-developer who needs this most is exactly the one who won't think to write the
-note. **Auto-detection is zero-knowledge** — it reads the relationship the
-developer already encoded by attaching the repo in their IDE.
-
-AI Council (anthropic/claude-sonnet-4-5 + openai/gpt-4o, 3 rounds + Karpathy
-peer-review, 2026-05-29) flipped to **GO** on this reasoning.
-
-## Decision — GO, scoped to Option A (passive awareness)
-
-Build an **opt-in** auto-detection feature:
-
-1. **Detect** IDE-attached siblings from on-disk config (config-driven only;
-   never arbitrary adjacent directories).
-2. **Opt-in once** per sibling; persist the choice **local-only** in
-   `.agent-settings.local.yml` (in agents/settings/) (gitignored, per-machine — sibling paths differ
-   per developer and must never be committed).
-3. **Behavioral directive** for in-scope siblings: proactively check cross-repo
-   impact on relevant changes (API contract, shared types) and **warn**.
-   **Do NOT bulk-include** the sibling's files (interpretation C — token
-   blowup — stays **out of scope**). Out-of-root writes still pass the host
-   agent's own permission gate.
-
-### A/B/C scoping
-
-- **A — passive awareness (CHOSEN):** know + warn, no bulk inclusion. Cheap, low risk.
-- **B — proactive dependency scanning:** auto-scan on every change. Deferred (needs heuristics).
-- **C — implicit inclusion of all sibling files:** **rejected** — token blowup, context pollution.
-
-### Fork resolutions
-
-- **Fork A** — `.agent-settings.local.yml` (in agents/settings/), deepest cascade layer reusing `_deep_merge` (not a bespoke override).
-- **Fork B** — key `linked_projects` (avoids ADR-007 "scope"/"workspace", ADR-029 "multi-workspace").
-- **Fork C** — cross-cwd writes documented, never auto-configured; host permission gate applies.
-
-## Consequences
-
-- New: detector (`scripts/_lib/linked_projects.py`), the
-  `.agent-settings.local.yml` (in agents/settings/) cascade layer, a committed-local lint, and the
-  `linked-projects-onboarding-gate` rule (tier-2b, **experimental**, **removable**).
-- The intra-repo module system (`enumerate_modules()`) is untouched.
-- Size never excludes a sibling — a real frontend (galawork-web ≈ 38k files)
-  must surface; it is flagged `large` (awareness only). The council's literal
-  "skip >20k files" guardrail was corrected: it conflated Option C's
-  file-inclusion cost with Option A, under which repo size is cost-irrelevant.
-- Per install decision **D2**, the installer does not touch the consumer
-  `.gitignore`; consumers gitignore `.agent-settings.local.yml` (in agents/settings/) themselves
-  (documented in the guide).
-
-## Kill-switch
-
-Experimental + removable by construction. If opt-in is consistently declined or
-siblings are never cited in practice, remove the rule. Signal stays local — no
-telemetry.
-
-## Open follow-ups
-
-- **Consumer detector reachability:** ✅ **Closed (2026-05-30, `road-to-leaner-core-and-discovery`
-  Phase 4).** The detector is now exposed as `agent-config linked-projects:list`
-  (`scripts/linked_projects_list.py`, registered in `src/cli/registry.ts` + `scripts/_dispatch.bash`),
-  wrapping `scripts/_lib/linked_projects.detect_linked_projects` + the `.agent-settings.local.yml`
-  opt-in cascade. Cross-repo *retrieval* over the opted-in siblings ships alongside it
-  (`/knowledge:cross-repo`, `scripts/cross_repo_retrieve.py`) per
-  [`cross-repo-retrieval`](../contracts/cross-repo-retrieval.md).
-- **Multi-agent verification:** only Claude Code was empirically validated.
-  Cursor / Augment / Copilot are unverified — the guide's manual snippet covers
-  them until an interactive per-IDE test is run.
-
-## Alternatives considered
-
-- **NO-GO + docs only** — rejected: a manual note fails the target user who lacks the awareness to write it.
-- **Build Option C** — rejected: token blowup.
-
-## References
-
-- [`docs/guides/cross-repo-linked-projects.md`](../guides/cross-repo-linked-projects.md)
-- [`ADR-007`](ADR-007-agent-discovery-scopes.md) — owns "scope"/"workspace".
-- [`ADR-029`](ADR-029-multi-workspace-deferred.md) — unrelated package-root multi-workspace defer.