session-orchestrator 3.23.0 → 4.0.0

package/docs/migration-v4.md

@@ -0,0 +1,341 @@
+# Migrating to Session Orchestrator v4.0.0
+
+v4.0.0 removes public surfaces. Nothing about the core loop changes — `/session`, `/go`,
+`/close`, `/plan`, `/discovery`, `/evolve`, `/bootstrap` and the rest of the 25 commands
+behave exactly as in 3.x — but five skills, three commands and eight top-level scripts are
+gone, two files leave `agents/`, and two telemetry names are deprecated on a dated clock.
+This guide is for someone running 3.x today: which invocations break, what replaces them,
+what happens to your state, and how to go back.
+
+The removals follow a two-signal rule measured over a 90-day window — **0 telemetry ∧ 0
+fleet invocation ∧ no runtime consumer** — not a judgement call. Evidence:
+[`docs/audits/2026-09-06-360-audit.md`](./audits/2026-09-06-360-audit.md), per-agent raw
+reports under [`audits/2026-09-06-360-audit/w1/`](./audits/2026-09-06-360-audit/w1/). Full
+change list: [CHANGELOG.md](../CHANGELOG.md).
+
+## 1. What Changes
+
+| Area | 3.x | 4.0.0 |
+|------|-----|-------|
+| Skills (`SKILL.md` files) | 49 | 43 — 5 removed, 1 merged into `architecture` |
+| Commands | 28 | 25 — `/contract-version-bump`, `/journey-audit`, `/autopilot-multi` removed |
+| Top-level scripts | 8 more than today | 8 removed (0 runtime callers each) |
+| `agents/*.md` | 16 (2 of them not agents) | 14 — the two non-agents moved to `docs/` |
+| `.claude/rules/` | 61 files (43 generated) | 26 files (43 generated → 8 thematic) |
+| Turn-stop event | `orchestrator.session.stopped` | `orchestrator.turn.stopped` (both emitted until 2027-03-06) |
+| Telemetry field | `fleet` | `fleet_self_declared` (both sent until 2027-03-06) |
+| Cross-harness manifest | none | root `AGENTS.md` + root `plugin.json` + `.agents/skills/` |
+| Session shapes | `housekeeping` / `feature` / `deep` | unchanged, plus the `ultradeep` PROFILE over `deep` |
+| Runtime | Node 24+, npm | unchanged |
+
+### 1a. Invocations that break
+
+| You invoke | Status in 4.0.0 | What to do instead |
+|---|---|---|
+| `/contract-version-bump` | **removed** | No replacement. Bump the contract's version literal by hand and note it in your CHANGELOG. |
+| `/journey-audit` | **removed** | No replacement. It required a journey manifest; zero existed fleet-wide, so it was never runnable. |
+| `/autopilot-multi` | **removed** | No replacement. `/autopilot` (single-story) is unaffected and stays. |
+| the `daily` skill | **removed** | No replacement. A recurring daily note is a scheduled task / cloud Routine, not a session skill — see `.claude/rules/loop-and-monitor.md` § LM-004. |
+| the `skill-creator` skill | **removed** | Anthropic's official `skill-creator` plugin, or `claude plugin init`. |
+| the `ubiquitous-language` skill | **removed** | No replacement. |
+| the `domain-model` skill | **merged** | `/architecture` — the material now lives at `skills/architecture/references/domain-model.md` (with `ADR-FORMAT.md` and `CONTEXT-FORMAT.md` beside it). |
+| `node scripts/autopilot-multi.mjs` | **removed** | No replacement. | <!-- path-check: historical -->
+| `node scripts/backfill-learnings.mjs`, `…-expires.mjs` | **removed** | No replacement — one-shot ledger repairs, already applied. | <!-- path-check: historical -->
+| `node scripts/migrate-learnings-jsonl.mjs`, `migrate-subagents-jsonl.mjs` | **removed** | No replacement — one-shot format migrations; the target format has been canonical for several releases. | <!-- path-check: historical -->
+| `node scripts/fleet-instruction-scan.mjs`, `lifecycle-sim-v6.mjs`, `upload-social-preview.mjs` | **removed** | No replacement. | <!-- path-check: historical -->
+| dispatching `AGENTS.md` as an agent | **removed as a dispatch target** | It was never an agent — it is the authoring spec, now [`docs/agent-authoring.md`](./agent-authoring.md). Read it; do not dispatch it. |
+| dispatching `memory-proposal-collector` as an agent | **removed as a dispatch target** | Now [`docs/memory-proposal-flow.md`](./memory-proposal-flow.md). |
+| citing `skills/_shared/model-selection.md` | **removed** | No replacement; it had zero consumers. |
+| Session Config `autopilot.bg-isolation` | **removed** | No replacement — delete the `autopilot:` block from your `CLAUDE.md`/`AGENTS.md`, it was the block's only field and is now inert (`scripts/parse-config.mjs` never parsed it). |
+| Session Config `webhooks.<kind>.url` | **removed** (pre-4.0.0, `ce6a28aa`) | No replacement — `scripts/lib/webhook-url.mjs` had zero callers. The still-live Clank Event Bus webhook (`CLANK_EVENT_SECRET`/`CLANK_EVENT_URL`) is unrelated and unaffected. | <!-- path-check: historical -->
+
+### 1b. Telemetry consumers (dated deprecations, nothing breaks yet)
+
+If you read `.orchestrator/metrics/events.jsonl` or the ingest server, two names change and
+**both old and new are emitted for one generation**, so no reader breaks on upgrade day:
+
+- **`orchestrator.session.stopped` → `orchestrator.turn.stopped`.** The emitter always fired
+  per assistant TURN, not per session — measured 15,538 records against 2,016 distinct
+  `orchestrator.session.started` ids over 90 days, i.e. 7.7 per session, 184 for one id. Any
+  "sessions stopped" count you derived from it is a **turn count**, wrong by that factor. Both
+  names carry an identical payload from the same object, so they cannot disagree; every record
+  under the legacy name additionally carries `deprecated: true`. **Switch the name you match
+  on and change nothing else. Removal of the legacy name: 2027-03-06.** To count sessions,
+  count `session.started` ids; to count closes, count `sessions.jsonl` records with
+  `status: completed`. Unaffected: `orchestrator.agent.stopped`, whose per-agent cardinality
+  was always correct.
+- **`fleet` → `fleet_self_declared`.** The old name claimed something the client cannot know.
+  The new name says what it is, and the authoritative classification is now server-side (an
+  anon-id allowlist). `fleet` keeps being sent with an identical value for the whole
+  generation so an existing column stays comparable. **Removal: 2027-03-06.** Contract:
+  [`docs/telemetry.md`](./telemetry.md).
+
+## 2. Prerequisites
+
+- **Node.js 24 or later** — unchanged from v3. `node --version`.
+- **Git** — any recent version.
+- **`npm install` after updating.** Still mandatory, and now slightly less punishing: in 3.x,
+  4 of 27 hooks died at module-load with `ERR_MODULE_NOT_FOUND: js-yaml` when `node_modules`
+  was absent. In 4.0.0 all 27 hooks exit 0 without `node_modules` — but they run degraded, so
+  install anyway.
+- **`glab` / `gh`** — optional, unchanged.
+
+Nothing new is required. There is no data migration, no schema bump, and no config key you
+must add.
+
+## 3. Upgrade Steps
+
+### 3a. Claude Code
+
+```bash
+# 1. Update the plugin — run this INSIDE Claude Code, not in a shell:
+#      /plugin update session-orchestrator@kanevry
+#    A marketplace-installed plugin lives in a managed cache, not a git checkout,
+#    so `git pull` does not apply to it.
+
+# 2. Install Node dependencies in the cache copy:
+SO_DIR="$(dirname "$(find ~/.claude/plugins/cache -path '*session-orchestrator*' -name package.json 2>/dev/null | head -1)")"
+cd "$SO_DIR" && npm install
+
+# 3. Restart Claude Code so hooks.json is re-read.
+```
+
+From 4.0.0 on, session-start compares the version that is **running** against the npm
+`dist-tags.latest` and prints a one-line banner when they differ. It fails silent: offline, a
+non-2xx response, malformed JSON or a timeout each produce no statement — never a false "you
+are up to date".
+
+### 3b. Codex CLI
+
+```bash
+codex plugin marketplace upgrade kanevry   # omit the name to refresh all marketplaces
+codex plugin add session-orchestrator@kanevry
+codex plugin list --available --json
+```
+
+For the maintainer / local-clone path instead:
+
+```bash
+cd ~/Projects/session-orchestrator
+git pull && npm install
+node scripts/codex-install.mjs
+```
+
+New in 4.0.0 and relevant here: this repository now ships a **root `AGENTS.md`**
+(byte-identical to `CLAUDE.md`). Before, a Codex-family harness resolving project
+instructions from `AGENTS.md` found nothing in this repo. If you keep your own
+`AGENTS.md`, nothing changes for you.
+
+### 3c. Cursor IDE
+
+```bash
+cd ~/Projects/session-orchestrator
+git pull && npm install
+node scripts/cursor-install.mjs /path/to/your-project    # links NEW commands/rules/skills only
+# Restart Cursor
+```
+
+**The installer adds new files; it never overwrites or removes an existing one.** `linkPath()`
+skips whenever the destination already exists as a symlink or a file
+(`scripts/cursor-install.mjs:69-73`), and the `hooks.json` writer skips outright when one is
+already there (`:139-140`). Two consequences on this upgrade: the malformed `argument-hint` fix
+(the 3.x generator wrote it into 24 of 28 command files, GH#54) reaches you for free through
+your existing symlinks the moment `git pull` updates this checkout — no re-run needed for that.
+But the three retired commands do **not** disappear from `.cursor/commands/` on their own, and a
+`hooks.json` written before 4.0.0 is never synchronised with a new hook event automatically.
+Both need the manual step in § 5 ("Cursor still shows the removed commands") below.
+
+A root `plugin.json` following the [agent-plugins.org](https://agent-plugins.org) 1.0.0
+schema now ships as well, for Cursor's plugin system.
+
+### 3d. Pi
+
+```bash
+pi install npm:session-orchestrator
+```
+
+Or against a local checkout:
+
+```bash
+cd ~/Projects/session-orchestrator
+git pull && npm install
+node scripts/pi-install.mjs /path/to/your-project --settings-only
+```
+
+`pi/prompts/` drops from 28 to 25 files, matching `commands/`.
+
+### 3e. Verify
+
+Run `/session housekeeping` in any configured repo. You should see the session-start banner;
+`/contract-version-bump`, `/journey-audit` and `/autopilot-multi` should no longer be offered.
+Then:
+
+```bash
+node scripts/parse-config.mjs --json     # now works — in 3.x this failed with "File not found: --json"
+node scripts/validate-plugin.mjs
+```
+
+## 4. What Stays the Same
+
+**Your state is untouched. There is no migration step and no format change.**
+
+- **`.orchestrator/` in every repo** — `metrics/sessions.jsonl`, `metrics/learnings.jsonl`,
+  `metrics/events.jsonl`, `current-session.json`, `session.lock`, `state.lock`, filescopes and
+  wave-scope manifests are all read-write compatible in both directions. Nothing is rewritten
+  on upgrade, and nothing 4.0.0 writes is unreadable by 3.24.0.
+- **`STATE.md`** — same frontmatter schema. 4.0.0 adds ONE optional scalar,
+  `session-profile`, and absent is not empty: a STATE.md without it behaves exactly as before.
+  A 3.x build reading a 4.0.0 STATE.md simply ignores the extra key.
+- **Session Config in `CLAUDE.md` / `AGENTS.md` / Cursor rules** — no key you are likely using
+  is renamed or given a new default. Two keys ARE removed — `autopilot.bg-isolation` and
+  `webhooks.<kind>.url` — see § 1a above; everything else you configured in 3.x is still
+  correct as-is.
+- **Session memory** (`~/.claude/projects/<project>/memory/`) — untouched.
+- **`session-type`** — still the closed set `housekeeping` / `feature` / `deep`. `ultradeep`
+  is an argument ALIAS that resolves to `session-type: deep` plus
+  `session-profile: ultradeep`; it is deliberately not a fourth type, because a fourth member
+  would degrade silently in the telemetry mapper and the close-backfiller.
+- **The whole core loop** — `/session`, `/go`, `/close`, `/plan`, `/discovery`, `/evolve`,
+  `/bootstrap`, `/debug`, `/autopilot` and the other remaining commands take the same
+  arguments and run the same flow.
+- **VCS integration** — `glab` / `gh` commands, label taxonomy, issue and MR templates.
+
+## 5. Known Issues & Workarounds
+
+### Your CLAUDE.md cites a removed skill
+
+**Nothing breaks at runtime.** A citation in a consumer repo's `CLAUDE.md` (or `AGENTS.md`) to
+`daily`, `skill-creator`, `ubiquitous-language`, `contract-version-bump`, `journey-audit`,
+`domain-model` or `skills/_shared/model-selection.md` is prose. No loader resolves it, no hook
+reads it, and the session starts normally.
+
+**But `claude-md-drift-check` may flag it** as a dangling citation, and if you run it with
+`enforcement: strict` that finding is an error rather than a warning. Two ways out, both fine:
+
+1. Delete or rewrite the citation. `domain-model` becomes
+   `skills/architecture/references/domain-model.md`; the other five have no successor, so the
+   sentence usually goes away with the skill.
+2. Leave it and accept the warning until your next docs pass. It is a documentation-parity
+   finding, not a functional one.
+
+Same story for a rule file or ADR that names one of the removed scripts.
+
+### A wrapper script or Routine calls a removed top-level script
+
+`node scripts/<name>.mjs` on any of the eight removed scripts now exits with a Node
+`ERR_MODULE_NOT_FOUND`-class failure — a loud error, not a silent no-op. If a cron job,
+Routine or CI step calls one, delete that step: the two `migrate-*` scripts had already
+completed their one-shot migration, and the two `backfill-learnings*` scripts their one-shot
+repair, before this release.
+
+### A dashboard suddenly reports far fewer "sessions stopped"
+
+Expected, and it was wrong before, not now. See § 1b — you were counting turns. Match on
+`orchestrator.turn.stopped`, or better, count `session.started` ids for sessions and
+`sessions.jsonl` records with `status: completed` for closes.
+
+### `npm install` fails with `ERESOLVE` or peer-dep warnings
+
+Use Node 24 or later, matching `engines.node: ">=24.0.0"`. If it persists:
+`npm install --legacy-peer-deps`.
+
+### Hooks silently no-op after the update
+
+Node must be on `PATH` inside the **editor** process, not only in your terminal. Verify from
+inside Claude Code with `!node --version`. This is unchanged from v3.
+
+### Cursor still shows the removed commands
+
+Re-running the installer does **not** fix this: `linkPath()` skips any destination that already
+exists (`scripts/cursor-install.mjs:69-73`), including a stale symlink pointing at a command
+that no longer exists in this repo. Remove only the three dead **symlinks** from your project —
+never an unconditional `rm -f`, which would just as happily delete a regular file, including a
+command you wrote yourself under one of these three names (the installer itself never overwrites
+or deletes a regular file; this recipe must not either):
+
+```bash
+for f in autopilot-multi contract-version-bump journey-audit; do
+  p=/path/to/your-project/.cursor/commands/$f.md
+  [ -L "$p" ] && rm "$p"   # -L: true only for a symlink, so a real file with this name survives
+done
+```
+
+Then restart Cursor. Same story for `.cursor/hooks.json`: the installer skips it outright once
+it exists (`:139-140`), so a `hooks.json` written before 4.0.0 is never re-synced with a new hook
+event automatically — re-check it by hand (diff it against a fresh `node scripts/cursor-install.mjs`
+run in an empty scratch directory if you suspect drift).
+
+## 6. Rollback
+
+4.0.0 removes surfaces; it does not migrate data. **Rolling back is therefore a plain version
+switch — no state has to be converted, and nothing you wrote under 4.0.0 becomes unreadable.**
+
+**Claude Code / plugin cache.** A marketplace install tracks the marketplace's current
+version; this repo documents no version-pin flag for `/plugin install`, so do not guess one.
+Roll back by pointing Claude Code at a local clone parked on the old tag:
+
+```bash
+git clone https://github.com/Kanevry/session-orchestrator ~/so-3.24.0
+cd ~/so-3.24.0 && git checkout v3.24.0 && npm install
+```
+
+Then, inside Claude Code, remove the marketplace-installed copy and add the clone as the
+plugin source (`/plugin marketplace add ~/so-3.24.0`, then install from it) and restart the
+editor. If you are unsure of the exact `/plugin` subcommands on your build, run `/plugin`
+with no arguments — it lists them.
+
+**Local checkout (Codex / Cursor / Pi / maintainer):**
+
+```bash
+cd /path/to/session-orchestrator
+git fetch --tags
+git checkout v3.24.0
+npm install                       # the 3.24.0 lockfile, not the 4.0.0 one
+node scripts/codex-install.mjs                              # Codex — no target-project argument
+node scripts/cursor-install.mjs /path/to/your-project        # Cursor — pass YOUR project, not this checkout
+node scripts/pi-install.mjs /path/to/your-project --settings-only   # Pi — same argument contract
+# Restart your editor
+```
+
+Run only the line for your platform. `cursor-install.mjs` and `pi-install.mjs` both default their
+target to `process.cwd()` when no argument is given (`scripts/cursor-install.mjs:24-51`) — omit
+the project path here and the installer links into `/path/to/session-orchestrator` itself, not
+into your project.
+
+**npm consumers:** `npm install session-orchestrator@3.24.0`.
+
+What you get back, and what you do not:
+
+- **Your state survives in both directions.** `sessions.jsonl`, `learnings.jsonl`,
+  `events.jsonl` and `STATE.md` written by 4.0.0 are readable by 3.24.0. The one 4.0.0
+  addition to STATE.md, `session-profile`, is an unknown key to 3.24.0 and is ignored, not
+  rejected.
+- **`orchestrator.turn.stopped` records written under 4.0.0 stay in your `events.jsonl` after
+  a rollback.** 3.24.0 does not know the name and will not count them; the
+  `orchestrator.session.stopped` twin of every one of those records is right beside it, so no
+  data is lost — only a 3.x reader sees each turn once instead of twice.
+- **The removed skills, commands and scripts come back with the checkout.** They were deleted
+  from the repository, not from your disk history.
+- **What does NOT roll back automatically** is anything an installer wrote into YOUR project:
+  `.cursor/commands/`, `.cursor/hooks.json`, Pi settings. Both `cursor-install.mjs` and
+  `pi-install.mjs` skip any destination that already exists — a symlink or a file
+  (`scripts/cursor-install.mjs:69-73`; the `hooks.json` writer at `:139-140`) — so re-running
+  the installer from the 3.24.0 checkout only **adds** files missing from your project. It does
+  not restore a symlink you removed yourself, and it does not resync an existing `hooks.json` or
+  Pi settings file. To get those back: remove the stale file first (§ "Cursor still shows the
+  removed commands" has a safe, symlink-only removal recipe), then re-run the installer with
+  your project path, as shown above.
+
+If 4.0.0 blocks you, please open an issue describing the blocker before rolling back — a
+removal we got wrong is fixable in a 4.0.x patch.
+
+## 7. Support
+
+- **GitHub:** [Kanevry/session-orchestrator/issues](https://github.com/Kanevry/session-orchestrator/issues)
+  — preferred for bugs and feature requests.
+- **Homepage:** [session-orchestrator.com](https://session-orchestrator.com)
+
+When filing a bug, include `node --version`, your OS and arch, the harness (Claude Code /
+Codex CLI / Cursor / Pi), the plugin version actually running (the session-start banner prints
+it), and a minimal reproduction. For hook failures, attach the relevant entries from
+`.orchestrator/metrics/events.jsonl`.

package/docs/pi-setup.md

@@ -18,7 +18,12 @@ pi install npm:session-orchestrator
 
 This is the primary install path — the package is published to npm (since v3.16.0, 2026-07-19) and carries the `pi-package` keyword for the [Pi packages gallery](https://pi.dev/packages) index; no local checkout required. The dev-fallback options below remain available for working against a local checkout.
 
-The short git form documented for Pi packages (`pi install git:github.com/user/repo`) is **unverified against this repo as of 2026-08-28** — the `pi` CLI was not installed on the verifying host (`which pi` → not found), so no install attempt could be made. The npm form above remains the only measured, documented install path; do not elevate the `git:` short form to this guide or to README until it has been run against this repo and the result dated.
+The short git form for Pi packages is `pi install git:github.com/user/repo@ref`. Two separate questions were previously collapsed into one "unverified" verdict; they are split here because only one of them is still open (measured 2026-09-06, W1 d10):
+
+- **Is the syntax real?** Yes — the `git:` short form, including the `@ref` suffix, is documented upstream. The 2026-08-28 line that called the *syntax* unverified was stale and is corrected here.
+- **Does it work against THIS repo?** Still unverified. The `pi` CLI is not installed on the verifying host (`which pi` → not found), so no install attempt has been made against `github.com/Kanevry/session-orchestrator`. The npm form above remains the only *measured* install path.
+
+Do not elevate the `git:` form to README as a recommended install line until it has been run against this repo and the result dated. Citing it as valid Pi syntax is fine; citing it as a verified install path for this package is not.
 
 ### Option 2: Project-local registration (dev fallback)
 

package/docs/plugin-architecture-v3.md

@@ -114,7 +114,7 @@ Under `scripts/lib/`. Each module is a focused concern and exports only what cal
 | Module | 1-liner | Key exports |
 |--------|---------|-------------|
 | **`io.mjs`** | Hook stdin/stdout helpers matching the Claude Code contract | `readStdin`, `emitAllow`, `emitDeny`, `emitWarn`, `emitSystemMessage` |
-| **`platform.mjs`** | OS + editor detection | `SO_OS`, `SO_IS_WINDOWS`, `SO_IS_WSL`, `SO_PATH_SEP`, `SO_STATE_DIR`, `detectPlatform()` |
+| **`platform.mjs`** | OS + editor detection | `SO_OS`, `SO_IS_WINDOWS`, `SO_IS_WSL`, `SO_PATH_SEP`, `getStateDir()`, `detectPlatform()` |
 | **`path-utils.mjs`** | CWE-23-safe path helpers (null-byte rejection, UNC block, cross-drive escape, locale-stable casing) | `normalizeForMatching`, `isWithin`, `CWE_23_ATTACK_PATTERNS` |
 | **`config.mjs`** | CRLF-tolerant Session Config parser (originally parse-config.sh in v2; byte-exact parity preserved) | `parseSessionConfig`, `readConfigFile`, `getConfigValue` |
 | **`config-schema.mjs`** | Plain-JS validator; validates the 7 mandatory Session Config fields (3 required strings + 4 typed fields) | `validateSessionConfig` (internal `REQUIRED_STRING_FIELDS` constant covers the 3 required strings — not exported) |

package/docs/rule-authoring.md

@@ -194,32 +194,33 @@ The `learning-key` field above links a rule to a learning record, but does not b
 
 ### The type-taxonomy + per-type TTL registry (single source of truth)
 
-`LEARNING_TYPE_REGISTRY` in [`scripts/lib/learnings/schema.mjs`](../scripts/lib/learnings/schema.mjs) (~L80–107) is the **single source of truth** for every learning `type`'s TTL policy and its two cross-module capability flags. Before this registry existed (pre-#733), three modules independently hand-maintained overlapping type lists that drifted out of sync. `LEARNING_TTL_DAYS` (this file), `PROPOSAL_TYPES` (`scripts/lib/memory-proposals/schema.mjs`), and `CONVERT_TYPES` (`scripts/lib/reconcile/eligibility.mjs`) are now all **derived** from this one registry — no hand-maintained duplicate lists remain.
+`LEARNING_TYPE_REGISTRY` in [`scripts/lib/learnings/schema.mjs`](../scripts/lib/learnings/schema.mjs) (~L92–127) is the **single source of truth** for every learning `type`'s TTL policy and its three cross-module capability flags (`agentProposable`, `ruleConvertible`, `hostScoped` — four axes in total, counting `ttlDays`). Before this registry existed (pre-#733), three modules independently hand-maintained overlapping type lists that drifted out of sync. `LEARNING_TTL_DAYS` (this file), `PROPOSAL_TYPES` (`scripts/lib/memory-proposals/schema.mjs`), and `CONVERT_TYPES` (`scripts/lib/reconcile/eligibility.mjs`) are now all **derived** from this one registry — no hand-maintained duplicate lists remain.
 
 Transcribed verbatim from `LEARNING_TYPE_REGISTRY` (16 types):
 
-| Type | ttlDays | agentProposable | ruleConvertible |
-|------|---------|------------------|------------------|
-| `mode-selector-accuracy` | 30 | true | false |
-| `hardware-pattern` | 60 | true | false |
-| `fragile-file` | 45 | true | true |
-| `effective-sizing` | 45 | true | false |
-| `recurring-issue` | 45 | true | true |
-| `workflow-pattern` | 90 | true | true |
-| `proven-pattern` | 90 | true | true |
-| `anti-pattern` | 90 | true | true |
-| `autopilot-effectiveness` | 90 | true | false |
-| `autonomy-verdict` | 90 | false | false |
-| `domain-regression` | 60 | true | false |
-| `convention` | 90 | true | true |
-| `architecture-pattern` | 90 | true | true |
-| `design-pattern` | 90 | true | true |
-| `fragile-pattern` | 45 | false | true |
-| `stagnation-class-frequency` | 60 | false | true |
+| Type | ttlDays | agentProposable | ruleConvertible | hostScoped |
+|------|---------|------------------|------------------|------------|
+| `mode-selector-accuracy` | 30 | true | false | false |
+| `hardware-pattern` | 60 | true | false | true |
+| `fragile-file` | 45 | true | true | false |
+| `effective-sizing` | 45 | true | false | false |
+| `recurring-issue` | 45 | true | true | false |
+| `workflow-pattern` | 90 | true | true | false |
+| `proven-pattern` | 90 | true | true | false |
+| `anti-pattern` | 90 | true | true | false |
+| `autopilot-effectiveness` | 90 | true | false | false |
+| `autonomy-verdict` | 90 | false | false | false |
+| `domain-regression` | 60 | true | false | false |
+| `convention` | 90 | true | true | false |
+| `architecture-pattern` | 90 | true | true | false |
+| `design-pattern` | 90 | true | true | false |
+| `fragile-pattern` | 45 | false | true | false |
+| `stagnation-class-frequency` | 60 | false | true | false |
 
 Capability axes:
 - **`agentProposable`** — the type may appear in `PROPOSAL_TYPES` (a wave-agent may `memory.propose()` this type). `autonomy-verdict`, `fragile-pattern`, and `stagnation-class-frequency` are `false` — these are analyzer-synthesized classes, not agent-observed, so they are never agent-proposable.
 - **`ruleConvertible`** — the type may appear in `CONVERT_TYPES` (the FA2 reconciliation engine may convert a learning of this type into a conditional `.claude/rules/*.md` proposal). `fragile-file`, `recurring-issue`, `anti-pattern`, `convention`, `architecture-pattern`, `design-pattern`, `fragile-pattern`, `stagnation-class-frequency`, `workflow-pattern`, and `proven-pattern` are the ten `ruleConvertible: true` types (issue #900 flipped the last two from `false` — the real corpus census showed a large volume of these records carrying usable `file_paths` scope that were structurally unconvertible before the flip).
+- **`hostScoped`** — `reconcile/emitter.mjs` may copy the record's `host_class` through as the emitted rule's `host-class` activation axis (issue #1090; derived set: that module's `HOST_SPECIFIC_TYPES`). `hardware-pattern` is the ONLY `true` type today — its content IS the chip/OS, so gating the emitted rule by host-class is faithful rather than an accidental one-machine restriction. For every other type `host_class` merely records the machine the learning was authored on and must never gate the rule.
 
 ### Type aliasing (issue #900)
 
@@ -257,6 +258,71 @@ Field-by-field:
 
 **Provenance is session-slug based, not issue-number based.** The only session-identity field the schema carries is `source_session` (a kebab-slug like `main-2026-07-03-session-1`) — there is currently no issue-number provenance field on a learning record or a generated rule. Adding issue-number provenance (linking a rule back to the GitHub/GitLab issue that motivated the learning) would require a schema addition to `scripts/lib/learnings/schema.mjs` — out of scope for this documentation pass.
 
+### Consolidated rules: N provenance pairs in ONE file (the merge contract)
+
+A rule file may ABSORB several generated rules. This is the supported way to
+stop `.claude/rules/` growing one 2.6 kB file per learning — measured
+2026-09-06 @ `e4674109`: 43 generated files / 112,443 B, 46.2 % of it pure
+frontmatter + provenance overhead, consolidated to 8 thematic files (33
+absorbed, 10 dropped). Four rules make a merge safe, and skipping any one of
+them silently loses a learning or regenerates it:
+
+1. **Frontmatter `learning-key:` is a SCALAR — so N−1 markers live in the
+   body.** `engine.mjs` reads BOTH forms: the frontmatter
+   `FRONTMATTER_LEARNING_KEY_RE` (`^learning-key: <value>`) and the body
+   bullets `BODY_LEARNING_KEY_RE` / `BODY_LEARNING_ID_RE`
+   (`` - learning-key: `<value>` `` / `` - learning-id: `<value>` ``). A merged
+   file therefore carries **one `- learning-key:` + `- learning-id:` bullet
+   PAIR per absorbed learning** in its `## Provenance` section, and may omit
+   the frontmatter scalar entirely. Removing a pair does not "tidy up" the
+   file — it makes that learning look unmaterialized, and the next
+   `/reconcile` regenerates it as a standalone rule.
+
+2. **`expires-at` is the EARLIEST of the absorbed dates.** A merged file must
+   not outlive its shortest-lived content: one date now covers several
+   learnings, so it must expire when the FIRST of them is due for review, not
+   the last. (Taking the latest would silently extend every other learning's
+   TTL past what its type registry granted it.) State the rule in the file
+   itself, so the next editor does not "fix" it upward.
+
+3. **Keep `globs:` only, and take the UNION.** The merged file loads for any
+   path any of its parts covered, so its `globs:` is the union of theirs.
+   `rule-loader.mjs` resolves `globs:` and `paths:` with `globs:` winning
+   SILENTLY when both are present (issue #795, `parseGlobsFrontmatter`) — so a
+   file carrying both duplicate keys ships the `paths:` block as dead bytes.
+   Write `globs:` alone.
+
+4. **Substance in, boilerplate out.** Each absorbed learning becomes an `###`
+   heading carrying its original rule sentence, plus its evidence line. What is
+   dropped is only the per-file repetition (the `# Auto-generated rule:` title,
+   the untrusted-content wrapper repeated 43×, the `evidence-digest` /
+   `evidence-digest-input` / `source-session` fields). Never drop an evidence
+   line to hit a byte target — an insight with no measurement behind it is the
+   thing `.claude/rules/measurement-discipline.md` exists to forbid.
+
+**Dropping a learning requires a stamp BEFORE the delete.** Deleting a
+generated rule file whose insight is already carried verbatim by a hand-written
+always-on rule is legitimate — but `rm` alone does not stick. `engine.mjs`
+treats a learning as `alreadyMaterialized` if EITHER the idempotency sidecar
+holds a terminal verdict for its `learning_key` (`isProcessed`) OR a
+`.claude/rules/*.md` file still carries its marker. Delete the file without
+stamping and both conditions go false, so the next `/reconcile` proposes it
+again. Stamp it first, via the store's only sanctioned writer:
+
+```js
+import { markCandidateProcessed } from '../scripts/lib/reconcile/idempotency.mjs';
+markCandidateProcessed({
+  learningKey: 'anti-pattern/<subject-slug>',
+  outcome: 'rejected',        // or 'already-on-disk' when it lives elsewhere
+  fallbackSlug: '<the .claude/rules slug>',
+  repoRoot,
+});
+```
+
+This writes `.orchestrator/runtime/reconcile-candidates.jsonl` (creating it if
+absent). Verify with a dry run: `alreadyMaterialized` must equal
+absorbed + dropped, not absorbed alone.
+
 ## Authoring Examples
 
 ### (a) Hand-authored always-on rule (no frontmatter)

package/docs/scope-collision-guard.md

@@ -41,22 +41,22 @@ The coordinator's **own** planned direct edits belong in `coordinator.json` in t
 
 `wave-scope.json` is written into the WORKING COPY, not into the session — so until #1123 one session's manifest governed every session sharing that checkout. Measured 2026-08-22 (#1082): a Discovery wave's `allowedPaths: []` — which `wave-loop.md` prescribes for *every* Discovery wave — denied every write of an unrelated parallel session, with a deny reason that could only tell it to fix a wave plan it does not own.
 
-Two OPTIONAL manifest fields close that: `session` (the raw `session_id`) and its human-readable twin `semantic_session`. Both come from ONE `sessionAttribution(repoRoot)` call (`scripts/lib/events.mjs`, reads `.orchestrator/session.lock` once) in the same coordinator step that writes the rest of the manifest — `skills/wave-executor/wave-loop.md` § Scope Manifest 1.
+Two OPTIONAL manifest fields close that: `session_id` (the raw harness session id) and its human-readable twin `semantic_session_id` — the same spelling `.orchestrator/session.lock` and `current-session.json` use (renamed from `session` / `semantic_session` in #1153 P2; readers accept the legacy pair until the next minor release, see `MANIFEST_SESSION_KEYS` in `scripts/lib/session-identity/own-session.mjs`). Both come from ONE `attributionForRecord(repoRoot)` call (`scripts/lib/events.mjs`) in the same coordinator step that writes the rest of the manifest — `skills/wave-executor/wave-loop.md` § Scope Manifest 1. Unlike a raw lock read, `attributionForRecord()` reads `.orchestrator/session.lock` and then confirms the lock's raw `session_id` against `readProcessLocalSessionIds()` before returning anything — a mismatch (or no process-local id at all) yields `{}`, never a peer's ids (#1207).
 
-The reader is `hooks/enforce-scope.mjs` **Gate 3b**, between the manifest parse (G3) and the path-guard gate (G4). It resolves identity via `readOwnSessionIds(projectRoot, { hookInput: input })` and classifies via `classifyManifestSession(scope, ownIds)`, both from [`scripts/lib/session-identity/own-session.mjs`](../scripts/lib/session-identity/own-session.mjs):
+The reader is `hooks/enforce-scope.mjs` **Gate 3b**, between the manifest parse (G3) and the path-guard gate (G4). It resolves identity via `new Set(readProcessLocalSessionIds({ hookInput: input }))` and classifies via `classifyManifestSession(scope, ownIds)`, both from [`scripts/lib/session-identity/own-session.mjs`](../scripts/lib/session-identity/own-session.mjs):
 
 | Manifest state | `classifyManifestSession` verdict | Gate 3b disposition |
 |---|---|---|
-| no `session` / `semantic_session` (legacy, pre-#1123) | `unknown` | ENFORCE — falls through unchanged |
+| no `session_id` / `semantic_session_id` (and no legacy `session` / `semantic_session`; pre-#1123) | `unknown` | ENFORCE — falls through unchanged |
 | an id present and matching one of our own | `own` | ENFORCE — falls through unchanged |
 | ids present, none matching, own identity resolvable | `foreign` | **ALLOW** + one `orchestrator.scope.foreign_session_ignored` event |
 | ids present, own identity unresolvable (empty id set) | `unknown` | ENFORCE |
 
 Five properties are choices, not omissions — and every one of them points the fail-**closed** way, the deliberate inverse of § 4.1's posture for the dispatch hook:
 
-- **Only what is PROVABLY foreign is foreign.** `readOwnSessionIds()` returns the **UNION** of three sources — hook input (`session_id`/`sessionId`/`parent_session_id`) ∪ `CLAUDE_CODE_SESSION_ID` ∪ `session.lock` (`session_id`/`semantic_session_id`) — and an EMPTY set when none yields an id, which can only produce `unknown`. A gate that guessed would turn "cannot tell" into a silent enforcement-off on every harness exporting no session id. Every value is trimmed on the way in, so a whitespace-only env var cannot enter as a phantom id that matches nothing (`.claude/rules/development.md` § env-var whitespace trap).
-- **Union, not first-tier-wins.** Any id the process can legitimately claim names this session; only an id in NO source is somebody else's. Gating the sources made the READER's identity a strict subset of the WRITER's — the manifest's `session` comes from `sessionAttribution()` = the same repo-global lock — and three divergences all produced the same silent failure, the OWN manifest read `foreign` and the write gate switched itself off for the whole wave, logging an event indistinguishable from correct behaviour: (a) a nested harness where payload `session_id` ≠ `CLAUDE_CODE_SESSION_ID` (measured in `hooks/pre-bash-issue-budget.mjs` `resolveSessionId`); (b) a sub-agent invocation, whose own id is the subagent's while the manifest names the coordinator; (c) a session that lost the lock race and therefore wrote a PEER's id into its own manifest (see the writer guard below). The union only ADDS ids the process actually carries, so the security direction is unchanged: a manifest whose id appears in no source still classifies `foreign`. Its cost is named and points fail-**closed** — a peer-owned lock makes us enforce a peer's wave plan, which is a visible deny rather than a silent enforcement-off.
-- **The writer verifies the binding names itself.** Because the lock is repo-global, `skills/wave-executor/wave-loop.md` § Scope Manifest 1 requires the coordinator to compare `sessionAttribution()`'s ids against its own session (STATE.md `session`) and to OMIT the `session`/`semantic_session` keys when they diverge — unbound = ENFORCE. The reader's union covers the case anyway; the writer guard keeps the manifest readable as an audit record instead of publishing a foreign name.
+- **Only what is PROVABLY foreign is foreign.** `readProcessLocalSessionIds()` returns the ids that are PROCESS-LOCAL — hook input (`session_id`/`sessionId`/`parent_session_id`) and `CLAUDE_CODE_SESSION_ID` — and an EMPTY set when neither yields an id, which can only produce `unknown`. The repo-global `session.lock` is deliberately NOT a tier here (#1194): it is ONE file shared by every session in the checkout, so unioning it let a peer's manifest match a peer-written lock id, classify `own`, and have Gate 7 deny the second session's legitimate writes — the exact lockout G3b exists to end. A better signal REPLACES a worse one (`.claude/rules/host-resources.md` § HR-102). A gate that guessed would turn "cannot tell" into a silent enforcement-off on every harness exporting no session id. Every value is trimmed on the way in, so a whitespace-only env var cannot enter as a phantom id that matches nothing (`.claude/rules/development.md` § env-var whitespace trap).
+- **Union across the process-local tiers, not first-tier-wins.** Both process-local tiers are read and merged; only an id in NEITHER is somebody else's. Gating them against each other made the READER's identity a strict subset of the WRITER's — the manifest's `session` comes from `sessionAttribution()` = the same repo-global lock — and two divergences inside these tiers produce the same silent failure, the OWN manifest read `foreign` and the write gate switched itself off for the whole wave, logging an event indistinguishable from correct behaviour: (a) a nested harness where payload `session_id` ≠ `CLAUDE_CODE_SESSION_ID` (measured in `hooks/pre-bash-issue-budget.mjs` `resolveSessionId`); (b) a sub-agent invocation, whose own id is the subagent's while the manifest names the coordinator. A third divergence — a session that lost the lock race and wrote a PEER's id into its own manifest — is NO longer covered here since #1194 dropped the lock tier; it is the accepted cost in limit 11, and its defense is the writer guard. The merge only ADDS ids the process actually carries, so the security direction is unchanged: a manifest whose id appears in neither tier still classifies `foreign`. Its cost is named in limit 11 below.
+- **The writer's binding check is mechanical, not a prose comparison (#1207).** Because the lock is repo-global, `skills/wave-executor/wave-loop.md` § Scope Manifest 1 calls `attributionForRecord(repoRoot)`, which confirms the lock's raw `session_id` against `readProcessLocalSessionIds()` internally and returns `{}` on any mismatch or absent process-local id — the coordinator writes whatever comes back, with no further comparison to perform. STATE.md is deliberately not part of this check: it is a shared working-copy artefact written by whichever session holds the lock, so under a peer-owned lock STATE.md's `session` field would agree with the lock about the same peer and "confirm" exactly the wrong id. OMIT the `session_id`/`semantic_session_id` keys whenever `attributionForRecord()` returns `{}` — unbound = ENFORCE. The reader's union covers the case anyway; the writer guard keeps the manifest readable as an audit record instead of publishing a foreign name.
 - **Gate 3b runs after the parse, never on the raw bytes.** A corrupt manifest yields `{}`, hence no ids, hence `unknown` — and keeps failing closed. A gate that peeked at the bytes first would let a truncated manifest disarm the guard.
 - **The empty string is a validator ERROR, not a third flavour of absent.** `validateSession()` → `validateOptionalSessionId()` in `scripts/validate-wave-scope.mjs` rejects `"session": ""` with *"an empty id attributes to nothing; omit the key entirely to declare the manifest unbound"*. An empty id satisfies a truthiness check while matching nobody, so every reader would classify the manifest FOREIGN where the writer meant UNBOUND — opposite dispositions, not a cosmetic ambiguity. An ABSENT key only WARNS, because the § 3.3 pre-union skeleton is itself an unbound manifest and so is every manifest written before #1123.
 
@@ -89,7 +89,7 @@ false
 true true
 ```
 
-Both globs match `scripts/lib/x.mjs`, yet the direct comparison says `false`. For `assertFileScopeSubset()` that inexactness is *safe*: its glob branch reduces to verbatim presence plus literal-prefix coverage and therefore **over-approximates coverage**, which at worst accepts a union it could not fully prove. For a **collision** check the sign flips — the same over-approximation becomes a **false negative**, i.e. a missed collision, i.e. the incident. That is why the two exact stages decide first and stage 3 is reached only for pairs neither can settle.
+Both globs match `scripts/lib/x.mjs`, yet the direct comparison says `false`. For `assertFileScopeSubset()` that inexactness is *safe*: its glob branch reduces to verbatim presence plus literal-prefix coverage and therefore **over-approximates coverage**, which at worst accepts a union it could not fully prove. For a **collision** check the sign flips — the same over-approximation becomes a **false negative**, i.e. a missed collision, i.e. the incident. That is why the two exact stages decide first and stage 3 is reached only for pairs neither can settle. <!-- path-check: example -->
 
 ## 4. The hook
 
@@ -174,7 +174,7 @@ Complete list of what this guard does **not** see, or sees only approximately:
 8. **Lock loss reopens the race.** On lock timeout the cycle runs unlocked (row 14) — two dispatches starting together can then read the same ledger state and one record is lost. That is the pre-lock behaviour, chosen over denying on a lock-file problem.
 9. **The session binding is self-declared** (§ 2.3). `session` is a plain field in a file any process in this working copy can write, so writing a foreign id into it turns the write gate off for that manifest. Named rather than hidden: it is the SAME power `enforcement: "off"` already grants in the same file, so Gate 3b adds no new authority — the manifest is the coordinator's own artefact either way.
 10. **Only the WRITE gate is session-bound.** The dispatch ledger of § 4 takes its session component from the harness's own `input.session_id` (`waveKeyOf(projectDir, sessionId, …)`), and reads only `wave` and `role` out of `wave-scope.json` — the `session` field is not consulted there at all. So a peer session's manifest cannot bind this session's writes since #1123, but the two hooks reach that property by different routes, and a change to one does not carry to the other.
-11. **A peer-owned lock costs enforcement precision, deliberately.** `readOwnSessionIds()` unions the `session.lock` ids in (§ 2.3), and the lock is repo-global — so while a peer holds it, that peer's manifest classifies `own` here and its `allowedPaths` bind this session's writes: the #1082 shape, but now as a visible deny naming a wave plan we do not own. The alternative (gating the lock behind the payload) fails the other way and silently, because the manifest's own `session` is written from that same lock. Bounded by the writer guard in `skills/wave-executor/wave-loop.md` § Scope Manifest 1 (omit rather than write a foreign id) and by `session.lock` heartbeat-liveness. Revisit if a manifest ever carries the writer's PROCESS identity alongside the lock-derived one, which would let the reader distinguish the two cases instead of unioning them.
+11. **A session that published a peer's id reads its OWN manifest as `foreign` (#1194) — the writer's defense is now mechanical (#1207).** Dropping the lock tier (§ 2.3) moved the cost to the other side of the trade: with a raw `sessionAttribution()` read, a session that lost the `bootstrapLock()` race could get the peer's id and write it into its own manifest, and Gate 3b would then classify the manifest `foreign`, standing its own write guard down. Since #1207 the writer calls `attributionForRecord(repoRoot)` instead — `skills/wave-executor/wave-loop.md` § Scope Manifest 1 — which confirms the lock's raw `session_id` against `readProcessLocalSessionIds()` before returning anything and yields `{}` on any mismatch, so the coordinator performs no manual comparison and STATE.md plays no part in it (a shared working-copy artefact written by whichever session holds the lock, not a process-local witness). A filled binding is therefore provably this session's own; unbound (`{}`) = ENFORCE. CEILING (BV-004): on a harness that exports no session env var and puts no `session_id` in the hook payload (Codex CLI, Cursor today) both tiers are empty, so G3b is permanently `unknown` = enforce = pre-#1123 behaviour there. Revisit when Codex/Cursor hook payloads carry a session id.
 
 ## 7. Debugging