@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/CHANGELOG.md

@@ -14,6 +14,316 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [19.0.0] - 2026-09-18
+
+Major, because phase numbers are the contract and they moved. Eight phases
+became six: two of the eight were doing the same work twice, and the count
+itself was guarded by nothing.
+
+Full reasoning, mapping and rejected alternatives:
+[ADR-0014](./docs/adr/0014-six-phase-consolidation.md).
+
+### Changed
+
+- **Six phases.** `0 Init`, `1 Plan`, `2 Dev`, `3 Review`, `4 Commit`,
+  `5 Report`. Analysis and Planning were already one decision - the depth
+  picker skipped them together and `onlyDevelop` described them as one unit -
+  and they are one phase now. Review Stage 1 became Dev's exit gate, which is
+  what removes the second build: Dev built and tee'd a log, then Review built
+  again, and nothing consumed the difference. The user test moved inside
+  Review, keeping its waiting state.
+- **`pipeline/schemas/phases.json` is the phase contract.** The list existed as
+  eight independent copies, none derived from another. The generator, the run
+  index, the metrics logger and the token budget read it now, and comparison
+  thresholds that used to be literals (`phase >= 6` for "waiting on you", the
+  Short-run boundary) are named fields in it.
+- **`smoke-phase-contract.sh`** is the gate that never existed. The phase count
+  appeared in 91 places across 40 files with nothing holding any of them; the
+  command count, the jq count and the persona count all had gates. It derives
+  the count from the contract and checks the generator's output, the token
+  budget, the state-schema bounds, every shipped surface that states a count,
+  the progress fractions in sample output and the named thresholds. Verified
+  both ways: a deliberately wrong contract fails it.
+- **`smoke-no-mcp-in-dev-phases.sh` keeps `phase >= 2`, and the gate now
+  asserts that it is unchanged.** Figma MCP was reachable only in Analysis (1);
+  Analysis is inside Plan (1). The permitted set `{0, 1}` is identical either
+  way, so the threshold surviving a renumbering is a result of the mapping
+  rather than an oversight - and an edit that "corrects" it would widen access.
+- **Analysis has one pipeline.** Lite mode is removed. It chose sections from a
+  fixed list scored on three signals while Locked 2 chooses them from evidence,
+  and the two disagreed in both directions: a small feature with rich business
+  rules lost Section 15 because it was not on the list, and a feature with no
+  API contract kept Section 9 because it was. 37 Locked decisions became 36.
+- **Locked 2's numbering clause was wrong and is corrected.** It said numbering
+  re-flows `1..N`; Locked 30 threads ids across the document BY NUMBER
+  (`Section 15.1`, `Section 4.4`), so a re-flowed document sends every one of
+  those references to the wrong section. No emitted document ever re-flowed.
+  A rendered section keeps its canonical number, gaps included, and the
+  validator now checks what actually holds: numbers inside the template range,
+  ascending, no repeats.
+
+### Added
+
+- **`/multi-agent:model`** turns the top rung on or off AND realigns
+  `costBudget.pricingModel` in the same write. The switch existed; the command
+  did not, and the pricing field it must move with was left to the user to
+  remember. It reports what the switch means on the host it runs on: a live
+  switch on Claude Code, a status report on Copilot CLI and Codex CLI.
+- **`/multi-agent:route-on` · `:route-off` · `:route-status`** - policy-driven
+  model routing, shipping disabled. `scope` has no `host-session` member and
+  the schema enforces that: rewriting the host's base URL would route the
+  user's whole session, including work unrelated to this pipeline. `route-off`
+  keeps the rules, so `route-on` does not re-ask. `route-status` prints the
+  honest limit every time - a subagent cannot be sent to a non-Anthropic model,
+  because subagent dispatch belongs to the host.
+- **`docs/facts.json`**, generated by `pipeline/scripts/gen-facts.mjs`: the
+  phase, command, skill and tool counts, derived rather than written. The
+  website read its own copies and said "8 faz + 51 komut" while the repo had
+  six phases and sixty commands. The tool count is asked of the toolkit's own
+  `tools/list` rather than counted out of its source, because three tool
+  families live in modules the main file only spreads in - a regex over
+  `index.js` returns 2 when the answer is 99.
+- **`prefs.schema.json` moves to 2.7.0, and the shipped template moves with
+  it.** The template had been left at 2.6.0, which
+  `smoke-schema-validation.sh` catches by design: a fresh install that starts
+  behind the migration target makes an old entry in the migrator's accepted set
+  load-bearing purely to rescue the template. 2.7.0 removes the Lite value from
+  `analysisPhase.mode` and declares `global.modelRouting`, which the template
+  now ships explicitly disabled rather than leaving absent - a default that is
+  written down is one a reader can find.
+- **The description-surface ceiling moves 86,500 -> 88,000**, and this is where
+  that has to be said. Four commands with a shared/core twin each is eight
+  descriptions; the average held at 316 against its own 420 ceiling, which is
+  the condition the gate's convention names for a raise rather than a trim -
+  the surface grew because there are more commands, not wordier ones. The
+  fixed per-run load was a different answer: it went 122 bytes over its 60,000
+  ceiling and the bytes were reclaimed from prose rather than the ceiling
+  raised, which is what that gate's message asks for in as many words.
+- **`smoke-six-phase-run.sh`** drives phase-tracker.sh through a synthetic run
+  and asserts what a live run would show: six tiles named from the contract, no
+  tile above 5, the `Phase 2 Dev` line shape, a sub-step that registers under
+  its parent phase rather than as a seventh tile, a token count and a start
+  timestamp for the cost and elapsed suffixes, and a state file that validates
+  at 0..5 while `currentPhase: 6` is rejected. It says plainly what it does not
+  cover: that Review does not build a second time is an assertion about a model
+  following a document, and only a live run's `.build.log` mtime can show it.
+  Verified both ways - a seventh phase in the contract fails it.
+- **A facts gate on the website** (`tests/facts-consistency.test.ts`). It does
+  not check that the copied `facts.json` is fresh - CI has no pipeline
+  checkout, that is `sync-facts.mjs --check` on a machine that does. It checks
+  what actually failed: that no component states a phase count or a phase
+  number that disagrees with the contract. Copy may say "6 phases"; it may not
+  say a different number. Verified both ways.
+- **`metrics.jsonl` carries `phaseSchema`.** The file is append-only across a
+  renumbering, so `phase: 3` means Dev in a pre-v19 row and Review in a post-v19
+  one. Lines without the field are generation 1. `pipeline/lib/phase-schema.mjs`
+  resolves both, and the two aggregators that compared phase numbers to literals
+  go through it.
+
+### Migration
+
+- **`state-2.1.0-to-2.2.0.mjs`** maps `0→0, 1→1, 2→1, 3→2, 4→3, 5→3, 6→4, 7→5`.
+  Two sources can collide onto one `phases{}` key: furthest-along status wins,
+  `retryCount` takes the MAX (the schema caps it at 3, so a sum would emit an
+  invalid state), `files[]` union, earliest start, latest finish. It also
+  repairs four defects the live corpus already carried - `completed` →
+  `complete`, `awaiting-user-test-main-checkout` → `awaiting_input`, and
+  explicit defaults for a missing `currentPhase` or `status`. Measured on the
+  62 real state files: **52 valid before, 62 after.**
+- **`prefs-2.6.0-to-2.7.0.mjs`** rewrites `analysisPhase.mode` from `auto` or
+  `lite` to `full`. The key is kept rather than deleted, so a file that set it
+  stays valid.
+
+### Fixed
+
+- `migrate-prefs.mjs` read its target version from a literal that had drifted
+  behind the schema. It reads the schema now, as do the two gates that were
+  checking against their own copies of it.
+- `phases.md` carried a second token-budget table whose total said 17,000 while
+  the enforced file said 63,150 - wrong by a factor of four, for most of the
+  project's life, guarded by nothing. The numbers are gone; the enforced source
+  is named instead.
+- `validate-analysis-doc.mjs` gated one half of Locked 2 and not the other. The
+  one emitted document available rendered `1..10, 12, 16, 20, 21` and nothing
+  looked.
+- Eight pieces of dead code on the website, found by the linter rather than by
+  grep - which had already been wrong three times about this repo.
+- **The phase bound is generation-aware, and it had to be.** Tightening
+  `currentPhase` to 0..5 marked every pre-v19 run log invalid - a run that
+  finished at phase 7 in October was correct when it was written, and a
+  validator that calls correct history invalid is one people learn to ignore.
+  A file stamped 2.2.0 or later is bounded 0..5; anything older, including the
+  files that predate stamping entirely, is bounded 0..7 and says so in the
+  error text. The same decision `metrics.jsonl` got: label the generation, do
+  not rewrite history. The tightening still bites where it matters - phase 7 on
+  a file claiming 2.2.0 is exactly what a skipped migration produces, and that
+  is rejected. Measured on the live corpus: 2 valid of 16 before, 11 of 16
+  after, and the 5 that remain were already invalid for reasons the plan had
+  recorded (no `currentPhase` at all, non-object phase values).
+- `validate-state.mjs` did not check `retryCount`. The schema caps it at 3 and
+  four documents call 3 a hard kill, so `retryCount: 4` was a state that every
+  document forbade and every validator accepted. The bound is checked now. The
+  limit is named rather than overstated: this closes the validation boundary,
+  it does not stop the loop - that stays prose.
+- **`phase-banner.sh` still had eight labels**, and it is the banner every
+  phase prints. Its table is bare words - `en:4) echo "Review"` - so all three
+  sweeps walked past it: they looked for `Phase 4 Review`, `4:Review` and
+  `Phase 4: Review`, and none of those spellings appear in it. It is now six
+  labels in both languages, and `smoke-phase-contract.sh` check 14 compares
+  every one against the contract and rejects a label above the last id, so the
+  one copy of the phase list that nothing derives is at least checked.
+- A third spelling of a phase reference, `Phase N: Name`, which the first sweep
+  could not see: its rules matched `Phase 3 Dev` and the tracker tuple `3:Dev`,
+  and the colon form sits between them. It had left the canonical label table in
+  `skills/shared/core/multi-agent/SKILL.md` reading eight rows with six-phase
+  labels, and `/multi-agent:local` listing both a Phase 4 Review and a Phase 4
+  Commit. Fifteen files, corrected by name match rather than by number.
+- The golden-task fixtures are named for the phases that produce them, so they
+  moved too: `phase-2-plan.json` -> `phase-1-plan.json`, `phase-4-review.json`
+  -> `phase-3-review.json`, `phase-4-triage.json` -> `phase-3-triage.json`.
+- A doc sweep of 166 files in the repo and 68 in the source tree, none of which
+  the eight-phase plan had listed. Release history is deliberately excluded:
+  `CHANGELOG`, the `ROADMAP` "Previous Release" sections and
+  `docs/token-budget-history.md` keep the numbers their versions shipped with,
+  and four ADRs carry a pointer to ADR-0014 instead of being rewritten, because
+  an ADR records what was decided rather than what is true today.
+
+### Removed
+
+- **The engagement page** (`src/app/_nisan`, its API routes and its admin
+  panel) on the website. The 16 RSVP rows were exported before anything was
+  deleted and **the `rsvp_entries` table is kept** - removing code does not
+  remove data, and dropping the table is a separate decision.
+
+---
+
+## [18.0.0] - 2026-09-17
+
+Major, for two behaviour changes rather than a renamed command: a run's state now
+has ONE canonical directory, and four publish paths refuse to send when the leak
+gate cannot be loaded.
+
+### Added
+
+- **`multi-agent-pipeline verify`** answers "is this install the thing that was
+  published". The install is a copy, and from the moment `install.js` writes it
+  the two halves drift independently: an edit in the installed tree is behaviour
+  with no source, and a file the installer skipped is a script the docs describe
+  and nobody has. `manifest.json` (SHA-256 per shipped file, version, source
+  commit) is built at pack time by `prepack` and never committed - a manifest in
+  git is stale one commit after it is written, and a stale manifest reports
+  honest edits as tampering.
+
+  `commands/` is compared by presence, not bytes, because `install.js` rewrites
+  each description into the user's `outputLanguage`: measured here, all 57
+  command files differ and 56 of them differ by nothing else. Dev-only files are
+  excluded, or 252 smokes and linters read as "the installer skipped this".
+
+  What a green result proves is stated in the output's own reference: the bytes
+  match what the publisher recorded. Not who published them - the manifest, the
+  signature and the verifier travel in the same tarball, so provenance belongs
+  to npm's integrity field. Signing is optional, and an unverifiable signature
+  says so rather than claiming valid.
+
+- **`cost-analyze.mjs`** - projection, anomaly, burn and diff. `cost-budget-check`
+  watches one run against one ceiling, which is blind to both ways a budget
+  actually empties: a drift no single run trips, and one session that burns a
+  week in an hour while every run stays under its cap.
+
+  The series is not where the schema says it is. `tracker-state.json` carries
+  per-phase token fields that are written only when a phase reports them; of 98
+  trackers on a working machine, zero carry any. The dense series is the host's
+  own transcripts, so that is what this reads - and the consequences are printed
+  rather than buried: it covers everything Claude Code did on the machine, the
+  figures are LIST-price estimates rather than a bill, and a host with no
+  transcripts reports UNMEASURED instead of zero.
+
+  Anomalies use the median and the MAD, because the expensive session the check
+  exists to find is the observation that inflates a mean and a standard
+  deviation - it hides inside the statistic measured against it.
+
+- **`install --unattended`** writes a documented permission profile, and prints
+  it with a reason per line before writing. autopilot passes
+  `--permission-prompts none`, which stops Claude Code asking and grants
+  nothing; on a fresh machine the run stops at the first tool call with no
+  prompt for anyone to answer, which is indistinguishable from an empty queue. A
+  default install still writes no permissions at all.
+
+- **`doctor --profile=server`** adds four checks that only matter when nobody is
+  at the keyboard: the unattended contract, the permission posture, the
+  scheduler, and the keychain. The default run is unchanged - same 17 checks,
+  same verdict - because a laptop told it fails a server check learns to ignore
+  doctor.
+
+- **`docs/server-readiness.md`** sets up nothing and says so first. It covers the
+  permission posture, why the scheduler is a LaunchAgent rather than a
+  LaunchDaemon (the keychain is locked until login, and that failure arrives
+  much later wearing a 401), and which credential each phase needs.
+
+- **`scorecard-snapshot.mjs --diff`** keeps what the scorecard said and reports
+  what moved. Deliberately no 0-100 score: the scorecard reports twelve measured
+  metrics AND four it refuses to measure, and one figure would hide both halves.
+
+### Changed
+
+- **A run's state has one canonical directory.** `{project}/{taskId}/` is
+  canonical and the flat `{taskId}/` is read for compatibility; every reader
+  resolves through `lib/run-paths.sh` / `scripts/_run-paths.mjs`, so a run that
+  exists in both layouts is counted once.
+
+- **Five publish paths refuse rather than send when the leak gate is missing.**
+  Jira comments and descriptions, PR review bodies and inline comments, the
+  GitHub issue progress comment, the issue-CREATION path, and Confluence page
+  create/update all run their outbound text through `lib/outbound-gate.mjs`
+  first. A missing gate file refuses; opening the gate because the gate is not
+  there would be the one failure mode that matters. The count is part of the
+  gate: a sixth publisher cannot ship without the smoke's list naming it.
+
+- **`set -e` on the four destructive scripts, and deliberately not on the two
+  collectors.** `gc-abandoned`, `gc-worktrees`, `purge` and `worktree-finalize`
+  delete things, so the command after an unnoticed failure is the dangerous one.
+  `pre-push-check` runs the gates and counts failures, and `pre-commit-check` is
+  a hook built out of greps that are supposed to find nothing - under `-e` the
+  first clean detector would end the scan and report "no secrets" for a file it
+  never finished reading.
+
+### Fixed
+
+- **A script that dies now prints one line instead of a stack dump, and releases
+  what it held.** `lib/fatal.mjs` catches the sync throw, the rejection nobody
+  awaited and the throw from inside a callback; the last two are invisible to a
+  try/catch around `main()`. `write-state` releases its advisory lock on the way
+  out, so the next writer never has to judge a lock on age alone. EPIPE is
+  deliberately not fatal: `runs-index.mjs --json | head` is the ordinary way to
+  read a large output.
+
+- **Build junk no longer reaches an install.** A CI runner shipped 147 files
+  where every developer tree shipped 146, for four rounds, and the extra was
+  `__pycache__/*.pyc` - untracked, so no diff of the source could show it, and
+  copied verbatim into all three install trees. `copyDir` now filters
+  `__pycache__`, `*.pyc` and `.DS_Store` on every path.
+
+- **`jq` is required rather than optional on the nine paths that publish or
+  decide.** A missing `jq` renders as empty DATA and the work carries on with
+  it; those nine now exit 3.
+
+- **The autopilot runner survives a month unwatched.** `runner.log` is truncated
+  in place past 5MB (renaming it leaves launchd's `O_APPEND` descriptor writing
+  into the renamed file while the new one stays empty - the rotation that looks
+  right and silently stops logging), three consecutive empty attempts stop new
+  work being taken, and one JSON line per tick goes to `ticks.jsonl`.
+
+- **`github-ssh-setup.sh` no longer waits forever on a headless machine**, and
+  `write-state.mjs` gained `--if-rev=<n>` compare-and-swap so a second writer
+  cannot silently overwrite the first.
+
+- **A direct-run guard that compared `import.meta.url` to `file://${argv[1]}`**
+  is false whenever argv[1] is not already resolved - a `/var` path that
+  resolves to `/private/var`, or the symlink `install --link` writes. The script
+  then does nothing at all, silently.
+
+---
+
 ## [17.6.0] - 2026-09-15
 
 ### Added

