session-orchestrator 4.0.1 → 4.2.0

package/docs/vault-docs-architecture.md

@@ -123,11 +123,13 @@ Data flow within a single `/session feature → /go → /close` cycle:
 | `vault-staleness` probes | `skills/discovery/probes-vault.md` + `skills/discovery/probes/vault-staleness.mjs` | `/discovery vault` (on-demand) and session-end Phase 2.3 (opt-in close-time gate) | `VAULT_DIR/01-projects/*/` `_overview.md` + narrative files | JSONL findings under `.orchestrator/metrics/vault-staleness.jsonl` and `vault-narrative-staleness.jsonl` | Vault/Ops (telemetry) |
 | `docs-orchestrator` | `skills/docs-orchestrator/SKILL.md` | session-start Phase 2.5, session-plan Step 1.5/1.8, session-end Phase 3.2 (all gated on `enabled: true`) | Session scope + Session Config audience list | `docs-tasks` block in STATE.md (write side); `### Documentation Coverage` block in final report (verify side) | All three (User / Dev / Vault) |
 | `docs-writer` agent | `agents/docs-writer.md` | Dispatched by `wave-executor` for each `Docs`-classified task | `diff`, `git-log`, `session-memory`, `affected-files` | Audience-targeted Markdown writes (Edit/Write); `[docs-orchestrator] Docs task complete` report line | All three (per task) |
-| `narrative-mirror` | `scripts/lib/vault-status/narrative-mirror.mjs` (`mirrorNarrative`) | session-end Phase 3.7, gated on `vault-integration.enabled` | `.claude/STATE.md` narrative sections + the session record | `<vault>/01-projects/<repo-slug>/_session-narrative.md` (generator-marked) | Vault/Ops (durable per-repo narrative) |
+| `narrative-mirror` | `scripts/lib/vault-status/narrative-mirror.mjs` (`mirrorNarrative`) | session-end Phase 3.7, gated on `vault-integration.enabled` | Generated session-state narrative sections (see input note below) + the session record | `<vault>/01-projects/<repo-slug>/_session-narrative.md` (generator-marked) | Vault/Ops (durable per-repo narrative) |
 | `board-writer` | `scripts/lib/vault-status/board-writer.mjs` (`sweepBoard` / `mirrorBoard`) | session-start Phase 1.7 (`in-progress`) and session-end Phase 3.7c (`closed`), gated on `vault-integration.enabled` | live session registry + this repo's root | `<vault>/01-projects/_active-sessions.md` — one row per repo (generator-marked, idempotent, never touches `_overview.md`) | Vault/Ops (cross-repo occupancy board) |
 | `vault-mirror` | `skills/vault-mirror/SKILL.md` + `scripts/vault-mirror.mjs` | session-end Phase 3.7 (sessions); evolve Phase 3.5 (learnings) | `.orchestrator/metrics/sessions.jsonl`, `.orchestrator/metrics/learnings.jsonl` | `<vault>/50-sessions/<id>.md`, `<vault>/40-learnings/<slug>.md` (`_generator` marker `session-orchestrator-vault-mirror@1`) | Vault/Ops (telemetry → Markdown) |
 | `vault-backfill` CLI | `scripts/vault-backfill.mjs` | Manual, also surfaced via `/plan retro vault-backfill` sub-mode | `vault-integration.gitlab-groups` config + GitLab API | `.vault.yaml` per repo + Vault stub directories | Vault/Ops (one-shot migration) |
 
+The narrative mirror reads narrative sections from the generated `.claude/STATE.md` input, together with the session record. <!-- path-check: example -->
+
 ---
 
 ## 4. Audience Model
@@ -138,7 +140,7 @@ table), which is the **single source of truth** for which files belong to
 which audience. Never inline this table elsewhere — always cross-link.
 
 - **User** — external/internal users of the repo. Targets: `README.md`,
