session-orchestrator 3.24.0 → 4.0.1

package/docs/instruction-delivery.md

@@ -632,6 +632,75 @@ Not read off the code — run, on two disjoint scopes, comparing the emitted sub
 
 ```console
 $ # hooks scope
+---
+
+## 8. Which harness reads which file (measured 2026-09-06)
+
+> Survey of 8 agent harnesses, W1 d10/d11 of session `main-2026-09-06-deep-1`.
+> The question this table settles: *when a foreign harness opens this repository,
+> what does it actually load?*
+
+| Harness | Instruction file | Skill discovery path |
+|---|---|---|
+| Claude Code | `CLAUDE.md` | plugin skills (`.claude-plugin/`) |
+| Codex CLI | `AGENTS.md` | `.codex-plugin` skills |
+| Cursor | `AGENTS.md` | `.agents/skills`, `.cursor/skills` |
+| Copilot CLI | `AGENTS.md` **and** `CLAUDE.md` | `.github/skills`, `.claude/skills`, `.agents/skills` |
+| OpenCode | `AGENTS.md` | `~/.claude/skills` |
+| Amp | `AGENTS.md` | `.agents/skills` |
+| Kiro | `AGENTS.md` | — |
+| Gemini CLI | `GEMINI.md` | `skills/<name>/SKILL.md` layout |
+| Pi | — | manifest skills |
+
+**The finding.** 7 of 8 read `AGENTS.md`; exactly one (Claude Code) reads only
+`CLAUDE.md`; exactly one (Copilot CLI) reads both. Measured the same day,
+`git ls-files | grep -i AGENTS.md` returned only `agents/AGENTS.md` (the
+sub-agent authoring spec) and one rule file — i.e. **this repo, opened in Codex
+CLI, OpenCode, Kiro or Amp, could not find its own `## Session Config`.** The
+gap was invisible from inside Claude Code, which is the only harness anyone here
+develops in.
+
+`.agents/skills/` is the intersection of the skill-discovery column: Cursor, Amp
+and Copilot CLI all read it, so one generated mirror serves three harnesses.
+
+### 8.1 `AGENTS.md` is generated, never edited
+
+The root `AGENTS.md` is a **byte-identical generated copy** of `CLAUDE.md`
+(`scripts/generate-agents-skills.mjs`), gated by that script's `--check` inside
+`scripts/validate-plugin.mjs`. Edit `CLAUDE.md` and regenerate; a hand-edit is a
+CI failure. Hand-maintenance is not an option this repo gets to pick — #726
+measured six divergent `AGENTS.md` strategies across the fleet.
+
+A symlink was the smaller diff and was rejected on three measurements:
+`package.json` `files[]` does not publish `CLAUDE.md` (a symlink would dangle in
+the npm tarball); `core.symlinks` defaults to false on Windows without Developer
+Mode, where git writes the link out as a 10-byte regular file containing the
+literal text `CLAUDE.md`; and `git ls-files -s | awk '$1=="120000"'` returned
+zero rows, so this repo — itself a template others copy — has no symlink
+precedent. The drift gate still ACCEPTS a symlink, for consumer repos that
+prefer one.
+
+The `.agents/skills/` mirror carries only the six frontmatter fields
+agentskills.io permits outside Claude Code (`name`, `description`, `license`,
+`compatibility`, `metadata`, `allowed-tools`); our `tools:` spelling maps onto
+`allowed-tools:`, and non-spec keys (`tags`, `model-preference*`, `color`,
+`args-schema`, …) fold into `metadata` as strings. The body is a pointer at
+`skills/<name>/SKILL.md`, never a copy of it — progressive disclosure keeps the
+whole mirror at 47,380 bytes across 43 files.
+
+These are the two artifacts emitted by `scripts/generate-agents-skills.mjs`. Plugin
+manifests are maintained separately under `.claude-plugin/`, `.codex-plugin/` and
+`.cursor-plugin/`; `scripts/release.mjs` updates their versions with `package.json`.
+The initial 4.0.0 standard root `plugin.json` was moved to the native Cursor location
+because it intercepted Codex's skill path and version selection; see
+[Codex manifest compatibility](codex-setup.md#manifest-compatibility).
+
+Codex has a separate generated surface: `scripts/generate-codex-skills.mjs` writes
+`.codex-plugin/skills/` from the union of canonical command and skill names. Commands
+win same-name overlaps, and each adapter reads the canonical document before dispatch.
+The portable `.agents/skills/` mirrors continue to reference canonical skills directly;
+they do not replace the installed Codex command entrypoints.
+
 ## Learnings Index (selected for your file scope)
 
 7 entries (3 matched your declared file scope, 4 general). One line each — this is an INDEX, not the corpus.

package/{agents/memory-proposal-collector.md → docs/memory-proposal-flow.md}

@@ -1,11 +1,4 @@
----
-name: memory-proposal-collector
-description: 'Reference documentation (NOT a dispatchable agent) for the coordinator-direct AUQ rendering flow at session-end Phase 3.6.3. The coordinator collects proposals from `.orchestrator/metrics/proposals.jsonl` via `collectProposals()` and renders the multiSelect AUQ in batches of 4. Approved proposals flow to `learnings.jsonl` with `_provenance: agent-proposed@<wave-id>` via `sink.writeApproved()`. AUQ is a coordinator-only tool — this flow does NOT dispatch as a subagent. <example>Context: session-end Phase 3.6.3, proposals.jsonl contains 5 entries from W2/W3 agents. user "Close the session." assistant "I''ll render the AUQ in 2 batches of 4 + 1, then route the user''s choices through writeApproved + archiveRejected per agents/memory-proposal-collector.md." <commentary>The collector flow is coordinator-direct because AskUserQuestion is unavailable inside subagents per .claude/rules/ask-via-tool.md AUQ-004.</commentary></example>'
-model: inherit
-color: cyan
-tools: Read, Grep, Glob
-sandbox-tier: read-only
----
+<!-- Moved in v4.0.0 from `agents/memory-proposal-collector.md` (audit 2026-09-06 § 5A). It never was a dispatchable agent — it documents a coordinator-direct flow — but Claude Code's plugin loader registers every `agents/*.md` by directory convention and the manifest's `agents` key is additive-only, so no manifest entry could exclude it. Living under `docs/` removes the registration instead of bounding it. -->
 
 # Memory Proposal Collector (Reference Documentation)
 

package/docs/migration-v4.md

@@ -0,0 +1,365 @@
+# 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 integration | native manifests | generated root `AGENTS.md` + `.agents/skills/`; separate Claude, Codex and Cursor manifests |
+| 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.
+
+The Codex command integration uses generated skills: search for `go` or `close` in the
+picker and select the **Session Orchestrator** entry, or invoke `$session-orchestrator:go` and
+`$session-orchestrator:close`. Refresh the installed plugin as above and restart Codex if
+the new entries do not appear. The native `/goal` command is separate.
+
+The initial 4.0.0 root Agent Plugins `plugin.json` has been replaced by a native Cursor
+manifest. Read-only probes on Codex 0.153.3 and desktop runtime 0.153.4 showed that the
+standard root manifest overrides Codex's declared skill directory and cache version.
+The separate native manifests avoid that conflict; details are in
+[Codex manifest compatibility](codex-setup.md#manifest-compatibility).
+
+### 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.
+
+Cursor's plugin metadata now lives at `.cursor-plugin/plugin.json`, replacing the initial
+4.0.0 standard root `plugin.json`. The native manifest retains the canonical skills and
+MCP paths and explicitly disables additional component discovery; the installer above
+continues to supply commands and hooks. The shape follows the
+[official Cursor manifest reference](https://cursor.com/docs/reference/plugins); native
+Cursor loading was not runtime-tested during this compatibility repair.
+
+### 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
+```
+
+`[ -L "$p" ]` checks the destination's TYPE, not who created it — it removes any symlink at that
+path regardless of origin. If you separately symlinked your own command under one of these three
+names, this recipe deletes that symlink too; a regular (non-symlink) file is the only thing it
+leaves untouched.
+
+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. The two installers behave
+  differently: `cursor-install.mjs` skips any destination that already exists — a symlink or a
+  file (`scripts/cursor-install.mjs:69-73`; the `hooks.json` writer at `:139-140`) — and
+  re-creates only the ones that are MISSING, so re-running it from the 3.24.0 checkout only
+  **adds** command links missing from your project; it does not restore a link you removed
+  yourself and does not resync an existing `hooks.json`.
+  `pi-install.mjs --settings-only` **does** rewrite the Pi settings file: it reads it, upserts
+  this package's entry and writes it back (`scripts/pi-install.mjs` `upsertPackage` /
+  `writeSettings`), so re-running it from the 3.24.0 checkout re-points Pi at that checkout.
+  For Cursor, to get a removed link back: delete 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)