package/README.md

@@ -8,16 +8,16 @@
 
 🇹🇷 Türkçe: [README.tr.md](./README.tr.md)
 
-An 8-phase AI development pipeline for **Claude Code**, **Copilot CLI** and **Codex CLI**. Drives a Jira issue or GitHub URL to a merged PR in one command - analysis → plan → TDD → review → test → commit → PR - with multi-repo orchestration, a plan-approval gate, CLI-aware parallel review, and store-compliance checks. Component and Figma-to-code work is dispatched to the per-stack marketplace plugins (iOS/SwiftUI, Android/Compose) rather than bundled, so component skills live in one place.
+A 6-phase AI development pipeline for **Claude Code**, **Copilot CLI** and **Codex CLI**. Drives a Jira issue or GitHub URL to a merged PR in one command - analysis → plan → TDD → review → test → commit → PR - with multi-repo orchestration, a plan-approval gate, CLI-aware parallel review, and store-compliance checks. Component and Figma-to-code work is dispatched to the per-stack marketplace plugins (iOS/SwiftUI, Android/Compose) rather than bundled, so component skills live in one place.
 
 Runs natively on Claude Code, Copilot CLI and Codex CLI. macOS only. Zero runtime dependencies.
 
-📐 **[Architecture diagrams](./docs/architecture.md)** - the 8-phase flow, operating modes, review/triage, Figma subphases, component layout. **[Ecosystem diagram](./docs/ecosystem.md)** - how this repo, the `multi-agent-plugins` marketplace and `multi-agent-toolkit-mcp` compose.
+📐 **[Architecture diagrams](./docs/architecture.md)** - the 6-phase flow, operating modes, review/triage, Figma subphases, component layout. **[Ecosystem diagram](./docs/ecosystem.md)** - how this repo, the `multi-agent-plugins` marketplace and `multi-agent-toolkit-mcp` compose.
 
 ### Prerequisites
 
 - **Node.js >= 20.11** - required; the pipeline's own tooling runs on it.
-- **`jq`** - optional but recommended. Thirteen shell helpers reach for it and skip in silence without it: cost summaries, the phase tracker's JSON reads, convention extraction, skill signing. The install prints a note when it is missing.
+- **`jq`** - required for nine paths, optional for the rest. 82 shell files call it. The nine that publish or decide - the autopilot queue, Jira comments, PR reviews, issue updates, the plan file, both Figma fetchers, log search and Jira auth - now refuse with exit 3 rather than run, because a missing `jq` renders as empty DATA and the work carries on with it. Everywhere else it still degrades. The install prints a note when it is missing.
 - **`gh`** - for GitHub issue and PR work. Its built-in `--jq` is independent of the `jq` binary.
 
 ## Quick Start
@@ -33,6 +33,41 @@ npx @mmerterden/multi-agent-pipeline install --all       # all three
 /multi-agent:setup          # keychain token scan + git identity + default stack
 ```
 
+### No `npx` on that machine?
+
+`npx` ships with npm, and npm ships with Node - so "npx: command not found" almost
+always means Node is missing from that shell, not that anything is wrong with the
+package. Check first, then pick the row that matches:
+
+```bash
+node -v; npm -v; command -v node npm npx
+```
+
+| What you see | What to do |
+|---|---|
+| nothing at all | Install Node >= 20.11: `brew install node`, or the LTS installer from nodejs.org |
+| `node` works, `npx` does not | `npm i -g @mmerterden/multi-agent-pipeline` then `multi-agent-pipeline install --claude` |
+| nvm is installed but the shell does not see it | `source ~/.nvm/nvm.sh && nvm use --lts`, or just open a new terminal |
+| npm is ancient (< 5.2, which predates npx) | `npm i -g npm@latest`, or use the global-install row above |
+
+And the path that needs neither `npx` nor a global install - clone and run the
+installer directly:
+
+```bash
+git clone https://github.com/mmerterden/multi-agent-pipeline.git
+cd multi-agent-pipeline
+node index.js install --claude        # add --dry-run first to see what it would write
+```
+
+`npm exec @mmerterden/multi-agent-pipeline install --claude` also works on any npm
+7+ without `npx` on `PATH`.
+
+**One error that is not an npx problem.** This package declares `os: ["darwin"]`,
+so npm refuses to install it anywhere else and says `npm ERR! notsup Unsupported
+platform`. That is deliberate ([ADR-0012](./docs/adr/0012-macos-only.md)), not a
+missing tool: every credential read shells `security`, every iOS build
+`xcodebuild`, every piece of visual evidence `simctl`.
+
 Tool flags combine (`--claude --codex`). With no tool flag at all, the installer targets Claude Code only. Other flags: `--dry-run` (show what would be written, write nothing), `--platform=ios|android|all` (skip the stack skills you do not need), `--link` (symlink instead of copy, for local development).
 
 Run a task - the input type is auto-detected:
@@ -56,22 +91,45 @@ Update later with `/multi-agent:update`. Uninstall (tokens preserved) with `npx
 
 ## How it works
 
-One command runs up to 8 phases, with a gate between the risky ones. Phase 0
+One command runs up to 6 phases, with a gate between the risky ones. Phase 0
 asks two questions that decide the shape of the rest - how deep the run goes
 (Full or Short) and where the branch lives (a worktree or your current
 checkout):
 
 - **0 · Init** - parse the input (Jira id / GitHub URL / free text), pick account + repo(s), fetch the issue, run a maturity check.
-- **1 · Analysis** - detect the stack, scan the codebase, map impact (Sonnet).
-- **2 · Plan** - write a task breakdown and **stop for your approval** before touching code.
-- **3 · Dev** - TDD: failing test → code → green, following the repo's style + the active stack skills.
-- **4 · Review** - deterministic gates (build / lint / test / secret-scan) must pass first, then a **CLI-aware parallel review** - Claude Code runs 3 models (Fable + Opus + Sonnet), Copilot CLI runs 3 (GPT-5.4 + Opus + Sonnet) - and a **Fable triage** keeps only actionable findings; blockers loop back to Phase 3.
-- **5 · Test** - build + run the suite; success is required (no faked passes).
-- **6 · Commit/PR** - conventional commit, push (must succeed), open a PR (`Ref: #N`, never auto-close).
-- **7 · Report** - technical summary + a Jira comment with test scenarios, posted through the channels layer.
+- **1 · Plan** - detect the stack, scan the codebase and write the analysis document, then break it into tasks with file-level targets and **stop for your approval** before touching code. Analysis and planning were two phases until 19.0.0; the depth picker always skipped them together, because they are one decision. Codebase scanning runs on the explorer persona (Sonnet).
+- **2 · Dev** - TDD: failing test → code → green, following the repo's style + the active stack skills. The phase ends at its own gate: build, lint, tests and a secret scan, run **once**. Review used to build again, and nothing consumed the difference.
+- **3 · Review** - a **CLI-aware parallel review** against the logs Dev produced - Claude Code runs 3 models (Fable + Opus + Sonnet), Copilot CLI runs 3 (GPT-5.4 + Opus + Sonnet) - then a **Fable triage** keeps only actionable findings; blockers loop back to Phase 2. The optional user test lives here, keeping its waiting state.
+- **4 · Commit/PR** - conventional commit, push (must succeed), open a PR (`Ref: #N`, never auto-close).
+- **5 · Report** - technical summary + a Jira comment with test scenarios, posted through the channels layer. This is the one step autopilot still pauses at, in every mode.
 
 `/multi-agent:analysis` runs its own shorter chain and, since v16.12.0, reviews what it wrote before publishing it: the draft goes through the same three-reviewer set and triage as a code diff, a blocking finding returns it to synthesis with dispatch closed, and the gaps that survive are either searched, asked about, or recorded with an owner. It used to publish behind a structural validator alone.
 
+### 19.0.0: six phases, and a gate for the number
+
+Two of the six phases were doing the same work twice. Dev built the project
+and tee'd a log; Review opened by building it again. Analysis and Planning were
+already one decision - the depth picker skipped them together and the state
+schema described them as one unit. Six phases now, one build per run.
+
+The other half of the change is that the count is finally guarded.
+`smoke-phase-contract.sh` derives it from `pipeline/schemas/phases.json` and
+holds every other copy to it: the generator's output, the token budget, the
+state-schema bounds, the progress fractions in sample output, and the named
+thresholds that used to be literals scattered across scripts. The phase count
+appeared in 91 places across 40 files with nothing checking any of them, while
+the command count, the jq count and the persona count all had gates.
+
+Reasoning, mapping and rejected alternatives:
+[ADR-0014](./docs/adr/0014-six-phase-consolidation.md).
+
+### 18.0.0: one state directory, and a way to ask whether your install is real
+
+- **`multi-agent-pipeline verify`.** The install is a copy, and from the moment it is written the two halves drift independently: an edit in the installed tree is behaviour with no source, and a file the installer skipped is a script the docs describe and nobody has. `verify` compares both against a manifest built at pack time. What a green result proves is stated plainly - the bytes match what the publisher recorded, not who published them.
+- **Cost, past the single run.** The per-task ceiling cannot see the two ways a budget actually empties: a drift that trips nothing, and one session that burns a week in an hour while every run stays under its cap. `cost-analyze` projects, finds days out of family by median absolute deviation, and reports acceleration - as LIST-price estimates, which it says on every run rather than in a footnote.
+- **A run's state lives in one place.** `{project}/{taskId}/` is canonical, the flat layout is still read, and a run that exists in both is counted once.
+- **Server readiness, entirely opt-in.** `doctor --profile=server` adds four checks that only matter when nobody is at the keyboard, `install --unattended` writes a permission profile after printing it, and the autopilot runner now survives a month unwatched. The default install writes no permissions and the default doctor run is unchanged, because a laptop told it fails a server check learns to ignore doctor.
+
 ### Your package manager, your hooks, your MCP surface
 
 Three smaller things in 17.6.0, each closing a gap where the pipeline assumed instead of looking:
@@ -108,8 +166,8 @@ The discipline behind all of this - bounded loops, evidence gates, token-budgete
 
 | Mode      | Command                              | Flow                                                                                                                                                             |
 | --------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Full      | `/multi-agent "task"`                | All 8 phases, interactive                                                                                                                                        |
-| Autopilot | `/multi-agent:autopilot "task"`      | 7 phases (interactive Test gate dropped), no confirmations                                                                                                       |
+| Full      | `/multi-agent "task"`                | All 6 phases, interactive                                                                                                                                        |
+| Autopilot | `/multi-agent:autopilot "task"`      | 6 phases (interactive Test gate dropped), no confirmations                                                                                                       |
 | Local     | `/multi-agent:local "task"`          | Full pipeline minus the interactive Test gate, current branch (no worktree)                                                                                      |
 | Depth     | asked at Phase 0 Step 7.5            | Full (all phases) or Short (Dev → Review → Test → Commit → Report). Not a command name - `/multi-agent` and `:local` ask, both autopilot entries always run Full |
 | Ship      | `/multi-agent:resume-local`          | Run the review→test→commit→report tail over local work                                                                                                           |
@@ -165,7 +223,7 @@ The widget follows the answer rather than predicting it: Phase 0 is the only til
 | `/multi-agent:review-jira`         | Grade a Jira issue's readiness for development, comment the gaps                            |
 | `/multi-agent:review-issue`        | Same grading for a GitHub issue                                                             |
 | `/multi-agent:review-analysis`     | Review a written analysis document; findings cite the Locked rule they break                |
-| `/multi-agent:diff-explain`        | Map a Phase 4 triage finding back to the diff lines that caused it                          |
+| `/multi-agent:diff-explain`        | Map a Phase 3 triage finding back to the diff lines that caused it                          |
 | `/multi-agent:refactor`            | Best-practice extraction + bug hunt + derived-skill drift + toolkit MCP research → one plan |
 | `/multi-agent:scan`                | Skill security scan of local skill directories against a tiered pattern catalog             |
 | `/multi-agent:prune-prompts`       | Zero-base review of the always-on instruction footprint; keep / trial / delete per rule     |
@@ -301,17 +359,17 @@ This enables the matching plugin (+ the shared `ai-common` plugin) in the repo's
 
 ## Tool support
 
-The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI** - all three install from the same `pipeline/` source and get the same 56 commands.
+The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI** - all three install from the same `pipeline/` source and get the same 60 commands.
 
 | Tool        | Flag                 | What it installs                                                                                       |
 | ----------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
 | Claude Code | `--claude` (default) | slash commands + skills + agents + three `PreToolUse` hooks (secret scan, agent-guard, read-size gate) |
-| Copilot CLI | `--copilot`          | instructions + 56 sub-command skills + scripts                                                         |
-| Codex CLI   | `--codex`            | one router skill + 56 specs as refs + 9 agent TOML + `AGENTS.md` block + `codex mcp add`               |
+| Copilot CLI | `--copilot`          | instructions + 60 sub-command skills + scripts                                                         |
+| Codex CLI   | `--codex`            | one router skill + 60 specs as refs + 9 agent TOML + `AGENTS.md` block + `codex mcp add`               |
 
 Filter skills by stack with `--platform=ios\|android\|all`.
 
-**Why Codex gets one skill and not 56.** Codex assembles every discovered skill's name
+**Why Codex gets one skill and not 60.** Codex assembles every discovered skill's name
 and description into a single prompt block and drops entries when it overflows, with no
 error. Measured on 0.145: installing one plugin that declares 142 skills surfaced only
 75 of them and evicted an unrelated user skill. So on Codex the pipeline ships a single

package/README.tr.md

@@ -8,11 +8,11 @@
 
 🇬🇧 English: [README.md](./README.md)
 
-**Claude Code**, **Copilot CLI** ve **Codex CLI** için 8 fazlı bir AI geliştirme pipeline'ı. Bir Jira issue'sunu veya GitHub URL'sini tek komutla merge edilmiş bir PR'a dönüştürür - analiz → plan → TDD → review → test → commit → PR - çoklu-repo orkestrasyonu, bir plan-onay kapısı, CLI-farkında paralel review ve store-uyumluluk kontrolleriyle birlikte. Component ve Figma-to-code işleri paket içine gömülmek yerine stack başına marketplace plugin'lerine (iOS/SwiftUI, Android/Compose) devredilir, böylece component skill'leri tek bir yerde yaşar.
+**Claude Code**, **Copilot CLI** ve **Codex CLI** için 6 fazlı bir AI geliştirme pipeline'ı. Bir Jira issue'sunu veya GitHub URL'sini tek komutla merge edilmiş bir PR'a dönüştürür - analiz → plan → TDD → review → test → commit → PR - çoklu-repo orkestrasyonu, bir plan-onay kapısı, CLI-farkında paralel review ve store-uyumluluk kontrolleriyle birlikte. Component ve Figma-to-code işleri paket içine gömülmek yerine stack başına marketplace plugin'lerine (iOS/SwiftUI, Android/Compose) devredilir, böylece component skill'leri tek bir yerde yaşar.
 
 Claude Code, Copilot CLI ve Codex CLI üzerinde native çalışır. Yalnızca macOS. Sıfır runtime dependency.
 
-📐 **[Mimari diyagramları](./docs/architecture.md)** - 8 faz akışı, çalışma modları, review/triage, Figma subphase'leri, component yapısı. **[Ekosistem diyagramı](./docs/ecosystem.md)** - bu repo, `multi-agent-plugins` marketplace'i ve `multi-agent-toolkit-mcp`'nin nasıl bir araya geldiği.
+📐 **[Mimari diyagramları](./docs/architecture.md)** - 6 faz akışı, çalışma modları, review/triage, Figma subphase'leri, component yapısı. **[Ekosistem diyagramı](./docs/ecosystem.md)** - bu repo, `multi-agent-plugins` marketplace'i ve `multi-agent-toolkit-mcp`'nin nasıl bir araya geldiği.
 
 ### Önkoşullar
 