-  `docs/user/**/*.md`, `docs/getting-started.md`, `examples/**/*.md`. Source:
+  `docs/user/**/*.md`, `docs/getting-started.md`, `examples/**/*.md`. Source: <!-- path-check: example -->
   `skills/docs-orchestrator/audience-mapping.md` § Audiences & File Patterns.
 - **Dev** — contributors to the repo, including future Claude sessions.
   Targets: `CLAUDE.md`, `docs/dev/**/*.md`, `docs/adr/**/*.md`. Source: same.

package/hooks/_lib/hook-import-set.json

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-09-07T18:36:32.142Z",
-  "head": "a244b8707aa5bb650673fce2e6cf548564b43e58",
+  "generated_at": "2026-09-09T06:39:55.000Z",
+  "head": "9ce6b296e95ce0bc274b887544f0fe885f814427",
   "entries": [
     {
       "file": "hooks/_lib/atomic-json.mjs",
@@ -384,7 +384,8 @@
       "reachable_from": [
         "on-session-end.mjs",
         "on-session-start.mjs",
-        "post-edit-validate.mjs"
+        "post-edit-validate.mjs",
+        "pre-bash-issue-budget.mjs"
       ]
     },
     {
@@ -600,6 +601,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "pre-bash-staging-fence.mjs",
         "pre-task-scope-disjoint.mjs",
@@ -677,6 +679,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -855,6 +858,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -884,6 +888,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "pre-task-scope-disjoint.mjs",
         "skill-invocation-telemetry.mjs"
@@ -926,6 +931,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "pre-bash-staging-fence.mjs",
         "pre-task-scope-disjoint.mjs",
@@ -989,6 +995,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1010,6 +1017,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1031,6 +1039,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1223,6 +1232,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1244,6 +1254,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1313,6 +1324,12 @@
         "on-session-start.mjs"
       ]
     },
+    {
+      "file": "scripts/lib/session-shape.mjs",
+      "reachable_from": [
+        "on-session-start.mjs"
+      ]
+    },
     {
       "file": "scripts/lib/session-start-probes.mjs",
       "reachable_from": [
@@ -1377,6 +1394,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1406,6 +1424,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1478,6 +1497,12 @@
         "pre-bash-staging-fence.mjs"
       ]
     },
