@mmerterden/multi-agent-pipeline 20.8.3 → 20.9.0

package/pipeline/lib/stack-detect.sh

@@ -30,7 +30,9 @@
 # unreadable directory as a language-free repo.
 
 # Markers whose mere presence decides a stack, as data rather than a `case`
-# cascade: `stack:glob:maxdepth`. Adding a language is one line here, which is
+# cascade: `stack:glob:maxdepth:extensions`, where the extensions are the
+# stack's source language (used to discount a marker below the root, see
+# _ma_share_ok). Adding a language is one line here, which is
 # the point - a contributor who has to edit control flow to add Rust will
 # instead widen somebody else's regex.
 #
@@ -39,19 +41,28 @@
 # a JVM service), and one package.json can be web, backend or both. Those two
 # run after the table, with their reasoning at the point of decision.
 MA_STACK_MARKERS="\
-ios:Package.swift:3
-ios:*.xcodeproj:3
-ios:*.xcworkspace:3
-ios:Podfile:3
-web:vite.config.*:3
-web:nuxt.config.*:3
-web:angular.json:3
-web:svelte.config.*:3
-backend:requirements.txt:3
-backend:pyproject.toml:3
-backend:go.mod:3
-backend:Cargo.toml:3
-backend:pom.xml:3"
+ios:Package.swift:3:swift|m|mm
+ios:*.xcodeproj:3:swift|m|mm
+ios:*.xcworkspace:3:swift|m|mm
+ios:Podfile:3:swift|m|mm
+web:vite.config.*:3:js|jsx|ts|tsx|mjs|cjs|vue|svelte
+web:nuxt.config.*:3:js|jsx|ts|tsx|mjs|cjs|vue|svelte
+web:angular.json:3:js|jsx|ts|tsx|mjs|cjs|vue|svelte
+web:svelte.config.*:3:js|jsx|ts|tsx|mjs|cjs|vue|svelte
+backend:requirements.txt:3:py
+backend:pyproject.toml:3:py
+backend:go.mod:3:go
+backend:Cargo.toml:3:rs
+backend:pom.xml:3:java|kt|scala"
+
+# Every source extension a language share is measured against: the table's
+# own plus common languages no marker names.
+MA_STACK_SOURCE_EXTS='swift|m|mm|kt|java|scala|js|jsx|ts|tsx|mjs|cjs|vue|svelte|py|go|rs|dart|cs|rb|php|c|cc|cpp|h|hpp'
+# Below this share (percent of tracked source files) a marker under the root
+# is ignored, once the repo tracks at least MA_STACK_MIN_FILES source files; a
+# smaller tree is too small to judge by share.
+MA_STACK_MIN_SHARE=1
+MA_STACK_MIN_FILES=50
 
 # Dependency names that decide which side of one package.json a repo is on. A
 # Next app with API routes is honestly both, so both may be recorded.
@@ -119,14 +130,42 @@ ma_stack_detect() {
     _why="${_why:+$_why }$1<-$2"
   }
 
-  local _why="" hit row stack pat depth
+  # A marker below the root counts only when the stack's own language is at
+  # least MA_STACK_MIN_SHARE percent of the tracked source files. A subtree
+  # copied in without being a submodule is not pruned by name: a Kotlin app
+  # carrying a shared configuration repo's Package.swift has 1 .swift file
+  # against 9000+ .kt, and that marker is not this repo's stack. A root marker
+  # is the repo's own declaration and always counts. Outside a git work tree
+  # there is no tracked-file list, so the marker counts. Package manifests
+  # written in a source language (Package.swift) are not counted as source.
+  local _files="" _files_read=0 _ignored=""
+  _ma_share_ok() { # $1 = stack, $2 = extensions, $3 = hit path
+    case "$3" in "$root"/*/*) ;; *) return 0 ;; esac
+    if [ "$_files_read" -eq 0 ]; then
+      _files_read=1
+      _files=$(git -C "$root" ls-files 2>/dev/null | grep -iE "\.($MA_STACK_SOURCE_EXTS)\$" |
+        grep -vE '(^|/)Package(@[^/]*)?\.swift$')
+    fi
+    [ -n "$_files" ] || return 0
+    local total n
+    total=$(printf '%s\n' "$_files" | grep -c .)
+    [ "$total" -ge "$MA_STACK_MIN_FILES" ] || return 0
+    n=$(printf '%s\n' "$_files" | grep -ciE "\.($2)\$")
+    [ $((n * 100)) -ge $((total * MA_STACK_MIN_SHARE)) ] && return 0
+    case " $_ignored " in *" $1 "*) return 1 ;; esac
+    _ignored="${_ignored:+$_ignored }$1"
+    _why="${_why:+$_why }ignored $1<-${3#"$root"/}($n of $total source files)"
+    return 1
+  }
+
+  local _why="" hit row stack pat depth exts
 
   # --- table markers ----------------------------------------------------
-  while IFS=: read -r stack pat depth; do
+  while IFS=: read -r stack pat depth exts; do
     [ -n "$stack" ] || continue
     case " $MA_STACKS " in *" $stack "*) continue ;; esac
     hit=$(_ma_has "$pat" "$depth")
-    [ -n "$hit" ] && _ma_add "$stack" "${hit##*/}"
+    [ -n "$hit" ] && _ma_share_ok "$stack" "$exts" "$hit" && _ma_add "$stack" "${hit##*/}"
   done <<EOF
 $MA_STACK_MARKERS
 EOF
@@ -150,11 +189,12 @@ EOF
       fi
     done
   fi
-  [ -n "$hit" ] && _ma_add "android" "${hit##*/}"
+  [ -n "$hit" ] && _ma_share_ok "android" "kt|java" "$hit" && _ma_add "android" "${hit##*/}"
 
   # --- web / backend, by dependency -------------------------------------
   local pkg
   pkg=$(_ma_has "package.json")
+  [ -n "$pkg" ] && ! _ma_share_ok "node" "js|jsx|ts|tsx|mjs|cjs|vue|svelte" "$pkg" && pkg=""
   if [ -n "$pkg" ]; then
     local is_web=0
     grep -qE "$MA_STACK_WEB_DEPS" "$pkg" 2>/dev/null && is_web=1
@@ -177,7 +217,7 @@ EOF
   done
   MA_STACKS="$ordered"
   MA_STACK_WHY="${_why:-no marker matched}"
-  unset -f _ma_has _ma_add
+  unset -f _ma_has _ma_add _ma_share_ok
   return 0
 }
 

package/pipeline/lib/unattended.mjs

@@ -61,6 +61,23 @@ export function runMode(state, env = process.env) {
   return { unattended, stateClaimsAutopilot, claimMismatch: stateClaimsAutopilot && !unattended };
 }
 
+/**
+ * The table above as one value for a consumer that needs both answers: `mode`
+ * is who can answer a question (only the environment decides it), `gatesActive`
+ * whether the quality gates run. Terminal autopilot is attended with the gates
+ * active: a person is present, but no confirmation is asked.
+ *
+ * @param {object|null|undefined} state
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {{mode: "attended"|"unattended", gatesActive: boolean}}
+ */
+export function runPosture(state, env = process.env) {
+  return {
+    mode: isUnattended(env) ? "unattended" : "attended",
+    gatesActive: gatesActive(state, env),
+  };
+}
+
 /**
  * The verdict a quality gate returns when the gates are off.
  *

package/pipeline/multi-agent-refs/features/repo-profile.md

@@ -0,0 +1,96 @@
+# Repo profile  -  how one repo works, derived once, read by every phase
+
+> **TLDR**  -  A local-only JSON file per repo that tells generic skills what this repo does differently: paths a bot owns, generated trees and their inputs, the commit subject convention, the exact CI commands, hooks that rewrite a commit. Derived from the repo itself, confirmed once in attended runs, honoured without asking in unattended ones. Script: `repo-profile.mjs`. Schema: `schemas/repo-profile.schema.json`.
+
+## Where it lives
+
+`~/.claude/projects/<slug>/repo-profile.json`, next to `figma-config.json`. The slug is the main checkout's absolute path with every non-alphanumeric character replaced by `-` (the host's own project-directory slug), so every worktree of a repo reads one profile. Written atomically at `0600`. Never inside the repo and never committed: the save refuses a path that resolves inside the repo root. It is not the learnings ledger's `<repo-profile>` prompt block; that one holds free-text learnings.
+
+An unattended run's OS sandbox denies writes under `~/.claude`, so when that write is refused (`EACCES`, `EPERM`, `EROFS`) the profile goes to `<unattended run root>/repo-profiles/<slug>/repo-profile.json` (`MA_UNATTENDED_RUN_ROOT`, else `~/.multi-agent-unattended`, the directory the sandbox's `allowWrite` names). An unattended run reads whichever of the two copies was derived last. When neither is writable the profile is used from memory for the run, `persisted` is `false`, and the run continues.
+
+## What it holds
+
+Every role is `{ value, source, evidence, confidence }`. `source` is `derived`, `confirmed` or `manual`; `evidence` is `file:line`, `commit:<sha>` or `git:<ref>`; `confidence` is `high`, `medium` or `low`. A `null` value means nothing was found and the consumer keeps its default.
+
+| Role | Derived from |
+|---|---|
+| `ownedPaths[]` | candidates from a 2000-commit window: directories (and single files) only `[bot]` authors or `--bot-pattern` touched, at least 3 commits. Each candidate (at most 50) is then checked against its whole history in one `git log`; one with any human commit narrows to the subdirectories and files inside it that only the bot ever touched. `basis: "history"` rules are at most `medium`. Plus workflow rules: `case` arms (a case `*` crosses `/`: a star-only segment becomes `**`, a last segment such as `*.swift` becomes `**/*.swift`; any other star inside a segment widens an owned arm to its literal directory plus `/**` and drops an exception arm) and `git diff/log/ls-files -- <paths>` pathspecs (git semantics kept, stored repo-relative without `./`), in workflows that name a bot in code or read one from `vars.*BOT*` / `*BOT_LOGIN`; `#` comments are stripped first, so a login in a comment is an example, not an owner. The owner is the bots that actually committed under the job's paths, else the ones it names. A history directory that a same-owner workflow glob only partly covers folds into that glob (`basis: "history+workflow"`, `high`). An `on.*.paths` trigger filter only says when a workflow runs and is never read as ownership. A `labels.*.name` check becomes `bypass.label` |
+| `generators[]` | files whose first 5 lines carry a comment stamp (`//`, `#`, `/*`, `<!--` followed by `generated by`, `auto-generated` or `do not edit`; a docstring does not count), grouped into the highest directory that is 90% stamped; any tracked `Generated/` directory; `input` is the common parent of the directories that change in the same commits, `sameCommit` is true at 80%; `command` is the CI step naming the stamp's tool with `2>&1` and `\| tee` removed; a step with `--check`, `--verify` or `--dry-run` is recorded as `check`, never as `command` |
+| `commit.format` | last 200 non-merge, non-bot subjects: ticket `prefix` / `suffix` / `none` by majority, its style (`[KEY-123]`, `KEY-123:`), whether a conventional scope is required. A trailing `(#123)` is the host's PR number and is ignored |
+| `repo.workBranch`, `repo.defaultBranch` | `pull_request: branches:` targets in workflows, else `push: branches:` targets, else the most active of the usual integration branches, remote or local; `origin/HEAD` |
+| `build`, `test`, `lint` | CI `run:` steps, exact flags kept, continuations joined; `high` when a pull request triggers the step or it appears twice; `-testPlan` values and `*.xctestplan` files; `package.json` scripts as a low-confidence fallback |
+| `accessors.*`, `di.*` | top-level types a generated localization / testing-id / token tree declares, ranked by `<Root>.<Seg>.<Seg>` usage outside it; the registrar suffix is the compound most files of the commonest `Registrar` / `Configurator` / `Assembly` / `Container` / `Module` family end in, read from the file names; its common method; the inject attribute. `--conventions <file>` or `--with-conventions <platform>` folds in `extract-conventions.sh` buckets |
+| `module`, `mock` | repeated module manifests as a glob; a module validator script or step; mock framework imports or a fixture tree; a `Custom*` tree beside a generated one. `mock.system` and `di.injectAttribute` count only files of the repo's dominant language and carry `file:line` evidence; otherwise they are `null` |
+| `hooks[]` | `.githooks/`, `scripts/git-hooks/`, `.husky/`, pre-commit and lefthook configs; side effects `amends-commit`, `stages-files`, `writes-files`, `network`; the script that sets `core.hooksPath` |
+| `requiredChecks[]`, `docs.authoritative[]`, `inRepoSkills[]` | workflow jobs with a `required` comment (always low); the documents `claude-md-links.mjs` admits from the repo's `CLAUDE.md` files (same bounds, evidence is the CLAUDE.md that points at it); `.claude/skills/*/SKILL.md` with `trigger: explicit` when `disable-model-invocation: true` |
+
+Derivation reads and never writes: one bounded `git log`, one whole-history `git log` limited to the owned-path candidates, one `git ls-files`, a 600-byte header per regular source file (symlinks, submodules and anything `lstat` does not call a regular file are skipped), one fixed-string `git grep` for accessor, inject and mock usage. Paths are read NUL-separated with `core.quotePath` off, so non-ASCII paths arrive as written. It stays within a few seconds on a 50k-file repo.
+
+## Run start: one call
+
+```bash
+node $HOME/.claude/scripts/repo-profile.mjs ensure --repo "$PROJECT_ROOT" --state "$STATE_FILE"
+```
+
+It prints `{action, mode, policy, gatesActive, path, persisted, writeError, confirmed, needsConfirmation, stale, report}` and persists nothing but the profile. Persist the result as `state.repoProfile = {path, action, mode, confirmed, staleReasons, ignored}` (`staleReasons` from `stale.reasons`, `ignored` from `report.ignored`). `path` is `null` and `persisted` is `false` when no location was writable.
+
+The mode comes from `lib/unattended.mjs` (`runPosture`): only `MULTI_AGENT_UNATTENDED=1` is unattended. Terminal autopilot (`state.autopilot`) is attended with the gates active: its profile is stored under `~/.claude`, it is never asked to confirm, and because nobody confirms anything it applies the unattended confidence policy (`policy` in the output), so owned paths and generators fail safe.
+
+| Situation | Unattended (`MULTI_AGENT_UNATTENDED=1`) | Terminal autopilot | Attended |
+|---|---|---|---|
+| no profile | derive, save as `derived`, continue | derive, save, continue | derive, save, ask once |
+| stale | re-derive, keep confirmed and manual roles, continue | same, continue | re-derive, keep them, ask again |
+| fresh, confirmed | use it | use it | use it |
+| fresh, never confirmed | use it | use it | ask once |
+
+Stale means: the stored `repoHead` is no longer an ancestor of HEAD, HEAD is more than 200 commits ahead of it (`--max-behind`), or any file under `.github/workflows/` changed between the two.
+
+**The confirmation (attended only).** Render the derived roles as a table (role, value, confidence, first evidence) and ask one question through the picker contract (`question`, `label`, `description` in `outputLanguage`, `header` English, at most 12 characters, `"Profile"`): confirm (Recommended), edit, or skip for this run. Confirm runs `repo-profile.mjs confirm`. Edit starts from `show`, sets the corrected values with `source: "manual"`, and writes the whole profile back through `save --from -`, which replaces the stored one as given: a manual value wins over a confirmed one and an entry left out is removed. Then confirm. Skip leaves the profile derived and asks again next run.
+
+## Consuming a field
+
+`repo-profile.mjs resolve <field>` applies the policy and prints `{use, value, reason, ignored}`:
+
+| Role state | Used? |
+|---|---|
+| `confirmed` or `manual` | yes, whatever the confidence |
+| `derived`, high | yes |
+| `derived`, medium | only where a wrong value fails safe: `ownedPaths`, `generators`, `commit.format` |
+| `derived`, low | no; the default is kept and the field is recorded as ignored |
+| `ownedPaths` entry with `basis: "history"` (no CI job enforces it) | attended: no until confirmed, recorded as ignored; unattended and terminal autopilot: yes, and listed in `report.historyOnly` |
+| `ownedPaths`, `generators` in an unattended run | always, even low and unconfirmed: blocking an edit a person can undo is safer than editing a path a bot overwrites or CI rejects |
+
+## Who reads it
+
+- **Phase 1 (plan)** runs `ensure`, cites `ownedPaths` and `generators` in the plan so no task writes into them, and reads `docs.authoritative` and `inRepoSkills` as repo guidance.
+- **Phase 2 (dev)** checks every target path against `resolve ownedPaths` and `resolve generators` before writing; an edit there moves to the generator's `input` or stops with the owner named. Its exit gate runs `owned-path-gate.mjs` (below) before the build, and a violation blocks the phase.
+- **Phase 3 (review)** re-runs the gate at Step 1.761 and merges its `findings[]` (`tag: owned_path`, `blocking`) into triage; `review-decision-gate.mjs` keeps them blocking on the `owned-path` basis.
+- **The agent commit hook** (`pre-commit-check.sh`) runs the gate on the commit's own paths: the index, plus what the same command stages (`git add <pathspec>`, `-A`, `-u`) and what `commit -a` or `commit <pathspec>` takes (`agent-guard.py --commit-scope`; without python3, every dirty and untracked file). A dirty file the commit leaves out is not judged. It passes `--state auto`, which finds the live run whose `worktreePath` is the checkout. A profile kept only in memory (`persisted: false`) gives the hook nothing to read; Phase 2 Gate 0 and Phase 3 Step 1.761 still check that run.
+- **Phase 4 (commit)** takes the ticket position and style from `resolve commit.format`; `none` keeps the default suffix unless the role is confirmed or manual. It reads `hooks[]`: a hook that `amends-commit` or `writes-files` means the SHA after `git commit` is re-read, never assumed.
+- **Phase 5 (report)** prints `repo-profile.mjs report`: which fields were derived, confirmed or manual, which were used, and which were ignored for confidence.
+
+## Owned-path gate
+
+`owned-path-gate.mjs` turns `ownedPaths[]` into a deterministic check. For each changed path an honoured entry's `glob` covers and none of its `except[]` globs does, it reports a violation unless every author of the change matches the entry's `owner` (the account's own sync), every author matches `bypass.author`, or the PR carries `bypass.label`. `owner` and `bypass.author` are regular expressions when anchored (`^` or `$`) and otherwise one literal name compared exactly; an unanchored value with regex syntax (`\`, `*`, `+`, `?`, `()`, `{}`, `|`) fails validation. A merge commit counts as changing only the files its author edited while resolving it.
+
+```bash
+node $HOME/.claude/scripts/owned-path-gate.mjs --repo "$WORKTREE" --base "origin/$BASE_BRANCH" --state "$STATE_FILE"
+```
+
+| Input | Change set | Authors |
+|---|---|---|
+| default | merge-base with the profile's `repo.workBranch`, else `repo.defaultBranch`, `origin/HEAD`, `origin/main`, `origin/master`, `main`, `master`, plus uncommitted and untracked files | commits since the merge-base; the local identity for uncommitted files |
+| `--base <ref>` | the default, from the merge-base with `<ref>` | same |
+| `--range <base>..<head>` | `git diff <base>...<head>` | commits of the range that touch the path |
+| `--staged` | the index | the local identity |
+| `--paths <a,b>` or `--paths -` | the list given (stdin: NUL or newline separated) | the local identity, or `--author` |
+
+The policy is the profile's own (`resolve ownedPaths`): attended runs honour confirmed, manual, high and medium entries, except a history-only one that is still derived, and list the rest in `ignored[]`; runs that ask nothing (unattended, or terminal autopilot through `--state`) honour all. The commit hook passes the worktree's `agent-state.json` as `--state` when one exists. Without a stored profile, attended exits 0 with `skipped: true` and `note: "no repo profile, gate skipped"`; a run that asks nothing derives one first through `ensure`, which stores it under `~/.claude` or the unattended run root (or keeps it in memory) and never writes into the repo. Labels come from `--pr-labels a,b`; when a violation's bypass label is not among them and `gh` is installed, the PR's labels are read once, read-only, and a missing `gh` or PR changes nothing (`--no-gh` turns it off).
+
+Globs: `**` spans any number of segments, `*` and `?` stay inside one segment, `[...]` is a class, and a glob with no wildcard names a file or a whole directory. Output (stdout, or `--out <file>`): `{violations: [{path, glob, owner, evidence, confidence, fix}], exempt, findings, ignored, checked, mode, skipped, profileSource, profileAction}`. `fix` names where the change belongs: the matching `generators[].input` and `command`, the `resourceSource.authoring` commands, or the next sync. Exit 0 clean or skipped, 1 violations, 2 usage or environment error.
+
+The commit hook computes the profile path itself and reads the globs' literal prefixes with `sed`, so a commit that touches no owned prefix never starts node. No profile, no node or a gate that cannot run lets the commit through with one stderr line; a violation blocks it with exit 2.
+
+## Commands
+
+`derive` (print a draft), `save [--from <file|->] [--replace]`, `confirm`, `ensure [--max-behind <n>]`, `show`, `get <field>`, `resolve <field>`, `report`, `path`, `--help`. All take `--repo <path>`. `--history` and `--max-behind` must be positive integers. Exit `2` means no stored profile.

package/pipeline/multi-agent-refs/features/review-decision.md

@@ -30,11 +30,12 @@ exits 0 and writes neither the triage file nor the state.
 An `accepted[]` finding of severity `blocking` keeps its severity only when
 one of these holds:
 
-| Basis | What has to be true |
-|---|---|
-| `corroborated` | at least two independent reviewer outputs of the iteration carry a `blocking` finding that is the same finding |
-| `failing-test` | its `verification` (Step 3.7, `verify-by-test.md`) is `confirmed`, and `evidencePath` names a non-empty log inside the checkout that shows a failing test and no pass |
-| `test-integrity` | it is the finding `test-integrity-gate.mjs` produced for that file: a command's output, not a model's |
+| Basis            | What has to be true                                                                                                                                                                                                                                 |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `corroborated`   | at least two independent reviewer outputs of the iteration carry a `blocking` finding that is the same finding                                                                                                                                      |
+| `failing-test`   | its `verification` (Step 3.7, `verify-by-test.md`) is `confirmed`, and `evidencePath` names a non-empty log inside the checkout that shows a failing test and no pass                                                                               |
+| `test-integrity` | it is the finding `test-integrity-gate.mjs` produced: the same file and the same `tag` (or the same fingerprint), a command's output, not a model's                                                                                                 |
+| `owned-path`     | it is the finding `owned-path-gate.mjs` produced, matched the same way (an edit to a path the repo profile says an automated account owns), for the same reason. A reviewer's own blocker on a file the gate also flagged is not the gate's finding |
 
 Anything else is lowered to `important`. It stays in `accepted[]`: triage
 judged it real and in scope, so the rework still fixes it, it just no longer
@@ -100,6 +101,7 @@ result, before Step 3.8:
 ```bash
 node "$HOME/.claude/scripts/review-decision-gate.mjs" "$TRIAGE_FILE" --state "$STATE_FILE" \
   --integrity "$WORKTREE/.pipeline/test-integrity.json" \
+  --integrity "$WORKTREE/.pipeline/owned-path.json" \
   --source "$WORKTREE/.pipeline/security-audit-$ITERATION.json" \
   --json > "$WORKTREE/.pipeline/review-decision-$ITERATION.json"
 RD_RC=$?
@@ -111,8 +113,11 @@ nothing); `security-audit-$ITERATION.json` is the file Step 2.7 writes when the
 audit runs (`security-audit.md`). Both are files and not process substitutions
 of a shell variable with a `{}` brace default: bash 3.2, the stock macOS
 `/bin/bash`, expands that to `{\}`, and unparseable input is exit 3.
-A missing or empty `--integrity` file means no test-integrity findings, and a
-missing or empty `--source` means the audit did not run.
+`owned-path.json` is the file Step 1.761 writes. `--integrity` repeats, one
+file per deterministic gate. Both gates always write their file, so a declared
+`--integrity` file that does not exist is unreadable (exit 3): the gate failed
+before writing. An empty one means no findings from that gate, and a missing or
+empty `--source` means the audit did not run.
 
 Merge the JSON into `state.reviewIterations[-1].reviewDecision` through
 `write-state.mjs`:
@@ -123,12 +128,12 @@ jq --slurpfile d "$WORKTREE/.pipeline/review-decision-$ITERATION.json" \
   | node "$HOME/.claude/scripts/write-state.mjs" "$STATE_FILE"
 ```
 
-| Exit | Ledger | The run |
-|---|---|---|
-| 0 | `pass` | continues with the rewritten triage |
-| 1 | `fail`: a rebuttal round ran | `gate-ledger.mjs park --outcome verification-failed --gate review-decision` |
-| 2 | nothing | usage error; fix the call |
-| 3 | `fail`: triage unreadable, or an accepted blocker with no reviewer record to check it against | parks the same way |
+| Exit | Ledger                                                                                        | The run                                                                     |
+| ---- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| 0    | `pass`                                                                                        | continues with the rewritten triage                                         |
+| 1    | `fail`: a rebuttal round ran                                                                  | `gate-ledger.mjs park --outcome verification-failed --gate review-decision` |
+| 2    | nothing                                                                                       | usage error; fix the call                                                   |
+| 3    | `fail`: triage unreadable, or an accepted blocker with no reviewer record to check it against | parks the same way                                                          |
 
 The gate records the verdict; it does not park. Parking is the explicit call:
 

package/pipeline/multi-agent-refs/features/stack-skill-routing.md

@@ -1,14 +1,24 @@
 # Stack skill routing  -  letting the toolkit plugin choose its own skills
 
-> **TLDR**  -  When a toolkit plugin is enabled, Phase 3 asks that plugin's own `index` skill which of its skills apply to this task, loads them before writing code, and records each into `state.telemetry.skillCalls[]`. The routing table lives in the plugin; the pipeline copies none of it, and does not keep a stack-to-plugin table either - it reads the enabled set.
+<!-- toc -->
+- [Why this exists](#why-this-exists)
+- [When it runs](#when-it-runs)
+- [Resolution](#resolution)
+- [The call](#the-call)
+- [Recording  -  what makes this checkable](#recording---what-makes-this-checkable)
+- [Failure modes, and why none of them halt](#failure-modes-and-why-none-of-them-halt)
+- [What this deliberately does NOT do](#what-this-deliberately-does-not-do)
+<!-- /toc -->
+
+> **TLDR**  -  Phase 2 (Dev) asks each kept toolkit plugin's own `index` skill which of its skills apply to this task, loads them before writing code, and records each into `state.telemetry.skillCalls[]`. The routing table lives in the plugin; the pipeline copies none of it, and does not keep a stack-to-plugin table either - it reads the enabled set, drops inherited toolkits that contradict the repo's detected stack, and puts the repo's own `.claude/skills` ahead of both. The step runs for every task; with no toolkit it is a recorded no-op.
 >
 > The same routing applies outside a run: `rules/outside-the-pipeline.md` carries it for ordinary sessions. One discipline, two callers; only the recording is run-specific.
 
 ## Why this exists
 
-Phase 3 dispatched to the toolkit plugin for exactly one case, `taskType === "component"` (see `component-dispatch.md`). Every other task  -  `bugfix`, `feature`, `refactor`, `chore`  -  had no skill dispatch at all: whichever skills the host happened to surface by description match were the ones that got used, and nothing recorded or required any of them.
+Component dispatch (`component-dispatch.md`) covers exactly one case, `taskType === "component"`. Without this step every other task  -  `bugfix`, `feature`, `refactor`, `chore`  -  would have no skill dispatch at all: whichever skills the host surfaced by description match would be the ones used, and nothing would record or require any of them.
 
-That is the dev-side half of the gap `features/skill-conformance.md` closes on the review side. Review now asks "was this built to the rules it was supposed to follow"; without this step, the answer for a non-component task was "there were no declared rules, because nobody chose any".
+That is the dev-side half of the gap `features/skill-conformance.md` closes on the review side. Review asks "was this built to the rules it was supposed to follow"; that question only has an answer when some rules were chosen.
 
 The fix is not a routing table in the pipeline. Each `ai-<platform>-toolkit` already ships one: an `index` skill whose description says *"Load this first when unsure which skill applies"*, holding a 30-plus row intent-to-skill map maintained alongside the skills it points at. A second copy in this repo would drift the moment the plugin shipped a new skill, and the pipeline's copy would be the stale one.
 
@@ -16,34 +26,154 @@ So the pipeline's job is to **ask**, not to know.
 
 ## When it runs
 
-Phase 3 pre-flight, before any code is written, for **every** `taskType`. Component tasks keep their dedicated dispatch in `component-dispatch.md`; this step runs in addition, because the reference skills (architecture, naming, file placement, tokens) apply to a component build too.
+Phase 2 (Dev) pre-flight, before any code is written, for **every** `taskType` and every run, whether or not a toolkit is enabled: the unattended marketplace fallback (step 4 below) exists precisely for the run that has none. Component tasks keep their dedicated dispatch in `component-dispatch.md`; this step runs in addition, because the reference skills (architecture, naming, file placement, tokens) apply to a component build too.
 
 ## Resolution
 
-**Read the enabled set; do not keep a stack table.** Every `@multi-agent-plugins`
-toolkit enabled for this repo is a candidate, and each one ships its own `index`.
-The effective set is the repo's `.claude/settings.json` `enabledPlugins` over
-`~/.claude/settings.json`; `/multi-agent:stack` is what writes it.
+**Read the enabled set, filter it by the repo's stack; do not keep a stack table.**
+Candidates come from one resolver, run before the index call. The task text goes
+through a file, never through a shell string: write the task title and one-line
+intent to `$TASK_FILE` with the Write tool, then
 
-This replaced a `stack -> toolkit` table, and the reason is worth keeping. That table
-mapped `ios` and `android` and sent everything else to "no toolkit" - but six plugins
-ship an `index`, so a React or backend repo was told it had no toolkit while its
-plugin sat enabled with a routing table inside it. A table has to be widened every
-time a toolkit ships; the enabled set never goes stale, because it IS the answer to
-"what is on here".
-
-`ai-common-toolkit` and `ai-analyst-toolkit` are enabled everywhere and are always
-candidates - neither is stack-specific. A corporate variant (`ai-ios-engineering-toolkit`
-and friends) is a candidate too when a repo enables only it: it is in `enabledPlugins`
-like any other, which is the whole point of reading the set instead of naming names.
-
-Nothing enabled is not an error: a repo whose stack was never selected legitimately has
-no toolkit. Record the no-op with the enabled set that was read, so "none applied" is
-distinguishable from "never looked".
-
-**Not enabled is not an error here**, unlike component dispatch: a repo whose stack was never selected legitimately has no toolkit, and halting would make the pipeline unusable there. Record the no-op and continue. Every stack now has a toolkit, so "no toolkit" means the stack was never selected, not that none exists for it.
+```bash
+node $HOME/.claude/scripts/skill-candidates.mjs resolve --dir "$PROJECT_ROOT" \
+  --state "$STATE_FILE" --task-file "$TASK_FILE"
+```
 
-Two marketplaces may ship the same toolkit name (a public one and a corporate one). Resolve whichever is enabled and record its **name and version** in the ledger entry, because the routing table and the skill set differ between versions  -  a finding that cites a skill has to be traceable to the version that defined it.
+`--task -` reads the same text from stdin. `--task "<text>"` still takes a literal,
+but ticket titles are untrusted input and a literal puts them inside a shell
+command, so no pipeline document uses it.
+
+Pass `--state "$STATE_FILE"` inside a run so autopilot is recognised. It prints JSON
+with `mode`, `toolkits[]` (kept, each with `role`, `reason`, `source`, `version`),
+`excluded[]` (each with the reason it was dropped), `unscoped[]`, `hints[]`,
+`fallbacks[]`, `repoSkills[]`, `rejectedRepoSkills[]`, `repoMatches[]` (when a task
+is given), `overlaps[]`, `decisions[]` and `detection`. Write `mode`, `toolkits`,
+`excluded`, `unscoped`, `hints` and `fallbacks` to `state.telemetry.skillRouting` as
+they are, so "none applied" is distinguishable from "never looked", an exclusion can
+be traced to its cause, and Phase 5 can report it.
+
+1. **Enabled set.** The effective `enabledPlugins` is read from four layers, widest
+   first, the later layer winning per plugin, and `false` removes a plugin:
+   the user's `settings.json`, the user's `settings.local.json` (both under
+   `CLAUDE_CONFIG_DIR`, else `~/.claude`), the repo's `.claude/settings.json`, and the
+   repo's `.claude/settings.local.json`. The two user layers are *inherited*
+   (`source: "global"` / `"global-local"`); the repo layers are the repo's own
+   choice (`"repo"` / `"repo-local"`). Managed (enterprise) settings are not read.
+   `/multi-agent:stack` is what writes the repo layers. Only toolkits are candidates:
+   a plugin named `*-toolkit`, or one that ships a `skills/index/SKILL.md`.
+2. **Stack filter, inherited toolkits only.** A repo that never ran
+   `/multi-agent:stack` inherits the user-level set, which was chosen for some other
+   repo. So a toolkit from a user layer is checked against the stacks detected in
+   this repo (`lib/stack-detect.sh` plus `schemas/stack-adapters.json`, the same
+   detection the build and test adapters use). A toolkit's stacks are read from its
+   own name (`ai-<words>-toolkit`) and any `stack` / `stacks` / `keywords` in its
+   `plugin.json`, matched against the stack words the pipeline already knows: adapter
+   ids, the coarse stacks, and the aliases in `_stack-routing.mjs` (`web` and
+   `frontend`, `mobile` for iOS plus Android). No list of stacks lives in the resolver,
+   so a new `ai-<x>-toolkit` whose `<x>` is an adapter id is filtered correctly with no
+   code change.
+   - A toolkit whose stack words intersect the repo's is kept with `role: "stack"`.
+     Multi-stack repos (iOS plus a backend, Android plus web views, monorepos) keep
+     every matching toolkit.
+   - A toolkit whose name marks another stack only (`-ios-` in a Gradle-only repo) is
+     excluded, and `excluded[].reason` names both sides and the detector's evidence.
+   - An inherited toolkit whose name and `plugin.json` mark **no** stack (a vendor
+     utility plugin) says nothing about this repo. It is kept with `role: "common"`
+     only when it ships an `index`; otherwise it goes to `unscoped[]` and is not
+     routed to. An unattended or autopilot run never loads an `unscoped[]` toolkit;
+     an attended run loads one only when the user names it.
+   - A toolkit enabled in the repo's own settings is never filtered and has
+     `role: "stack"` (`"common"` for the always-on pair). That is an explicit per-repo
+     choice, and detection does not override it.
+   - Inconclusive or empty detection applies no filter to toolkits that mark a stack,
+     and `detection.filter` says why.
+   - Detection counts a marker below the repo root (a `Package.swift` two levels
+     down) only when that stack's language is at least 1% of the tracked source
+     files (`git ls-files`, from 50 tracked source files up). A subtree copied into a
+     Kotlin app, with one `.swift` file against thousands of `.kt`, is therefore not
+     iOS, and `detection.why` names the ignored marker. A root marker always counts.
+3. **Always-on.** `ai-common-toolkit` and `ai-analyst-toolkit` are never filtered and
+   have `role: "common"`; neither is stack-specific.
+4. **Hint, never a substitute.** When a detected stack has no kept toolkit, `hints[]`
+   carries `enable ai-<stack>-toolkit with /multi-agent:stack <stack>`. What happens
+   next depends on `mode`, which the resolver takes from `lib/unattended.mjs`, the
+   helper the rest of the pipeline uses (`MULTI_AGENT_UNATTENDED=1` is `unattended`;
+   otherwise `--state` with `autopilot: true` is `autopilot`; otherwise `attended`):
+   - **Attended**: show the hint once in the run log and continue with what is enabled.
+   - **Unattended or autopilot**: nobody can run `/multi-agent:stack`, and the
+     unattended policy forbids writing `.claude/` inside the repo. `fallbacks[]` then
+     names a local marketplace clone that carries the toolkit. Clones are found from
+     the host's `known_marketplaces.json` and, in addition, by scanning
+     `~/.claude/plugins/marketplaces/`; the plugin directory comes from each clone's
+     `marketplace.json`. Load its `index` (the `index` path) and the skills it routes
+     to **read-only** from `skillsDir`; never enable the plugin and
+     never write any settings file. Record each loaded skill with `source: "marketplace-fallback"`,
+     `toolkit` and `version` (from that clone's `plugin.json`; `marketplaceSkillCall()`
+     builds the entry), and put the entry's `reportLine` in the run report so the user
+     sees that the repo should enable the stack. When no clone carries it, the entry
+     has `gap` instead: record it and continue. The run never blocks on this.
+   - **Both modes**: never route the task to another stack's toolkit instead.
+5. **Repo-local skills.** `<repo>/.claude/skills/<name>/SKILL.md` are candidates
+   too. The resolver reads each one's `name` and `description`, and marks it
+   explicit-only when its frontmatter has `disable-model-invocation: true`, its
+   description asks for explicit invocation, or a line of the repo's CLAUDE.md that
+   names it says so ("only on explicit request"). Route them by the same intent
+   decision the index step makes, on the task title plus intent: `repoMatches[]` is
+   a word-overlap pre-ranking to start from, not the final word. An explicit-only
+   skill is loaded only when the task invokes it by name: `/name`, `` `name` `` or
+   "skill name". The bare word is not enough, so a skill called `release` does not
+   fire on "Fix crash in release notes".
+6. **Real paths.** A repo `SKILL.md` (or its directory) that is a symlink resolving
+   outside the repo is not read; it is listed in `rejectedRepoSkills[]`. A
+   marketplace plugin directory, its `skills/` or its `index` that resolves outside
+   its clone is treated as absent, so the fallback records a `gap`.
+
+### Precedence
+
+When two candidates cover the same ground, the first wins:
+
+1. **Repo-local skill** (`.claude/skills/<name>`) - the repo's own rule. When it has
+   the same name as a toolkit skill, it replaces that skill for this repo, and
+   `decisions[]` records which toolkit skill it shadowed.
+2. **Detected-stack toolkit skill** - whatever a `role: "stack"` toolkit's `index`
+   routes to.
+3. **Common toolkit** (`ai-common-toolkit`, then `ai-analyst-toolkit`, then any
+   stackless toolkit kept in the common role).
+
+Two kept toolkits can ship a skill of the same name, typically a public toolkit and a
+vendor variant for the same stack. The resolver picks one owner per overlapping name
+with one deterministic rule, and records each choice in `overlaps[]`
+(`skill`, `winner`, `losers`, `rule`) and as a line in `decisions[]`:
+
+1. a repo-local skill of that name wins over every toolkit;
+2. otherwise the `stack` role wins over the `common` role;
+3. otherwise the toolkit enabled at the **narrowest scope** wins:
+   repo `settings.local.json`, then repo `settings.json`, then user
+   `settings.local.json`, then user `settings.json`;
+4. a remaining tie goes to a toolkit the pipeline itself publishes, so an outside toolkit never wins a tie by how its name sorts; between two outside toolkits, the name that sorts first.
+
+Each toolkit's own `index` and `help` are its entry points, not competing skills, and
+are never counted as an overlap. When the index of the losing toolkit routes to an
+overlapping name, load the winner's skill of that name instead. The rule does not try
+to judge which variant knows more about a topic; a repo that wants the other variant
+enables it at a narrower scope.
+
+No flow requires a particular toolkit. A corporate or otherwise differently-named
+variant that is enabled is one more candidate, kept only if its name matches the
+repo's stack like any other; it is never required, and its absence is never an
+error. Two marketplaces may ship the same toolkit name: resolve whichever is enabled
+and record its **name and version** (the resolver reads both from the host's
+installed-plugin record), because the routing table and the skill set differ between
+versions and a finding that cites a skill has to be traceable to the version that
+defined it.
+
+Nothing enabled is not an error: a repo whose stack was never selected legitimately
+has no toolkit. Record the no-op with the enabled set that was read.
+
+**Not enabled is not an error here**, unlike component dispatch: halting would make
+the pipeline unusable in a repo whose stack was never selected. Record the no-op and
+the hint, and continue.
 
 ## The call
 
@@ -57,28 +187,44 @@ Emit one progress line per loaded skill per `progress-contract.md`, so the user
 
 ## Recording  -  what makes this checkable
 
-Append one `state.telemetry.skillCalls[]` entry per skill actually loaded:
+Append one `state.telemetry.skillCalls[]` entry per skill actually loaded, with `phase: 2`. A toolkit skill:
 
 ```json
-{"skill": "ai-ios-toolkit:reference/architecture", "phase": 3,
- "targetFiles": ["Domains/Checkin/Sources/CheckinScene.swift"],
+{"skill": "ai-ios-toolkit:reference/architecture", "phase": 2,
+ "targetFiles": ["Sources/Feature/FeatureScene.swift"],
  "routedBy": "ai-ios-toolkit:index@0.13.0", "timestamp": "<ISO-8601>"}
 ```
 
+A repo-local skill carries `source: "repo"` and `routedBy: "repo:.claude/skills"`
+(`repoSkillCall()` in `skill-candidates.mjs` builds it):
+
+```json
+{"skill": "fix-bug", "source": "repo", "phase": 2,
+ "targetFiles": ["Sources/App/LoginScene.swift"],
+ "routedBy": "repo:.claude/skills", "timestamp": "<ISO-8601>"}
+```
+
 `routedBy` names the index and version that chose it. That is the difference between "the model happened to read a skill" and "the toolkit said this skill governs this task".
 
-What Phase 4 actually does with it, precisely: Step 1.78 lists these entries in the manifest under `ledger.routedByToolkit`, so a reviewer and the Phase 5 report can see which skills the project's own toolkit selected. It does **not** give them extra weight in the coverage maths. The deterministic resolver stays primary because an unrecorded load and no load are indistinguishable in state, and no `routedBy` tag changes that  -  the tag says who chose the skill, not that the code honoured it.
+Usage reporting (`scripts/usage-report.mjs`) never sends a repo-local skill's name, which the repo's owner chose: it sends the constant `repo-local`. A `marketplace-fallback` entry keeps its name only when the toolkit is one the public marketplace carries, and is sent as `marketplace-fallback` otherwise.
+
+What Phase 3 (Review) does with it, precisely: Step 1.78 lists these entries in the manifest under `ledger.routedByToolkit`, so a reviewer and the Phase 5 report can see which skills the project's own toolkit selected. It does **not** give them extra weight in the coverage maths. The deterministic resolver stays primary because an unrecorded load and no load are indistinguishable in state, and no `routedBy` tag changes that  -  the tag says who chose the skill, not that the code honoured it.
 
 ## Failure modes, and why none of them halt
 
 | Situation | Behaviour |
 |---|---|
-| No toolkit for this stack | recorded no-op, continue |
+| No toolkit for this stack | recorded no-op plus the `hints[]` entry, continue |
+| No toolkit for this stack, unattended or autopilot | read it read-only from a marketplace clone (`fallbacks[]`), or record the `gap`, continue |
+| An inherited toolkit marks another stack | excluded with its reason in `excluded[]`, continue |
+| An inherited toolkit marks no stack and ships no index | listed in `unscoped[]`, not routed to, continue |
+| Two toolkits ship the same skill name | one owner per name by the precedence rule, recorded in `overlaps[]`, continue |
+| A repo skill or marketplace plugin dir is a symlink out of its root | not read (`rejectedRepoSkills[]`, or a fallback `gap`), continue |
 | Toolkit not enabled in this repo | recorded no-op, continue (component dispatch still halts for its own case) |
 | `index` resolves but routes to a skill that does not exist in this version | record the miss with the version, load the rest, continue. A stale row in a plugin's table must not stop a run |
-| `index` itself does not resolve | record and fall back to the host's own description matching, which is the pre-v14.1.0 behaviour  -  no worse than before |
+| `index` itself does not resolve | record and fall back to the host's own description matching  -  no worse than having no routing step |
 
-Nothing here blocks Phase 3. What is downstream is visibility, not enforcement: routed skills appear in the manifest's `ledger.routedByToolkit`, and a task that recorded nothing shows up as `ledgerSource: derived` with its coverage gap stated. Enforcement over rule IDs is the registry's job (`features/skill-conformance.md`), not this step's.
+Nothing here blocks Phase 2. What is downstream is visibility, not enforcement: routed skills appear in the manifest's `ledger.routedByToolkit`, and a task that recorded nothing shows up as `ledgerSource: derived` with its coverage gap stated. Enforcement over rule IDs is the registry's job (`features/skill-conformance.md`), not this step's.
 
 ## What this deliberately does NOT do