@@ -33,6 +33,40 @@ npx @mmerterden/multi-agent-pipeline install --all       # üçü birden
 /multi-agent:setup          # keychain token taraması + git kimliği + varsayılan stack
 ```
 
+### O makinede `npx` yoksa
+
+`npx` npm ile, npm de Node ile gelir - yani "npx: command not found" neredeyse her
+zaman o kabukta Node olmadığı anlamına gelir, pakette bir sorun olduğu değil. Önce
+bak, sonra sana uyan satırı uygula:
+
+```bash
+node -v; npm -v; command -v node npm npx
+```
+
+| Gördüğün | Yapılacak |
+|---|---|
+| hiçbiri yok | Node >= 20.11 kur: `brew install node` ya da nodejs.org'dan LTS installer |
+| `node` çalışıyor, `npx` çalışmıyor | `npm i -g @mmerterden/multi-agent-pipeline` sonra `multi-agent-pipeline install --claude` |
+| nvm kurulu ama kabuk görmüyor | `source ~/.nvm/nvm.sh && nvm use --lts`, ya da yeni bir terminal aç |
+| npm çok eski (< 5.2, npx'ten önceki sürümler) | `npm i -g npm@latest`, ya da üstteki global kurulum satırı |
+
+Ne `npx` ne de global kurulum isteyen yol - klonla ve installer'ı doğrudan çalıştır:
+
+```bash
+git clone https://github.com/mmerterden/multi-agent-pipeline.git
+cd multi-agent-pipeline
+node index.js install --claude        # önce --dry-run ile ne yazacağını görebilirsin
+```
+
+`npm exec @mmerterden/multi-agent-pipeline install --claude` de, `PATH`'te `npx`
+olmayan her npm 7+ üzerinde çalışır.
+
+**npx sorunu olmayan bir hata.** Bu paket `os: ["darwin"]` beyan eder; npm başka
+hiçbir yerde kurmaz ve `npm ERR! notsup Unsupported platform` der. Bu kasıtlıdır
+([ADR-0012](./docs/adr/0012-macos-only.md)), eksik bir araç değil: her credential
+okuması `security`, her iOS build'i `xcodebuild`, her görsel kanıt `simctl`
+çağırıyor.
+
 Tool flag'leri birleştirilebilir (`--claude --codex`). Hiç tool flag'i verilmezse installer sadece Claude Code'u hedefler. Diğer flag'ler: `--dry-run` (ne yazılacağını gösterir, hiçbir şey yazmaz), `--platform=ios|android|all` (ihtiyacın olmayan stack skill'lerini atlar), `--link` (kopyalamak yerine symlink, lokal geliştirme için).
 
 Bir görev çalıştır - girdi tipi otomatik algılanır:
@@ -56,22 +90,27 @@ Sonra `/multi-agent:update` ile güncelle. Kaldırmak için (tokenlar korunur) `
 
 ## Nasıl çalışır
 
-Tek komut en fazla 8 fazı çalıştırır, riskli olanlar arasında bir kapı ile. Faz
+Tek komut en fazla 6 fazı çalıştırır, riskli olanlar arasında bir kapı ile. Faz
 0 geri kalanın şeklini belirleyen iki soru sorar: koşu ne kadar derin olacak
 (Tam mı Kısa mı) ve branch nerede yaşayacak (worktree mi, mevcut checkout'un
 mu):
 
 - **0 · Init** - girdiyi ayrıştır (Jira id / GitHub URL / serbest metin), hesap + repo(lar) seç, issue'yu çek, maturity kontrolü yap.
-- **1 · Analysis** - stack'i tespit et, codebase'i tara, etkiyi haritala (Sonnet).
-- **2 · Plan** - bir görev kırılımı yaz ve koda dokunmadan önce **onayın için dur**.
-- **3 · Dev** - TDD: başarısız test → kod → yeşil, repo'nun stiline + aktif stack skill'lerine uyarak.
-- **4 · Review** - önce deterministik kapılar (build / lint / test / secret-scan) geçmeli, sonra bir **CLI-farkında paralel review** - Claude Code 3 model çalıştırır (Fable + Opus + Sonnet), Copilot CLI 3 (GPT-5.4 + Opus + Sonnet) - ve bir **Fable triage** sadece aksiyon alınabilir bulguları tutar; blocker'lar Phase 3'e geri döner.
-- **5 · Test** - build + suite'i çalıştır; başarı zorunlu (sahte pass yok).
-- **6 · Commit/PR** - conventional commit, push (başarılı olmalı), bir PR aç (`Ref: #N`, asla otomatik kapatma).
-- **7 · Report** - teknik özet + test senaryolarıyla bir Jira yorumu, channels katmanından gönderilir.
+- **1 · Plan** - stack'i tespit et, codebase'i tara ve analiz dokümanını yaz; sonra onu dosya seviyesinde hedefleri olan görevlere böl ve koda dokunmadan önce **onayın için dur**. Analiz ve planlama 19.0.0'a kadar iki ayrı fazdı; derinlik seçici ikisini hep birlikte atlıyordu, çünkü tek bir karar. Codebase taraması explorer persona'sı üzerinde koşar (Sonnet).
+- **2 · Dev** - TDD: başarısız test → kod → yeşil, repo'nun stiline + aktif stack skill'lerine uyarak. Faz kendi kapısında biter: build, lint, test ve sır taraması, **bir kez** koşar. Review eskiden ikinci kez build ediyordu ve aradaki farkı kimse okumuyordu.
+- **3 · Review** - Dev'in ürettiği log'lara karşı **CLI-farkında paralel review** - Claude Code 3 model çalıştırır (Fable + Opus + Sonnet), Copilot CLI 3 (GPT-5.4 + Opus + Sonnet) - ve bir **Fable triage** sadece aksiyon alınabilir bulguları tutar; blocker'lar Phase 2'ye geri döner. Opsiyonel kullanıcı testi burada, bekleme durumunu koruyarak.
+- **4 · Commit/PR** - conventional commit, push (başarılı olmalı), bir PR aç (`Ref: #N`, asla otomatik kapatma).
+- **5 · Report** - teknik özet + test senaryolarıyla bir Jira yorumu, channels katmanından gönderilir. Autopilot'un her modda hâlâ durduğu tek adım bu.
 
 `/multi-agent:analysis` kendi kısa zincirini koşar ve v16.12.0'dan beri yazdığını yayınlamadan önce review ediyor: taslak, bir kod diff'iyle aynı üç-reviewer setinden ve triyajdan geçiyor, bloklayıcı bulgu dokümanı sentez fazına geri gönderip dispatch'i kapatıyor, hayatta kalan boşluklar ya aranıyor ya sana soruluyor ya da sahibiyle birlikte kayda giriyor. Önceden yalnızca yapısal bir validator'ın arkasından yayınlıyordu.
 
+### 18.0.0: tek bir durum dizini, ve kurulumun gerçekten o kurulum olup olmadığını sorma yolu
+
+- **`multi-agent-pipeline verify`.** Kurulum bir kopyadır ve yazıldığı andan itibaren iki taraf birbirinden bağımsız kayar: kurulu ağaçtaki bir düzenleme kaynağı olmayan bir davranıştır, kurulumun atladığı dosya ise dokümanın anlattığı ama kimsede olmayan bir script. `verify` ikisini de paketleme anında üretilen bir manifest'e karşı karşılaştırır. Yeşil sonucun ne kanıtladığı açıkça yazılıdır: baytlar yayıncının kaydettiğiyle aynıdır, kimin yayınladığı değil.
+- **Maliyet, tek koşunun ötesinde.** Görev başına tavan, bütçeyi gerçekten bitiren iki şeyi göremez: hiçbir koşuyu aşmayan kayma, ve her koşu tavanın altında kalırken bir saatte bir haftayı yakan tek oturum. `cost-analyze` projeksiyon yapar, medyan mutlak sapmayla aileden ayrılan günü bulur ve ivmeyi raporlar - liste fiyatından tahmin olarak, ve bunu dipnotta değil her koşuda söyler.
+- **Bir koşunun durumu tek yerde.** `{project}/{taskId}/` kanonik, düz yerleşim hâlâ okunuyor, ve iki yerde birden duran koşu bir kez sayılıyor.
+- **Sunucu hazırlığı, tamamen opt-in.** `doctor --profile=server` yalnızca klavyede kimse yokken anlamı olan dört kontrol ekler, `install --unattended` izin profilini yazmadan önce gösterir, autopilot runner artık bir ay gözetimsiz ayakta kalır. Varsayılan kurulum hiçbir izin yazmaz ve varsayılan doctor koşusu değişmez: sunucu kontrolünden kaldığı söylenen bir dizüstü, doctor'ı görmezden gelmeyi öğrenir.
+
 ### Paket yöneticisi, hook'lar ve MCP yüzeyi
 
 17.6.0'da üç küçük iş; üçü de pipeline'ın bakmak yerine varsaydığı bir yeri kapatıyor:
@@ -108,8 +147,8 @@ Bunun arkasındaki disiplin - sınırlı loop'lar, kanıt kapıları, token-büt
 
 | Mod       | Komut                                | Akış                                                                                                                                                                       |
 | --------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Full      | `/multi-agent "task"`                | Tüm 8 faz, interaktif                                                                                                                                                      |
-| Autopilot | `/multi-agent:autopilot "task"`      | 7 faz (interaktif Test kapısı atlanır), onaysız                                                                                                                            |
+| Full      | `/multi-agent "task"`                | Tüm 6 faz, interaktif                                                                                                                                                      |
+| Autopilot | `/multi-agent:autopilot "task"`      | 6 faz (interaktif Test kapısı atlanır), onaysız                                                                                                                            |
 | Local     | `/multi-agent:local "task"`          | İnteraktif Test kapısı hariç tam pipeline, mevcut branch (worktree yok)                                                                                                    |
 | Derinlik  | Faz 0 Adım 7.5'te sorulur            | Full (tüm fazlar) veya Short (Dev → Review → Test → Commit → Report). Komut adı değil - `/multi-agent` ve `:local` sorar, iki autopilot girişi de her zaman Full koşar     |
 | Ship      | `/multi-agent:resume-local`          | Lokal iş üzerinde review→test→commit→report kuyruğunu çalıştır                                                                                                             |
@@ -302,17 +341,17 @@ Bu, ilgili plugin'i (+ ortak `ai-common` plugin'ini) repo'nun `.claude/settings.
 
 ## Araç desteği
 
-Pipeline **Claude Code**, **Copilot CLI** ve **Codex CLI** üzerinde native çalışır - üçü de aynı `pipeline/` kaynağından kurulur ve aynı 56 komutu alır.
+Pipeline **Claude Code**, **Copilot CLI** ve **Codex CLI** üzerinde native çalışır - üçü de aynı `pipeline/` kaynağından kurulur ve aynı 60 komutu alır.
 
 | Araç        | Bayrak                  | Ne kurar                                                                                                         |
 | ----------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | Claude Code | `--claude` (varsayılan) | slash komutları + skill'ler + agent'lar + üç `PreToolUse` hook'u (secret scan, agent-guard, okuma-boyutu geçidi) |
-| Copilot CLI | `--copilot`             | talimatlar + 56 alt-komut skill'i + script'ler                                                                   |
-| Codex CLI   | `--codex`               | bir router skill + ref olarak 56 spec + 9 agent TOML + `AGENTS.md` bloğu + `codex mcp add`                       |
+| Copilot CLI | `--copilot`             | talimatlar + 60 alt-komut skill'i + script'ler                                                                   |
+| Codex CLI   | `--codex`               | bir router skill + ref olarak 60 spec + 9 agent TOML + `AGENTS.md` bloğu + `codex mcp add`                       |
 
 Skill'leri stack'e göre filtrele: `--platform=ios\|android\|all`.
 
-**Codex neden 56 değil de tek bir skill alıyor.** Codex, keşfettiği her skill'in adını
+**Codex neden 60 değil de tek bir skill alıyor.** Codex, keşfettiği her skill'in adını
 ve açıklamasını tek bir prompt bloğuna toplar ve blok taştığında girdileri hatasızca
 düşürür. 0.145 üzerinde ölçüldü: 142 skill deklare eden bir plugin kurulduğunda sadece
 75'i yüzeye çıktı ve alakasız bir kullanıcı skill'i tahliye edildi. Bu yüzden Codex'te

package/docs/adr/0002-instruction-driven-flag.md

@@ -1,6 +1,7 @@
 # 2. `instructionDriven` flag as explicit pipeline fork
 
 **Status:** Accepted · 2025
+> **Phase numbers below are the eight-phase ones.** [ADR-0014](./0014-six-phase-consolidation.md) renumbered the contract in v19.0.0 (Phase 6 Commit is now Phase 4, Phase 7 Report is now Phase 5). The decision this ADR records is unchanged; only the labels moved, and they are left as written because an ADR records what was decided.
 
 ## Context