+    {
+      "file": "scripts/lib/wave-sizing.mjs",
+      "reachable_from": [
+        "on-session-start.mjs"
+      ]
+    },
     {
       "file": "scripts/lib/worktree/listing.mjs",
       "reachable_from": [

package/hooks/_lib/vcs-create-matcher.mjs

@@ -53,8 +53,9 @@
  *             a spaced subshell is a statement like any other. "Resolved verb"
  *             means: after leading `VAR=value` assignments, after transparent
  *             process wrappers (`nohup`, `command`, `sudo`, `env`, `timeout`,
- *             `xargs`, `exec`), and basename-normalised, so an absolute path
- *             (`/opt/homebrew/bin/glab`) resolves to `glab` (#1145).
+ *             `exec`), and basename-normalised, so an absolute path
+ *             (`/opt/homebrew/bin/glab`) resolves to `glab` (#1145). `xargs` is
+ *             NOT one of those wrappers — see the named ceiling below.
  *   NO MATCH: the words inside a quoted string, a `#` comment, or a here-doc
  *             body (they are data, not a command); a single token that merely
  *             CONTAINS the three words (`"glab issue create"` runs a binary of
@@ -95,6 +96,28 @@
  *     triage of a per-session counter file
  *     (`.orchestrator/runtime/issue-budget/<hash>.json`, #1141) or in a
  *     transcript census of real create calls.
+ *   - An `xargs`-driven create is NOT matched, and `xargs` is deliberately not
+ *     a transparent wrapper: `command-blocker.mjs` classes it as an INTERPRETER
+ *     (`SHELL_EXEC_INTERPRETERS`), because unwrapping it there would LOOSEN the
+ *     destructive-command guard that shares this lexer. Measured 2026-09-09
+ *     against this file — all four shapes yield 0 statements, so neither the
+ *     cap nor the loop-deny sees them:
+ *
+ *         xargs glab issue create --title X                          → 0
+ *         echo X | xargs -I% glab issue create --title %             → 0
+ *         seq 1 50 | xargs -I% gh api -X POST …/issues -f title=%    → 0
+ *         xargs -n1 glab issue create                                → 0
+ *
+ *     Widening this one shape means changing what `resolveSegmentVerb` reports
+ *     for `xargs` — read by the four OTHER consumers of that resolver
+ *     (`grep -rln resolveSegmentVerb scripts/ hooks/`, 2026-09-09:
+ *     `scripts/lib/project-hygiene.mjs`, `scripts/lib/scope-gate.mjs`,
+ *     `hooks/pre-bash-sessions-ledger-guard.mjs`,
+ *     `hooks/pre-bash-destructive-guard.mjs`) — so it is a deliberate
+ *     cross-consumer change, never a local patch here.
+ *     Pinned by `tests/hooks/vcs-create-matcher.test.mjs`. Revisit when an
+ *     `xargs`-driven create shows up in a transcript census or in the overflow
+ *     triage of a per-session counter file.
  *   - A paren glued to the verb (`(glab issue create …)`) is not reached: it
  *     lexes as the single word `(glab`. This is `command-blocker.mjs`'s own
  *     named ceiling on `COMMAND_POSITION_KEYWORDS` (#1145), inherited here
@@ -205,9 +228,115 @@ function matchReading(verb, tokens, index) {
     host: m[1] === 'gh' ? 'github' : 'gitlab',
     kind: /** @type {'pr'|'mr'|'issue'} */ (m[2]),
     verb: /** @type {'create'|'new'} */ (m[3]),
+    via: /** @type {'cli'} */ ('cli'),
   };
 }
 
+/**
+ * A REST path whose LAST segment is `issues` — the issue COLLECTION endpoint,
+ * which is the only one a POST creates an issue on.
+ *
+ * Deliberately anchored at the end (`?` allowed for a query string): the
+ * sub-resources `.../issues/12/notes` and `.../issues/12` are a comment and an
+ * update, neither of which creates an issue. Matching them would charge the cap
+ * for a note.
+ */
+const ISSUE_COLLECTION_PATH = /(^|\/)issues(\?|$)/;
+
+/** `-f` / `-F` / `--field` / `--raw-field` — the payload flags both CLIs take. */
+const FIELD_FLAGS = new Set(['-f', '-F', '--field', '--raw-field']);
+
+/**
+ * Recognise the REST-API route to issue creation: `gh api` / `glab api`
+ * against an `/issues` collection path (#1163 BUG-2).
+ *
+ * ## Why this is not an optional extra
+ *
+ * Measured 2026-09-09 over a 13-shape census of the matcher: every `api` form
+ * was a MISS, i.e. a COMPLETE silent bypass of the issue-budget cap and of the
+ * templates-first gate —
+ *
+ *     glab api --method POST projects/1/issues -f title=X   → isIssueCreate false
+ *     gh api repos/o/r/issues -f title=X                     → isIssueCreate false
+ *     gh api -X POST repos/o/r/issues -f title=X             → isIssueCreate false
+ *
+ * All three file a real issue. The subcommand route (`glab issue create`) was
+ * gated from the start, so an agent that hit the cap could reach the same
+ * effect through `api` with no counter moving at all.
+ *
+ * ## The narrow shape (guard-design: widen the matcher, not the bypass)
+ *
+ * A LIST call must not match — `gh api repos/o/r/issues` is the single most
+ * common read in this repo's own tooling, and charging it would make the cap
+ * fire on reads. So the accepted shape is: verb `gh`/`glab`, next token `api`,
+ * an `/issues` COLLECTION path somewhere in the argument list, AND either
+ *   - an explicit POST method (`--method POST`, `--method=POST`, `-X POST`,
+ *     `-XPOST`), or
+ *   - a `title=` payload field (`-f title=…`), which only a create carries.
+ * An explicit NON-POST method (`--method GET`, `-X PATCH`) is a hard NO-MATCH
+ * even when a `title=` field is present: an update is not a creation.
+ *
+ * `--help` short-circuits here exactly as it does for the subcommand route.
+ *
+ * NAMED CEILING (BV-004): the payload flags are read as `-f title=…` token
+ * pairs and `--field=title=…` is NOT recognised (neither CLI accepts that
+ * spelling today). A create whose whole body arrives via `--input -` on stdin
+ * matches only through the explicit POST method, which is the shape both CLIs
+ * require for that form. Revisit if a census of real create calls shows an
+ * `api` shape reaching neither condition.
+ *
+ * @param {string} verb — basename-normalised verb from resolveSegmentVerb
+ * @param {Array<{ text: string, quoted: boolean }>} tokens — the whole statement
+ * @param {number} index — token index the verb resolved to
+ * @returns {{ host: 'github'|'gitlab', kind: 'issue', verb: 'create', via: 'api' } | null}
+ */
+function matchApiReading(verb, tokens, index) {
+  if (verb !== 'gh' && verb !== 'glab') return null;
+  const sub = tokens[index + 1];
+  if (!sub || sub.quoted || sub.text !== 'api') return null;
+
+  let method = null;
+  let hasTitleField = false;
+  let issuePath = false;
+
+  for (let i = index + 2; i < tokens.length; i++) {
+    const tok = tokens[i];
+    const text = tok.text;
+    if (!tok.quoted && text === '--help') return null;
+    if (!tok.quoted && (text === '--method' || text === '-X')) {
+      method = tokens[i + 1]?.text ?? '';
+      i += 1;
+      continue;
+    }
+    if (!tok.quoted && text.startsWith('--method=')) {
+      method = text.slice('--method='.length);
+      continue;
+    }
+    if (!tok.quoted && text.startsWith('-X') && text.length > 2) {
+      method = text.slice(2);
+      continue;
+    }
+    if (!tok.quoted && FIELD_FLAGS.has(text)) {
+      const value = tokens[i + 1]?.text ?? '';
+      if (value.startsWith('title=')) hasTitleField = true;
+      i += 1;
+      continue;
+    }
+    // A path is an operand, quoted or not — `gh api "repos/o/r/issues"` is the
+    // same call as the bare form, and quoting an operand is not concealment the
+    // way quoting a whole COMMAND is.
+    if (ISSUE_COLLECTION_PATH.test(text)) issuePath = true;
+  }
+
+  if (!issuePath) return null;
+  if (method !== null) {
+    if (!/^post$/i.test(method)) return null;
+  } else if (!hasTitleField) {
+    return null;
+  }
+  return { host: verb === 'gh' ? 'github' : 'gitlab', kind: 'issue', verb: 'create', via: 'api' };
+}
+
 /**
  * Test one statement's token array against {@link CREATE_REGEX}, reading the
  * head at the RESOLVED verb index rather than at token 0 (#1145).
@@ -233,7 +362,9 @@ function matchStatement(tokens) {
   }
   for (const reading of [resolved, resolved.alt]) {
     if (!reading || typeof reading.verb !== 'string' || reading.index < 0) continue;
-    const shape = matchReading(reading.verb, tokens, reading.index);
+    const shape =
+      matchReading(reading.verb, tokens, reading.index) ??
+      matchApiReading(reading.verb, tokens, reading.index);
     if (shape) return shape;
   }
   return null;
@@ -267,7 +398,85 @@ function findCreateStatement(command) {
  *   `null` when no statement in the command is a `gh`/`glab` create/new call.
  */
 export function matchVcsCreate(command) {
-  return findCreateStatement(command)?.shape ?? null;
+  const shape = findCreateStatement(command)?.shape;
+  if (!shape) return null;
+  // The `via` marker is deliberately NOT part of THIS return shape: the sibling
+  // suite `tests/unit/hook-issue-budget.test.mjs` pins it by `toEqual` on the
+  // exact three keys, and a fourth key would fail those assertions without any
+  // behaviour changing. Consumers that need the route ask
+  // {@link findIssueCreateStatements}, which carries it.
+  return { host: shape.host, kind: shape.kind, verb: shape.verb };
+}
+
+/**
+ * Read the `--title` (subcommand route) or `-f title=…` (api route) value off
+ * ONE statement's tokens.
+ *
+ * @param {Array<{ text: string, quoted: boolean }>} tokens
+ * @returns {string|null}
+ */
+function titleFromTokens(tokens) {
+  for (let i = 0; i < tokens.length; i++) {
+    const text = tokens[i].text;
+    if (text === '--title') {
+      const value = tokens[i + 1]?.text;
+      return typeof value === 'string' ? value.trim() || null : null;
+    }
+    if (text.startsWith('--title=')) {
+      return text.slice('--title='.length).trim() || null;
+    }
+    if (FIELD_FLAGS.has(text)) {
+      const value = tokens[i + 1]?.text ?? '';
+      if (value.startsWith('title=')) return value.slice('title='.length).trim() || null;
+      i += 1;
+    }
+  }
+  return null;
+}
+
+/**
+ * EVERY issue-create statement in the command chain, in source order (#1163
+ * BUG-1).
+ *
+ * ## Why the callers cannot keep using {@link isIssueCreate} alone
+ *
+ * `isIssueCreate` answers "does this command create an issue?" — a BOOLEAN,
+ * which is exactly one issue short of what a QUANTITY gate needs. Measured
+ * 2026-09-09 against `hooks/pre-bash-issue-budget.mjs` before this change:
+ * `glab issue create --title A && glab issue create --title B` charged the cap
+ * ONCE for TWO issues, because the hook called `chargeIssueBudget` once per
+ * Bash tool call with the whole command string. The segmentation to answer it
+ * correctly was already here — nothing consumed it per statement.
+ *
+ * Each record carries the tokens the caller must judge (never the whole
+ * command): a chain may mix an exempt create with a chargeable one, and
+ * classifying the exemption on the joined command text would exempt BOTH —
+ * the same class of hole as the bypass-scoping regression documented on
+ * {@link matchesBypass}.
+ *
+ * `text` is the statement rebuilt from its tokens (quotes already resolved by
+ * the lexer, arguments joined by single spaces). It is a CLASSIFICATION INPUT
+ * for `classifyExemption`, never something to re-execute.
+ *
+ * @param {string} command
+ * @returns {Array<{ shape: { host: string, kind: string, verb: string, via: string },
+ *                   tokens: Array<{ text: string, quoted: boolean }>,
+ *                   text: string,
+ *                   title: string|null }>}
+ */
+export function findIssueCreateStatements(command) {
+  const out = [];
+  for (const tokens of statementsOf(command)) {
+    const shape = matchStatement(tokens);
+    if (!shape || shape.kind !== 'issue') continue;
+    out.push({
+      shape,
+      tokens,
+      text: tokens.map((t) => t.text).join(' '),
+      title: titleFromTokens(tokens),
+    });
+  }
+  return out;
 }
 
 /**
@@ -463,16 +672,5 @@ export function extractTitle(command) {
 
   const found = findCreateStatement(command);
   const tokens = found ? found.tokens : statementsOf(command).flat();
-
-  for (let i = 0; i < tokens.length; i++) {
-    const text = tokens[i].text;
-    if (text === '--title') {
-      const value = tokens[i + 1]?.text;
-      return typeof value === 'string' ? value.trim() || null : null;
-    }
-    if (text.startsWith('--title=')) {
-      return text.slice('--title='.length).trim() || null;
-    }
-  }
-  return null;
+  return titleFromTokens(tokens);
 }

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v4.0.1 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v4.2.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v4.0.1 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v4.2.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {