@gtrabanco/pi-agentic-workflow 0.13.2 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/README.md +3 -9
  2. package/dist/routing/catalogue.d.ts +1 -1
  3. package/dist/routing/catalogue.js +1 -1
  4. package/dist/runtime.d.ts +45 -0
  5. package/dist/runtime.js +62 -0
  6. package/package.json +10 -8
  7. package/skills/audit-docs/SKILL.md +6 -5
  8. package/skills/audit-pr/SKILL.md +1 -1
  9. package/skills/audit-pr/references/PORTABILITY.md +1 -1
  10. package/skills/execute-phase/SKILL.md +207 -116
  11. package/skills/execute-phase/references/DESCOPE.md +22 -18
  12. package/skills/execute-phase/references/EXECUTION_CONTRACT.md +69 -77
  13. package/skills/execute-phase/references/FOLDING.md +34 -47
  14. package/skills/execute-phase/references/PREFLIGHT.md +103 -114
  15. package/skills/execute-phase/references/PRE_EXECUTION_GATE.md +53 -60
  16. package/skills/init-workspace/SKILL.md +52 -16
  17. package/skills/init-workspace/references/BOOTSTRAP_DISCOVERY.md +6 -6
  18. package/skills/init-workspace/references/BOOTSTRAP_WRITE.md +17 -10
  19. package/skills/init-workspace/references/PORTABILITY.md +1 -1
  20. package/skills/init-workspace/references/UPGRADE.md +50 -15
  21. package/skills/log-session/SKILL.md +4 -3
  22. package/skills/orchestration-envelope/references/TURN_CONTRACT.md +1 -1
  23. package/skills/pre-execution-review/references/LEDGERS.md +39 -39
  24. package/skills/pre-execution-review/references/POLICY.md +1 -0
  25. package/skills/product-audit/SKILL.md +4 -4
  26. package/skills/product-audit/references/AUDIT_PROCESS.md +3 -3
  27. package/skills/review-change/SKILL.md +1 -1
  28. package/skills/review-change/references/PORTABILITY.md +1 -1
  29. package/skills/unit-lane/SKILL.md +154 -0
  30. package/skills/unit-lane/references/DESIGN.md +35 -0
  31. package/skills/unit-lane/references/DOCS.md +36 -0
  32. package/skills/unit-lane/references/EVIDENCE.md +34 -0
  33. package/skills/unit-lane/references/IMPLEMENT.md +45 -0
  34. package/skills/unit-lane/references/PLAN.md +38 -0
  35. package/skills/unit-lane/references/RELEASE.md +45 -0
  36. package/skills/unit-lane/references/RESEARCH.md +37 -0
  37. package/skills/unit-lane/references/REVIEW.md +45 -0
  38. package/skills/unit-lane/references/STEPS.md +23 -0
  39. package/skills/unit-lane/references/TESTS.md +32 -0
  40. package/skills/workflow-status/references/ENVELOPE_FIELDS.md +5 -6
  41. package/skills/workflow-status/references/SENSOR_CORE.md +16 -20
  42. package/skills/workflow-status/references/SENSOR_SIGNALS.md +5 -7
  43. package/skills/design-feature/SKILL.md +0 -231
  44. package/skills/design-feature/references/INTERVIEW.md +0 -74
  45. package/skills/design-feature/references/PORTABILITY.md +0 -15
  46. package/skills/design-feature/references/REPAIR.md +0 -88
  47. package/skills/design-feature/references/UPSERT_EXAMPLE.md +0 -8
  48. package/skills/design-feature/references/WRITE_AND_UPSERT.md +0 -115
  49. package/skills/evidence-grounding/SKILL.md +0 -174
  50. package/skills/evidence-grounding/references/DELEGATION.md +0 -131
  51. package/skills/evidence-grounding/references/READINESS.md +0 -130
  52. package/skills/evidence-grounding/references/ROWS.md +0 -93
  53. package/skills/execute-phase/references/BATCH_AND_PORTABILITY.md +0 -57
  54. package/skills/execute-phase/references/CLOSEOUT.md +0 -77
  55. package/skills/execute-phase/references/HANDOFF.md +0 -21
  56. package/skills/execute-phase/references/OPPORTUNISTIC_FINDING.md +0 -45
  57. package/skills/execute-phase/references/UNIT_LOOP.md +0 -88
  58. package/skills/execute-phase/references/WORKFLOWS_FEATURE.md +0 -37
  59. package/skills/execute-phase/references/WORKFLOWS_FIX.md +0 -43
  60. package/skills/execute-phase/references/WORKFLOWS_LEGACY.md +0 -26
  61. package/skills/execute-phase/references/WORKFLOWS_SMALL_PHASED.md +0 -38
  62. package/skills/generate-docs/SKILL.md +0 -145
  63. package/skills/generate-docs/references/ADAPTERS.md +0 -15
  64. package/skills/generate-docs/references/ADAPTER_DISCOVERY.md +0 -33
  65. package/skills/generate-docs/references/GENERATION_PROCESS.md +0 -90
  66. package/skills/implementation-discovery/SKILL.md +0 -209
  67. package/skills/plan-feature/SKILL.md +0 -208
  68. package/skills/plan-feature/references/ROUTING.md +0 -155
  69. package/skills/plan-feature-from-issue/SKILL.md +0 -162
  70. package/skills/plan-feature-scaffold/SKILL.md +0 -112
  71. package/skills/plan-feature-scaffold/references/SCAFFOLD_PROCESS.md +0 -122
  72. package/skills/plan-fix/SKILL.md +0 -161
  73. package/skills/plan-fix/references/PLANNING_PROCESS.md +0 -148
  74. package/skills/plan-fix/references/SPEC_CONTRACT.md +0 -22
  75. package/skills/planning-preflight/SKILL.md +0 -130
  76. package/skills/replan-findings/SKILL.md +0 -131
  77. package/skills/replan-findings/references/PHASE_APPEND.md +0 -89
  78. package/skills/review-plan/SKILL.md +0 -154
  79. package/skills/review-plan/references/CHECKS.md +0 -111
  80. package/skills/review-plan/references/ENG-CHECKS.md +0 -30
  81. package/skills/review-plan/references/OUTPUT.md +0 -166
  82. package/skills/review-spec/SKILL.md +0 -145
  83. package/skills/review-spec/references/CHECKS.md +0 -108
  84. package/skills/review-spec/references/OUTPUT.md +0 -160
  85. package/skills/ship-roadmap/SKILL.md +0 -120
  86. package/skills/ship-roadmap/references/ADVANCE.md +0 -117
  87. package/skills/ship-roadmap/references/AUDIT_AND_MERGE.md +0 -64
  88. package/skills/ship-roadmap/references/CLOSEOUT_AND_LOG.md +0 -27
  89. package/skills/ship-roadmap/references/FOUNDING.md +0 -101
  90. package/skills/ship-roadmap/references/GUARDRAILS.md +0 -56
  91. package/skills/ship-roadmap/references/MODEL_ROUTING.md +0 -16
  92. package/skills/ship-roadmap/references/PORTABILITY.md +0 -34
  93. package/skills/ship-roadmap/references/RECOVERY_AND_SELECTION.md +0 -94
  94. package/skills/ship-roadmap/references/STOP_CONDITIONS.md +0 -9
  95. package/skills/ship-roadmap/references/TERMINAL_REPORT.md +0 -34
@@ -1,101 +0,0 @@
1
- ## Process
2
-
3
- ### Mode A — Found & launch (interactive): `/ship-roadmap [--fullauto]`
4
-
5
- **1. The interview — all questions up front, then silence.** Small batched
6
- rounds; recommended defaults on every question; skip what discovery already
7
- answered. After Round 6 locks, **no further questions for the entire run** —
8
- every later decision is made silently and logged with a one-line rationale.
9
-
10
- | Round | Covers |
11
- |---|---|
12
- | 1 — Product | What it is, for whom; scale ceiling (solo / team / thousands of customers); lifespan & ambition (throwaway, internal, long-lived production). Calibrates every ceremony decision downstream. |
13
- | 2 — Features | The feature list (or "elicit" → draft one from the goal); must-have vs can-wait; ordering constraints; explicit out-of-scope. |
14
- | 3 — Stack & architecture | Stack decided? else recommend from features/constraints. Architecture chosen? else recommend the **lightest structure proportional to Round 1** — a solo tool gets a flat modular layout, a thousands-of-customers system gets enforced boundaries; never default to DDD, hexagonal, or any named pattern. Platform/runtime constraints, library vetoes. |
15
- | 4 — Quality & ops | Test depth (smoke / workflow default / strict); whether a11y, SEO, i18n, perf budgets apply (proposed from platform type); deploy target + scaffold CI?; secrets posture; **confirm the proposed verification gate commands** — they become the gate every phase must pass. |
16
- | 5 — Workflow & autonomy | Docs language (default English); forge + CLI (**verify with a real authenticated call now**, e.g. `gh auth status` — not mid-loop); **git workflow** (default `branches`: one active unit, sequential, no worktrees — `worktrees` only if the user declares it and their tooling manages them; recorded in the Workflow conventions and honored by every stage); merge policy (default human-merge vs `--fullauto`); the sensitive-area list (defaults: auth, payments, destructive migrations/data deletion, secrets, CI config — **seeded with every integration named in rounds 2–4**, e.g. the payment processor or auth provider the user mentioned); budget caps (default: max iterations = 4× roadmap feature count; 2 retries per red gate; 2 review-fix and 2 audit-fix cycles; optional "pause after N shipped features" checkpoint and milestone stop lines); model-routing confirmation; recommend enabling `ultracode` for the loop. |
17
- | 6 — Confirm & launch | The drafted roadmap (numbers, order, deps, sizes) and the full decision record, presented for **one last edit**. Then: founding artifacts written, exact `/loop` command printed. |
18
-
19
- **2. Founding (only what's missing).** Compose `init-workspace`'s process
20
- in-turn (both opus/high — within the ≥ rule), **pre-fed with the interview
21
- answers** so it asks nothing. Branch discipline:
22
-
23
- - **Empty repo:** the scaffold (CLAUDE.md, docs/, .github/, completed
24
- ROADMAP.md, decision record) is the repo's **initial commit on the default
25
- branch** — there is no history to protect and no base for a PR yet.
26
- - **Existing repo:** founding goes on a `docs/ship-founding` branch as a PR.
27
- Default mode: **stop after the interview** — print the PR and require it
28
- merged before the loop starts (building features against an unmerged
29
- substrate would stack PRs). `--fullauto`: gate the founding PR with
30
- `audit-pr` like every other PR, then merge it.
31
-
32
- **3. The roadmap — founding IS batch design.** The interview's rounds 2–4
33
- (features, quality/ops, workflow) already collected every product-definition
34
- answer a `design-feature` capability closure would ask — founding is design
35
- for every feature it names, not a shortcut around it. Adopt existing entries
36
- (never renumber), fill gaps the interview surfaced, append elicited features.
37
- If absent, write the complete table: NN in dependency-respecting order, slug,
38
- **status `idea`** (the locked founding decisions are the design record, but
39
- no per-feature `SPEC.md`/capability-closure artifact exists yet — that gets
40
- written JIT per feature, see ADVANCE → DESIGN below), depends-on, one-line
41
- summary with a **provisional XS/S/M/L size in the summary text** (the
42
- template's five-state legend and column schema stay exactly as they are —
43
- `plan-feature`/`plan-feature-scaffold` re-size authoritatively at planning
44
- time; a size change is logged silently). Greenfield: **feature 01 is always
45
- the project skeleton** (stack init, gate wiring, CI if requested), sized S —
46
- founding scaffolds it immediately (composing `design-feature` +
47
- `plan-feature-scaffold` in-turn, pre-fed from the interview, no questions) so
48
- it lands directly at **status `planned`**, never left at `idea` — and **every
49
- other feature's depends-on closure must include 01** (directly or
50
- transitively), so SELECT can never start a feature on a default branch that
51
- lacks the skeleton.
52
-
53
- **4. The run state — two artifacts, deliberately split:**
54
-
55
- - `docs/features/SHIP_DECISIONS.md` — **committed** (rides the founding
56
- commit/PR): run mode, safety floors, sensitive-area list, budget caps, stop
57
- lines, model routing, docs language, and a digest of every locked interview
58
- answer. It is the durable, auditable policy: a crash, another machine, or a
59
- fresh clone recovers the full run policy without re-interviewing.
60
- - `docs/features/.ship-run.log` — **untracked** (founding appends it to
61
- `.gitignore`): the append-only iteration log — one line per iteration
62
- (`date | NN-slug | stage | outcome | evidence: SHA / PR# / verdict`), silent
63
- decisions with rationale, partial-stage markers, verdict↔SHA bindings.
64
- Machine-local mechanics; committing it would conflict across every open PR.
65
-
66
- **5. Print the launch contract** — detect which driver this environment has
67
- and print the matching command. **Three equivalent drivers** (the loop is the
68
- contract; who re-invokes it is an implementation detail):
69
-
70
- | Driver | When | Launch |
71
- |---|---|---|
72
- | **`/loop`** (Claude Code) | The agent has a self-re-invoking loop primitive | `/loop /ship-roadmap --continue` |
73
- | **External orchestrator** | Any agent invocable headless (a shell loop, CI, your own program) | loop: invoke `/ship-roadmap --continue`, parse its native `SHIP:`/`→ Next:` contract, and re-invoke while the turn is non-terminal — see `docs/workflow/ORCHESTRATION.md` |
74
- | **Manual** | Neither of the above | re-run `/ship-roadmap --continue` yourself after each iteration; each ends with the exact next command |
75
-
76
- Default launch contract text (adapt the first line to the detected driver):
77
-
78
- ```
79
- Founded. Start the autopilot with:
80
-
81
- /loop /ship-roadmap --continue (Claude Code)
82
- — or loop `/ship-roadmap --continue` from your orchestrator/by hand;
83
- parse the native `SHIP:` banner and `→ Next:` block, then re-invoke
84
- while the turn is non-terminal (see docs/workflow/ORCHESTRATION.md)
85
-
86
- Stop when an iteration's first line is SHIP: COMPLETE, SHIP: BLOCKED, or
87
- SHIP: STOPPED (envelope state OK, BLOCKED, or FAILED). Iterations are
88
- idempotent and resume cleanly; stopping at any time is safe.
89
- ```
90
-
91
- For a fullauto run the command is `/ship-roadmap --continue --fullauto` (under
92
- whichever driver) — the flag must ride every iteration, because auto-merge is
93
- dual-keyed: the flag on the running command **and** `merge: fullauto` in the
94
- committed decision record (see Merge policy). One key without the other runs
95
- in default mode.
96
-
97
- Each firing is a fresh `/ship-roadmap --continue` turn (on Claude Code's
98
- `#claude` branch, at this skill's pinned tier; elsewhere, at whatever tier the
99
- driver chose — judgment iterations deserve your strongest model). Iterations
100
- after a terminal banner are cheap no-ops that re-print the same banner — so a
101
- missed stop costs tokens, never correctness.
@@ -1,56 +0,0 @@
1
- ## Guardrails
2
-
3
- - **Never work on the default branch** — the empty-repo initial scaffold commit
4
- is the single exception. One PR per unit, never stacked; roadmap status flips
5
- ride PR-bound commits only.
6
- - **Forge bodies are Markdown, not shell — never hand-escape.** Every explicitly
7
- authorized issue, PR, or comment the run creates (subagent PRs, triage
8
- comments) carries a body of **real Markdown**: backticks / `*` / `_` are
9
- formatting, and a `\` before them renders literally (`` \`code\` `` instead
10
- of `` `code` ``). Write the body to a file and pass **`--body-file <path>`**
11
- to `gh issue create` / `gh pr create` / `gh issue comment` (or the declared
12
- forge's equivalent) — never inline `--body "…"` or a quoted heredoc. Verify
13
- with `gh … --json body` that no literal `` \` `` survived. (execute-phase
14
- subagents already follow this; the conductor must too.)
15
- - **Never commit red; never merge red.** The gate and the floors are
16
- unconditional — no flag, mode, or interview answer disables them.
17
- - **Never request or retain a direct-merge permission.** Fullauto calls only
18
- the repository wrapper with command-scoped variables; a missing wrapper or
19
- active guard blocks the run and routes to `init-workspace` upgrade.
20
- - **No stage ends dirty or unpushed.** The clean close-out check (Mode B
21
- step 5) is part of every stage: tracked modifications — docs included — are
22
- committed with the stage, and a PR-backed branch is pushed before the
23
- iteration logs the stage complete. Merging while anything is uncommitted,
24
- unpushed, or unpulled is forbidden: push, wait for CI, re-audit, then merge.
25
- - **The conductor never writes application code.** All implementation flows
26
- through fresh cheap-tier `execute-phase` workers, one phase per context —
27
- that keeps the cost model honest and `execute-phase` the single pathway.
28
- - **Tier discipline.** Compose in-turn only skills at ≤ opus/high;
29
- implementation goes below the turn tier via explicit subagent model
30
- overrides; `product-audit` is never run by this skill. `ultracode` is a
31
- user-owned session setting — recommended, never claimed.
32
- - **Interview once, then silence.** Mid-run gaps — including a mid-run
33
- `idea`/`defined` unit's product-half gaps in the DESIGN stage — are resolved
34
- from the decision record and logged; contradictions park the feature with
35
- the evidence recorded. Re-interviewing mid-run is forbidden, in DESIGN as in
36
- every other stage: an undesignable unit is parked (`NEEDS_INPUT` on that
37
- unit, `state: CONTINUE` on the run), never asked about. The recovery from a
38
- wrong founding call is a reported stop and a human-restarted run.
39
- - **Scope discipline.** Defects and ideas discovered mid-run become report
40
- proposals — never automatically-created issues or in-run side quests. Only
41
- existing user/forge issues enter the issue sweep.
42
- - **Stack/architecture/forge agnostic; English artifacts** regardless of the
43
- interview language; recommendations proportional to the interviewed scale,
44
- recorded in the project's own docs so every sub-skill discovers them through
45
- its normal Step 0.
46
-
47
- **Known limits (stated, not hidden):** subagent overrides pin the model but
48
- not the effort, so execution subagents inherit the session's effort — cost can
49
- drift if the session runs high. `/loop`'s stop-on-banner matching should be
50
- treated as a convenience, not a guarantee — iterations after a terminal banner
51
- are idempotent no-ops, and the loop can always be stopped manually. Budget caps
52
- count iterations, not tokens — and the count lives in the machine-local log, so
53
- it bounds each machine's run, not the run's lifetime across machines. Verdicts
54
- persist in the run log and feature docs,
55
- but a crash between PR close-out and review may re-run one receipt check —
56
- accepted cost, never a correctness risk.
@@ -1,16 +0,0 @@
1
- ### Model routing
2
-
3
- | Stage | Tier | Mechanism |
4
- |---|---|---|
5
- | Interview, founding, roadmap creation | opus/high | this skill's frontmatter; composes `init-workspace` (equal tier), answers pre-fed |
6
- | Recovery, routing, logging | opus/high | in-turn (tiny token volume; a subagent would add cost, not save it) |
7
- | JIT feature design (mid-run `idea`/`defined` unit) | opus/high | compose `design-feature` + `plan-feature-scaffold` in-turn (equal tier, deriving only from `SHIP_DECISIONS.md` — no new questions) |
8
- | JIT feature planning | opus/high | compose `plan-feature` in-turn (its internals are opus/high–medium: ≥ holds) |
9
- | Product review (REVIEW-SPEC) | opus/high | `review-spec` in a **clean context** (fresh subagent or outside headless call) — never the turn that wrote the product half; tier equals or exceeds the author's, so the ≥ rule holds |
10
- | Plan review (REVIEW-PLAN) | opus/high | `review-plan` in a **clean context**, same rule; it judges the plan the previous stage froze |
11
- | Phase execution, single-pass, fixes | **cheap worker** | fresh context per phase following `execute-phase`; Claude branch maps this role to `sonnet`, portable drivers use their validated worker tier |
12
- | Final review/correction loop | opus/high | compose the manual path `/review-change`, then `/fold-findings` (only on `REVIEW-FAIL`), then re-run `/review-change`; it reuses a current exact-SHA receipt or reviews context-clean, and routes unresolved findings to `triage-issue --prioritize-now` |
13
- | Merge gate | opus/high | compose `audit-pr` in-turn (the highest-stakes automated verdict; must share one turn with the floor checks) |
14
- | Forge/git mechanics | — | Bash tool calls; no model judgment involved |
15
- | Final-report evidence gathering | haiku (optional) | fan-out subagents for grep-shaped per-feature log collection when ultracode is on; synthesis stays opus |
16
- | `product-audit` | opus/max | **never composed, never imitated by a subagent** — its effort (max) exceeds the conductor's (high) and a subagent override cannot carry `effort: max`. Hand-off only: the report prescribes when to run it. |
@@ -1,34 +0,0 @@
1
- ## Portability (agents other than Claude Code)
2
-
3
- The workflow is the contract; Claude Code features are conveniences. This skill
4
- leans on them harder than any other — here is the manual equivalent of each:
5
-
6
- - **No `/loop`** — two equivalent replacements, both vendor-neutral: (a) an
7
- **external orchestrator** loops `/ship-roadmap --continue` headless and
8
- routes its native fixed `SHIP:` banner plus closing `→ Next:` block (full
9
- protocol + driver skeleton in `docs/workflow/ORCHESTRATION.md`); (b) manual
10
- re-invocation after each iteration. Iterations are
11
- stateless-by-reconstruction, so any driver is exactly equivalent; stop when
12
- the first line is a terminal `SHIP:` banner. **Every iteration ending is
13
- announced** — "iteration complete (normal; re-invoke to continue)" vs a
14
- parked/terminal reason — so a stop is never ambiguous.
15
- - **No subagents** — execute phases sequentially: for each phase, one **fresh
16
- headless invocation (or conversation) on a cheaper model** following the
17
- installed `execute-phase` SKILL.md for exactly one phase (same two autopilot
18
- overrides) — the external-driver pattern in `docs/workflow/ORCHESTRATION.md`
19
- does exactly this. The conductor stages (recover/plan/PR/review/audit) stay
20
- on your strongest model.
21
- - **No slash-command menu** — where this skill says `/<skill>`, open that
22
- skill's `SKILL.md` (wherever your agent installed the skills) and follow it
23
- literally in the conversation the routing table assigns it (in-turn = this
24
- conversation; subagent/hand-off = a fresh one).
25
- - **No per-skill `model:`/`effort:`** — the `#claude` branch's routing table pins these tiers; here, pick tiers yourself:
26
- judgment stages on your **strongest** model, implementation on a cheaper one,
27
- and `product-audit` always as its own maximum-effort run.
28
- - **Provider concurrency limits** — when spawning parallel subagents (or
29
- parallel headless invocations), cap concurrency at the provider's documented
30
- parallel-request limit per API key, leaving one slot free for the conductor
31
- (e.g. a provider allowing 5 concurrent requests → at most 3–4 parallel
32
- executors). An agentic loop spends one request per tool round-trip, so
33
- parallel executors also eat the per-minute request budget fast; on a 429,
34
- reduce parallelism before retrying rather than hammering the limit.
@@ -1,94 +0,0 @@
1
- ### Mode B — One loop iteration: `/ship-roadmap --continue [--fullauto]`
2
-
3
- Every iteration is stateless-by-reconstruction — no memory is assumed between
4
- turns:
5
-
6
- 1. **RECOVER.** Read `SHIP_DECISIONS.md` (missing → `SHIP: STOPPED — no run
7
- policy; run /ship-roadmap first`) and `.ship-run.log` (missing on this
8
- machine → recreate empty; policy lives in the committed record). **Verify
9
- the substrate landed:** `SHIP_DECISIONS.md` must exist on the default
10
- branch — an open `docs/ship-founding` PR means the substrate isn't merged
11
- yet → `SHIP: BLOCKED` with "merge the founding PR" as the unblock map.
12
- Read ROADMAP.md; query the forge for open/merged PRs on `feat/*`, `fix/*`,
13
- `docs/ship-founding` and `docs/ship-report` heads; check git state.
14
- Reconcile: a feature flips to `done` when its **PR opens** (built, not merged
15
- — see the PR stage), so a `done` row with an open PR is awaiting a human merge
16
- (default mode), not finished shipping. A **merged** PR needs no status change
17
- (already `done`) — it means *shipped*, and **unblocks its dependents** + counts
18
- toward `SHIP: COMPLETE`. The done-flip rides the PR-bound commit, never a lone
19
- commit on the default branch. A dirty feature branch from a crashed phase
20
- is handed to the next phase subagent to finish or restart (counts against
21
- the red-gate retry cap). Uncommitted changes on the default branch confined
22
- to `docs/features/<NN-slug>/` + ROADMAP.md that match an in-flight roadmap
23
- row are the loop's own planning output — resume that feature; the
24
- dirty-default stop fires only for changes matching no roadmap unit.
25
- 2. **STOP-CHECK.** Evaluate the stop conditions (below). Terminal → write or
26
- refresh the final report, open the report PR, print the `SHIP:` banner +
27
- status table, end the turn.
28
- 3. **SELECT one unit.** Priority order, first match wins:
29
- 1. **Urgency labels first (feature 15, injection-safe).** Read
30
- `workflow-status`'s `detail.urgent` (labels-only, presence-only —
31
- never derived from issue text; see `skills/triage-issue/SKILL.md`, the
32
- sole owner of the `urgent`/`fix-next` vocabulary):
33
- - Any open issue labeled **`fix-next`** → its fix jumps to the head of
34
- the queue exactly like a blocking fix below (`plan-fix` →
35
- `execute-phase --fix`), **no interrupt** of the in-flight unit — it
36
- waits for the current stage to finish this iteration, then is
37
- SELECTed next.
38
- - Any open issue labeled **`urgent`** → run the canonical pause-vs-finish
39
- rubric in `docs/workflow/ORCHESTRATION.md` **by reference, never
40
- forked here** — feed it the issue content plus `detail.urgent
41
- .interruptibility` for the current in-flight unit.
42
- `INTERRUPT_NOW` → park the in-flight unit (WIP commit + `progress.md`
43
- note, same as any voluntary park) and SELECT the urgent issue's fix as
44
- this iteration's unit instead. `FINISH_FIRST` → this iteration
45
- proceeds normally (steps below); the urgent fix is queued head-of-line
46
- for the **next** iteration, same as `fix-next`.
47
- - No `urgent`/`fix-next` issues in `detail.urgent` → fall through to the
48
- normal priority order below.
49
- 2. **Blocking fixes first.** A fix-index entry classified fix-now whose
50
- subject blocks the next startable feature (same module, a dependency's
51
- defect, or a red gate cause) → its fix is the selected unit
52
- (`plan-fix` → `execute-phase --fix` through the normal stages). Fixes
53
- that block nothing wait for the report's triage batch.
54
- 3. An in-progress feature's next pending stage.
55
- 4. The next feature at status `idea` **or** `planned` whose depends-on rows
56
- are all **merged** (forge state, not merely `done` — a `done` dep with
57
- an open PR isn't on the default branch yet, so a dependent cut from it
58
- would lack its code). A `defined`-but-not-`planned` row is treated the
59
- same as `idea` here — its design exists but its planning artifacts
60
- don't, so it still needs a scaffold pass before PLAN.
61
- **Verify the closure transitively:** a dep row marked merged whose own
62
- dependencies aren't merged means the roadmap's statuses are inconsistent
63
- → `SHIP: STOPPED` (substrate invariant broken), never build on top of it.
64
- → `idea`/`defined`: DESIGN first (see ADVANCE). `planned`: → REVIEW-SPEC/
65
- REVIEW-PLAN if its receipt for that stage is missing or stale, else PLAN/EXECUTE
66
- directly.
67
- 5. **Issue sweep — features exhausted, run NOT over.** Every roadmap feature
68
- is `done` **and merged** but the sweep hasn't completed → the run
69
- continues with issues; finishing the features is not finishing the run:
70
- 1. **INVENTORY (once per run, its own iteration).** Enumerate (a) every
71
- open forge issue and fix-index entry; (b) every *documented residue*
72
- the run itself generated — each feature's `known-issues.md`, the
73
- trade-offs in `decisions.md`, and every review report's
74
- proposals/trade-offs. Residue without an existing issue remains a
75
- deduplicated **proposal** in the report; the run never creates backlog
76
- to make inventory look complete. Log existing issue numbers and
77
- proposal sources separately.
78
- 2. **TRIAGE (compose `triage-issue` in-turn, equal tier).** Classify
79
- each existing inventoried issue against the CURRENT codebase. fix-now → it
80
- becomes a selectable unit; postpone / wontfix / promote-to-feature →
81
- the dated verdict is recorded on the issue and carried into the
82
- report (promotions and untracked residue become report proposals,
83
- never in-run scope or automatically-created issues).
84
- 3. **SHIP the fix-now issues** one unit at a time through the normal
85
- stages (`plan-fix` → REVIEW-PLAN → EXECUTE (`--fix`) → PR → REVIEW → AUDIT), same
86
- budget caps, floors, and merge policy as features.
87
- 6. Nothing startable → `SHIP: BLOCKED` with the **unblock map** ("merging
88
- issue `#<n>` unblocks features `05` and `07`") and the resume command.
89
-
90
- `execute-phase`'s own dependency gate stays active inside every subagent —
91
- it's the belt to this braces. **The autopilot never passes `--force`:** a
92
- gate stop inside a subagent parks the feature with the unmet chain recorded;
93
- forcing through unmet dependencies is a human-only decision, made outside
94
- the loop.
@@ -1,9 +0,0 @@
1
- ### Stop conditions
2
-
3
- | Banner | Fires when |
4
- |---|---|
5
- | `SHIP: COMPLETE` | Every roadmap feature is `done` **and its PR merged** (default mode: the human merged them all; `--fullauto`: merged under the floors) — `done` alone is not enough, since it only means *built + PR open* — **AND the issue sweep ran to completion**: existing issues inventoried/triaged, every fix-now issue shipped or parked, and untracked residue deduplicated as report proposals without creating backlog. Features merged but sweep pending → the run is NOT complete. Report written, report PR open. |
6
- | `SHIP: BLOCKED` | Everything remaining is `done`-but-pr-open awaiting human merges, or planned with unmerged deps (default mode); or a parked feature transitively blocks the rest. Always includes the unblock map. |
7
- | `SHIP: STOPPED` | Budget/iteration cap; a Round-5 milestone stop line; substrate invariant broken (gate unrunnable, roadmap unparseable, unexplained dirty default branch, decision record missing); forge unavailable (no stage that depends on PR state may proceed on guesses). |
8
- | (feature parked, run continues) | Repeated red gate (retry cap), review ping-pong (2 cycles), audit ping-pong (2 cycles), capacity guard (3 partials), planning contradiction, **undesignable-from-record** (DESIGN stage `NEEDS_INPUT` — the recorded gap is a human-only unpark, never a mid-run re-ask). |
9
- | **Systemic drift stop** | `review-change` flags SPEC drift on **two consecutive features** → the locked founding assumptions are probably stale; the whole run stops rather than auto-merging a compounding error. |
@@ -1,34 +0,0 @@
1
- ### Final report
2
-
3
- Written by the terminal iteration to `docs/features/SHIP_REPORT_<date>.md` on a
4
- `docs/ship-report` branch as a docs-only PR (default: human merges; `--fullauto`:
5
- audit-gated like any PR), and printed in full under the banner:
6
-
7
- 1. **Run summary** — mode, iterations used vs cap, stop reason, feature counts
8
- (merged / `done`-awaiting-merge / parked / not started).
9
- 2. **Per-feature outcomes** — size planned vs final, phases, gate history,
10
- review findings folded vs postponed, audit verdict + SHA, PR + final state,
11
- merged by human or autopilot.
12
- 3. **Issues** — the sweep's existing-issue inventory and outcomes: fix-now issues
13
- shipped (PR links), postponed/wontfix verdicts with the trigger that
14
- should reopen each (feeds `triage-issue`'s verification model), and
15
- anything the sweep could not finish (budget/parked) as the explicit
16
- remaining triage batch. Untracked residue is listed separately as proposals;
17
- the run created no backlog for it.
18
- 4. **New feature proposals** — capabilities discovered during the build that
19
- serve the product goal (Round 1 quoted as the yardstick), each sized with a
20
- suggested roadmap slot. Recommend-only.
21
- 5. **Residual risks** — weak test areas, `--fullauto` merges deserving a second
22
- look, parked features and why, silent decisions with outsized consequences.
23
- 6. **Manual-verification checklist** — the deduplicated union of every review
24
- checkpoint's manual checks plus audit notes: what no gate proved.
25
- 7. **Going forward** — concrete `product-audit` cadence for this project
26
- (first one now if ≥2–3 features merged; then ~every 5 or pre-release), and
27
- the suggested command sequence to continue, closed with the canonical block:
28
-
29
- ```
30
- → Next: <merge the open PRs | /triage-issue <batch> | /plan-feature --next>
31
- · accepted proposals → /plan-feature · product-audit due → /product-audit
32
- ```
33
-
34
- Closing line, verbatim policy: **this report recommends; the human decides.**