dev-loops 0.6.0 → 0.7.2

package/.claude/skills/local-implementation/SKILL.md

@@ -39,11 +39,17 @@ Treat missing optional files as normal bootstrap conditions, not errors.
 
 ### Tracker-backed local implementation
 
-Local implementation supports two durable spec inputs:
+Local implementation supports these spec-of-record inputs. The first two are durable/committed artifacts; the third is a spec-of-record that is NOT a durable committed artifact:
+
+Durable/committed spec artifacts:
 
 - phase-doc-backed local sessions ([Phase Plan](../../docs/phases/phase-x.md) is canonical)
 - tracker-backed local sessions (the tracker issue is canonical)
 
+Non-durable spec-of-record (no committed plan artifact):
+
+- lightweight PR-body-as-spec sessions (`--lightweight`; the PR description is the canonical spec-of-record but NOT a durable committed artifact — the resolver output carries `canonicalSpecSource: pr_body` and the derived handoff envelope carries `specSource: pr_body`; no phase/plan doc minted or committed). Same gate sequence as the phase-doc path; only the backing artifact differs. See [Artifact Authority Contract](../docs/artifact-authority-contract.md) "Lightweight (PR-body-as-spec)".
+
 Tracker-backed local implementation stays inside the existing `local_implementation` path. For sub-issue tree decomposition, see [Sub-Issue Tree Contract](../../docs/sub-issue-tree-contract.md) (this is a source-repo reference; it is not part of the bundled `../docs/` runtime contract surface for installed skill copies). It does not introduce a new routing mode.
 
 When the local spec already lives in a tracker issue:
@@ -51,47 +57,38 @@ When the local spec already lives in a tracker issue:
 - resolve the tracker reference deterministically from a GitHub issue URL or explicit `<owner/name>` + issue number
 - use the bounded GitHub helper `scripts/github/resolve-tracker-local-spec.mjs` when you need a machine-readable spec bundle
 - treat the tracker issue title/body/url/state as the durable local spec bundle
-- do not create or read [Phase Plan](../../docs/phases/phase-x.md) for that same tracker-backed session
+- the no-duplicate-phase-doc rule is owned by `ARTIFACT-TRACKER-FIRST-NO-DUP` in [Artifact Authority Contract](../docs/artifact-authority-contract.md); do not read [Phase Plan](../../docs/phases/phase-x.md) for that same tracker-backed session either
 - sync durable scope / acceptance / status changes back to the tracker issue rather than maintaining a duplicate local phase doc
 - keep `tmp/` as temporary local execution state only; it does not become a second durable spec surface
 - for tracker-backed sessions, the handoff path is always: push the working branch → open a PR → merge via GitHub
-- for tracker-backed sessions, always open PRs through the canonical `dev-loops pr create` path, which is ALWAYS draft and always assigned — self-assigned by default (`--assignee @me` when none is given; honors an explicit `--assignee <login>` / `-a <login>`), never via raw `gh pr create`. The PR body must contain `Closes #N` (or `Fixes #N`) for the linked issue so GitHub auto-closes it on merge. When `.devloops` sets `workflow.requireDraftFirst` to true, use `dev-loops pr create --assignee @me ...`. Do not create a fresh PR directly in ready-for-review state unless the user explicitly overrides that policy for the current PR scope. The draft gate inspection is a real workflow boundary.
-- do not suggest a direct local-main merge for tracker-backed sessions; do not merge the working branch into local `main` at phase completion
+- <!-- rule: LOCAL-PR-CREATE-CANONICAL --> for tracker-backed sessions, you MUST open PRs through the canonical `dev-loops pr create` path — always draft and always assigned — self-assigned by default (`--assignee @me` when none is given; honors an explicit `--assignee <login>` / `-a <login>`) — and MUST NOT open them via raw `gh pr create`. The PR body MUST contain `Closes #N` (or `Fixes #N`) for the linked issue so GitHub auto-closes it on merge. When `.devloops` sets `workflow.requireDraftFirst` to true, use `dev-loops pr create --assignee @me ...`; the draft-first requirement itself is owned by [`OPS-DRAFT-FIRST-PR`](../docs/copilot-loop-operations.md).
+- <!-- rule: LOCAL-TRACKER-NO-DIRECT-MERGE --> `LOCAL-TRACKER-NO-DIRECT-MERGE`: for tracker-backed sessions, agents MUST NOT suggest a direct local-main merge and MUST NOT merge the working branch into local `main` at phase completion
 
 ## Primary execution rules
 
 ### Step 0: Pre-flight gate (mandatory for local_implementation)
 
-For the `local_implementation` strategy, before any planning or implementation mutation, run the pre-flight gate:
+<!-- rule: LOCAL-PREFLIGHT-GATE-MANDATORY -->
+For the `local_implementation` strategy, before any planning or implementation mutation, you MUST run the pre-flight gate:
 
 ```sh
 node scripts/loop/pre-flight-gate.mjs --expected-branch <working-branch> --check-subagents
 ```
 
-Before creating or reusing a worktree for local implementation, use the canonical lifecycle entrypoint, which fetches the base remote, then creates-or-reuses the worktree at its namespaced path and provisions it in one step:
+Before creating or reusing a worktree for local implementation, use the canonical lifecycle entrypoint (`WORKTREE-CREATE-PROVISION`, see [Worktree usage guidance](../../docs/worktree-guidance.md#create-or-reuse--provision-ensure-worktreemjs)):
 
 ```sh
 node scripts/loop/ensure-worktree.mjs --repo-root <main> --issue <n>
 ```
 
-This creates (or reuses) the worktree at `tmp/worktrees/dev-loops/<kind>-<n>` from a freshly fetched `origin/main` (the authoritative base for all worktree creation) and provisions its gitignored runtime files. Raw `git worktree add -b <branch> tmp/worktrees/dev-loops/<kind>-<n> origin/main` is the underlying mechanism `ensure-worktree.mjs` runs for you. See [worktree guidance](../../docs/worktree-guidance.md).
-
-This validates:
-- Worktree isolation (current directory is under `tmp/worktrees/`)
-- Branch identity (current branch matches the working branch)
-- Subagent availability (subagents should be used for fan-out when available)
-
-If the gate fails, **stop and fix the violation** before proceeding. Do not bypass the gate in normal workflow execution.
+This validates worktree isolation (current directory under `tmp/worktrees/`) and branch identity (current branch matches the working branch); `--check-subagents` only reports subagent availability and is advisory (fails-open, does not block the gate). If the gate fails, **stop and fix the violation** before proceeding — do not bypass it in normal workflow execution.
 
-Note: `--check-subagents` is advisory — it reports availability but does not block the gate. The worktree and branch checks are the mandatory gates.
-
-This gate does **not** apply to other routed strategies (`copilot_pr_followup`, `external_pr_followup`, `reviewer_fixer`, `wait_watch`, `final_approval`, `issue_intake`). Those strategies have their own execution rules and may edit code from any checkout as needed.
-
-Development-only bypass (`DEVLOOPS_PREFLIGHT_BYPASS=1`) exists for testing the gate itself but must not be used in production workflow runs. The bypass variable is a testing convenience, not an operational escape hatch.
+This gate does **not** apply to other routed strategies (`copilot_pr_followup`, `external_pr_followup`, `reviewer_fixer`, `wait_watch`, `final_approval`, `issue_intake`); those strategies have their own execution rules and may edit code from any checkout as needed. The development-only bypass (`DEVLOOPS_PREFLIGHT_BYPASS=1`) exists for testing the gate itself and MUST NOT be used in production workflow runs — it is a testing convenience, not an operational escape hatch.
 
 ## Narrow failure-triage fast path
 
-When resuming local implementation with dirty work or an observed failing command, use this path before broad discovery:
+<!-- rule: LOCAL-FAILURE-TRIAGE-ORDER -->
+When resuming local implementation with dirty work or an observed failing command, you MUST follow this ordered path before broad discovery:
 
 1. run startup once from the relevant worktree/context
 2. inspect current state with `git status` and the changed files
@@ -105,20 +102,13 @@ Follow [Anti-patterns](../docs/anti-patterns.md) for the general tooling-interna
 
 ### Step 1
 
-- Implement **one phase at a time**.
-- Do not refine later phases in detail before the current phase is complete.
+- <!-- rule: LOCAL-PHASE-ONE-AT-A-TIME --> You MUST implement **one phase at a time** and MUST NOT refine later phases in detail before the current phase is complete.
 - Use the `refiner` agent for phase-refinement work when subagents are available; escalate RFC-worthy technical decisions to the parent session / human operator.
-- Work **test-first** for all non-trivial logic.
-- Maintain **90% coverage** thresholds.
+- <!-- rule: LOCAL-TEST-FIRST-COVERAGE --> You MUST work **test-first** for all non-trivial logic and SHOULD maintain **90% coverage** thresholds (coverage is not enforced by the shipped verify config; treat it as the working target).
 - Log detailed iteration artifacts under `tmp/` using the required structure below.
-- For phase-doc-backed local sessions, keep durable phase intent and acceptance criteria in [Phase Plan](../../docs/phases/phase-x.md); for tracker-backed local sessions, keep that durable intent in the tracker issue and do not duplicate it into [Phase Plan](../../docs/phases/phase-x.md). Keep detailed execution artifacts in `tmp/`.
-- Treat `tmp/` as temporary local execution state. Do not rely on it as durable repo history and do not force-add it to git unless the user explicitly wants checked-in examples or fixtures.
+- Spec-of-record split (phase-doc-backed vs. tracker-backed vs. lightweight): see [Tracker-backed local implementation](#tracker-backed-local-implementation) above.
 - When a phase changes durable product truth in ways `PLAN.md` should express (for example command surface, accepted product decisions, resolved open questions, or scope changes), update [Project Plan](../../PLAN.md) before closing the phase.
-- Do implementation work on a dedicated local branch, not directly on `main`.
-- If the repo has no commits yet, still create the working branch first so the first commits land off `main`; only move `main` forward after review and validation.
-- Use small atomic local commits as progress checkpoints whenever a coherent slice is green and reviewable.
-- Before a branch is considered review-complete, approval-ready, merge-ready, or ready for final handoff, run the default pre-approval gate as a full review / fix loop with the review angles resolved from config (`resolveGateAngles(config, "preApproval")`), then apply accepted fixes and rerun validation. Shipped defaults include the `deep` angle.
-- A phase is only fully complete when its scoped work, required support files, artifacts, validation, review/fix pass, commit(s), and finalization (merge into local `main` for phase-doc-backed sessions; PR merge for tracker-backed sessions) are done, or when the only remaining step is an explicitly noted authorization-gated finalization action.
+- Branch, commit, pre-approval-gate, and finalization mechanics: see [Branch / review / merge policy](#branch--review--merge-policy), [Commit policy](#commit-policy), and [Implementation loop for the phase](#implementation-loop-for-the-phase) below.
 - When subagents are used, log what each subagent was asked to do and what it concluded.
 - If [Project Plan](../../PLAN.md) is too rough or ambiguous to safely start the current phase, do not guess: run a clarification/interview step with the user first.
 
@@ -126,34 +116,16 @@ Follow [Anti-patterns](../docs/anti-patterns.md) for the general tooling-interna
 
 Apply [Structural Quality](../docs/structural-quality.md) from the `deep` review angle.
 
-## Light mode (small changes) — config-only
+## Light mode (small changes)
 
-Light mode is currently **config-only**: the schema, resolver, and scope detector are implemented, but no functional wiring exists yet in the local-implementation flow. When scope is small enough, the intent is to skip fan-out/fan-in and use a single review pass instead. Light mode will still require validation and pre-approval gate once wired.
+<!-- rule: LOCAL-LIGHT-MODE-CONFIG-SURFACE -->
+`localImplementation.lightMode` (`.devloops` field; this repo sets `maxLines: 20`, `maxFiles: 2`) is this skill's config surface for light-mode gate dispatch. Gate-collapse mechanics, escalation, and dispatch resolution (`resolveGateDispatchMode`, `scripts/loop/resolve-gate-dispatch.mjs`) are owned by [Light-mode inline acceptance](../../docs/gate-review-sub-loop-contract.md#light-mode-inline-acceptance-under-threshold-micro-prs); this skill MUST NOT redefine them.
 
-**Eligibility:** ≤3 files AND ≤200 lines changed (configurable via `.devloops` field `localImplementation.lightMode`).
-
-Use `scripts/loop/detect-change-scope.mjs` to determine eligibility:
+Use `scripts/loop/detect-change-scope.mjs` to determine scope:
 ```sh
 node scripts/loop/detect-change-scope.mjs
 ```
 
-**Planned light mode path (not yet wired):**
-1. Validation (`npm run verify`)
-2. Single review pass (not multi-angle fan-out)
-3. Pre-approval gate
-4. Finalization
-
-**Override threshold:**
-```yaml
-localImplementation:
-  lightMode:
-    enabled: true
-    maxFiles: 5
-    maxLines: 300
-```
-
-Disabled by default (opt-in). Scope above threshold falls back to full fan-out/fan-in path.
-
 ## Deterministic logging structure
 
 Treat the workflow as three layers:
@@ -260,6 +232,10 @@ For the **current phase only**, run this loop before implementation.
 
 ### 1. Create or update the durable phase doc and tmp scaffold
 
+**Lightweight (PR-body-as-spec) exception:** when the session is lightweight — the resolver output carries `canonicalSpecSource: pr_body` and the derived handoff envelope carries `specSource: pr_body` (started via `resolve-dev-loop-startup.mjs --issue <n> --lightweight`) — SKIP the durable phase-doc mint entirely. The PR description is the spec-of-record; do NOT create or commit any `docs/phases/*.md` for this session. The ephemeral `tmp/phases/` scaffold may still be used for local execution state. All other steps (read prior learning, plan, implement) proceed unchanged, and the gate sequence (draft → pre-approval fanout → detect-evidence → human merge) is identical. See [Artifact Authority Contract](../docs/artifact-authority-contract.md) "Lightweight (PR-body-as-spec)".
+
+Otherwise (default phase-doc path), create or update the durable phase doc.
+
 Use paths like:
 - `docs/phases/phase-0.md`
 - `tmp/phases/phase-0/`
@@ -395,7 +371,8 @@ If the review finds real issues, revise the merged plan and briefly update the r
 
 ### 6. Only then start implementation
 
-Do not begin coding before the merged phase plan has passed review.
+<!-- rule: LOCAL-PLAN-REVIEW-GATE -->
+You MUST NOT begin coding before the merged phase plan has passed review.
 Update `manifest.json` to show that phase implementation has started.
 
 ## Task breakdown & delegation
@@ -414,7 +391,8 @@ into parallel executable tasks and dispatch them to the right specialist subagen
 
 ### Delegation contract
 
-Dispatch implementation tasks to dedicated specialist agents:
+<!-- rule: LOCAL-DELEGATION-TABLE -->
+Implementation tasks MUST be dispatched to dedicated specialist agents per this table:
 
 | Task type | Delegate to |
 |---|---|
@@ -514,7 +492,7 @@ After the phase plan passes review:
 5. Run the default pre-approval gate as a full review / fix loop on the branch before calling it review-complete, approval-ready, merge-ready, or ready for final handoff:
    - resolve review angles from config: `resolveGateAngles(config, "preApproval")` from `@dev-loops/core/config` (shipped defaults enable all 11 pre-approval gate angle families; consumer repos may opt out individual angles via `excludeAngles`); run via the chain prescription below
    - run the resolved angle-focused passes in parallel with fresh context when practical
-   - if parallel execution is impractical (for example due to tooling or resource constraints), run all angles sequentially and explicitly record why parallel execution was impractical in `Phase Review` (`tmp/phases/phase-x/review.md`) (or the equivalent merged review artifact)
+   - the sequential-fallback rule is owned by `GATE-EXEC-FANOUT-SEQUENTIAL-FALLBACK` in [Gate Review Sub-Loop Contract](../../docs/gate-review-sub-loop-contract.md); when it applies, record the fallback in `Phase Review` (`tmp/phases/phase-x/review.md`) (or the equivalent merged review artifact)
    - for each angle, resolve its persona and prompt via `resolveReviewerRole(config, angle)` — start each reviewer in fresh context with a concise briefing including the angle-specific prompt, the branch/phase, intended behavior, acceptance criteria, relevant files or artifacts, and current validation status
    - run the mandatory chain defined in [Gate Review Sub-Loop Contract](../../docs/gate-review-sub-loop-contract.md). Retry rule: in subsequent cycles, only re-run reviewers that produced findings in the previous pass. Do not fork the parent session for parallel reviewers; write a compact handoff artifact under `tmp/` and point the reviewer at it.
    - when reviewer subagents stumble on raw source-tree reads (for example unresolved build artifacts or import assumptions), generate a deterministic diff/review artifact under `tmp/` and have reviewers inspect that artifact instead of the raw file set
@@ -528,8 +506,8 @@ After the phase plan passes review:
 9. Write `Retrospective` (`tmp/phases/phase-x/retrospective.md`) using [Retrospective Template](../dev-loop/templates/retrospective.md).
 10. Update `tmp/phases/phase-x/manifest.json` and `tmp/phases/index.json`.
 11. Update [Implementation State](../../docs/IMPLEMENTATION_STATE.md).
-12. **Exit validation gate — no uncommitted changes.** Before the subagent session terminates, run `git status --porcelain` and verify the output is empty. If uncommitted changes exist, first determine whether they are intended implementation changes or unintended/post-validation deltas. Revert any unintended or speculative changes. For intended changes, rerun the narrowest justified validation (`npm run verify` or equivalent) before staging and committing with an appropriate message; for tracker-backed sessions, also push the branch. A subagent session that exits with uncommitted changes in the worktree is a workflow defect and must not be treated as a clean completion. After committing, verify `git status --porcelain` is empty before declaring phase completion.
-13. For tracker-backed sessions, create the PR from the working branch using the canonical `dev-loops pr create --assignee @me --repo <owner/name> --base main --head <branch> --title "..." --body-file <body-file>` (always draft, self-assigned by default; `--assignee @me` is the default and is shown here for clarity). When the `dev-loops` CLI helper is unavailable, use the equivalent `create-pr.mjs` script directly: `node <resolved-skill-scripts>/github/create-pr.mjs --repo <owner/name> --assignee @me --base main --head <branch> --title "..." --body-file <body-file>`. Never open a PR with raw `gh pr create`. The PR body must contain `Closes #N` (or `Fixes #N`) for the linked issue. Do not create a fresh PR directly in ready-for-review state unless the user explicitly overrides that policy.
+12. <!-- rule: LOCAL-COMMIT-BEFORE-EXIT --> **Exit validation gate — no uncommitted changes.** Before the subagent session terminates, run `git status --porcelain` and verify the output is empty. If uncommitted changes exist, first determine whether they are intended implementation changes or unintended/post-validation deltas. Revert any unintended or speculative changes. For intended changes, rerun the narrowest justified validation (`npm run verify` or equivalent) before staging and committing with an appropriate message; for tracker-backed sessions, also push the branch. A subagent session that exits with uncommitted changes in the worktree is a workflow defect and MUST NOT be treated as a clean completion. After committing, verify `git status --porcelain` is empty before declaring phase completion.
+13. For tracker-backed sessions, create the PR from the working branch: `dev-loops pr create --assignee @me --repo <owner/name> --base main --head <branch> --title "..." --body-file <body-file>` (fallback when the CLI helper is unavailable: `node <resolved-skill-scripts>/github/create-pr.mjs --repo <owner/name> --assignee @me --base main --head <branch> --title "..." --body-file <body-file>`); never raw `gh pr create`. Draft/assignment/`Closes #N` policy: [LOCAL-PR-CREATE-CANONICAL](#tracker-backed-local-implementation) above.
 14. If authorized, merge the fully reviewed, locally validated phase branch back into local `main` (phase-doc-backed sessions) or proceed through the PR gate pipeline (tracker-backed sessions).
 15. If authorization for PR creation or merge is still pending (commit authorization is already enforced by the exit validation gate in step 12), mark the phase as `awaiting-finalization` rather than `completed`, and record exactly which finalization step is pending.
 
@@ -542,85 +520,32 @@ The retrospective must capture:
 - what should change in the skill or workflow next time
 - what a fresh session should know before the next phase
 
-This is the infrastructure for self-improvement. Do not skip it.
+<!-- rule: LOCAL-RETROSPECTIVE-REQUIRED -->
+This is the infrastructure for self-improvement; you MUST NOT skip it.
 
 ## Dev mode
 
-Dev mode is for improving the local implementation loop itself while using it.
-
-A repository may also declare a formal-dev-mode default through `.devloops` field `workflow.devModeDefault`. Treat that config as the policy source of truth when present, but explicit user opt-in or opt-out for the current run still wins. Runtime consumption of that config may be staged separately from this documentation update.
-
-Trigger it when the user explicitly asks for dev mode, self-improvement mode, or says they want the skill to refine itself as it goes.
-
-In dev mode, after the normal phase summary and retrospective are written, run one extra bounded self-improvement pass before moving on:
-
-1. collect a deterministic context bundle for the phase using:
-   - `../dev-loop/scripts/dev-mode-context.mjs`
-   - output to `tmp/phases/phase-x/dev-mode-context.json`
-2. review the phase artifacts and logs with emphasis on the workflow itself:
-   - planning quality
-   - review quality
-   - validation friction
-   - bash exit-code-1 patterns
-   - places where skill or agent prompts should be tightened
-   - places where deterministic tooling should replace ad hoc work
-3. write `Dev Mode Retrospective` (`tmp/phases/phase-x/dev-mode-retrospective.md`)
-   - this is the required dev-mode retrospective artifact
-   - it should name the highest-value prompt/workflow follow-ups revealed by the phase
-4. optionally write `Dev Mode Review` (`tmp/phases/phase-x/dev-mode-review.md`) when separate analytical notes help support the retrospective
-5. apply at least one bounded follow-up update to a relevant skill and/or agent prompt
-   - deterministic tooling, docs, templates, or tests may accompany that change
-   - but they do not replace the required prompt update
-   - keep the change phase-bounded and tied directly to the retrospective findings
-6. write `Dev Mode Skill Changes` (`tmp/phases/phase-x/dev-mode-skill-changes.md`)
-   - record which skill and/or agent prompts changed
-   - record any supporting tooling/docs/template changes that accompanied them
-   - if no prompt update can be justified safely, stop and report that dev-mode exit criteria were not met
-7. if skill scripts or deterministic tooling changed, rerun the skill-local tests
-8. stop after this bounded self-improvement pass; do not recurse into endless self-editing loops
-
-Dev mode is still phase-bounded. It improves the loop around the completed phase; it does not authorize work on the next product phase.
+Dev mode improves the local implementation loop itself while using it. A repo may declare a default via `.devloops` field `workflow.devModeDefault`; explicit user opt-in/opt-out for the current run still wins over that default. Trigger it when the user explicitly asks for dev mode, self-improvement mode, or says they want the skill to refine itself as it goes.
 
-## tmp/ logging requirements
+After the normal phase summary and retrospective, run one extra bounded self-improvement pass:
 
-At minimum, each phase should leave behind:
-- a durable phase doc at [Phase Plan](../../docs/phases/phase-x.md)
-- local `tmp/` execution artifacts needed to resume and audit the phase, including:
-  - `manifest.json`
-  - `Variant A` (`tmp/phases/phase-x/variant-a.md`)
-  - `Variant B` (`tmp/phases/phase-x/variant-b.md`)
-  - `merged-plan.md`
-  - `review.md`
-  - `summary.md`
-  - `retrospective.md`
-  - optional `Variant C` (`tmp/phases/phase-x/variant-c.md`) when a third variant was actually useful
-  - `bash-exit-1.jsonl` when any bash call during the phase exited with code `1`
-  - `clarification.md` when a plan-sufficiency interview or auto-clarification step was needed
-  - subagent summaries when subagents were used
-  - raw subagent outputs only when they were saved separately on purpose
-  - in dev mode: `dev-mode-context.json`, `dev-mode-retrospective.md`, and `dev-mode-skill-changes.md`
-  - optional in dev mode: `dev-mode-review.md` when separate analytical notes were useful
-
-These `tmp/` artifacts are normally temporary and do not need to be checked into git.
-
-Also log validation output summaries and notable decisions if they help evaluate the local dev loop later.
-
-Additionally, append every bash call that exits with code `1` to:
-- `tmp/phases/phase-x/bash-exit-1.jsonl`
+1. Collect a deterministic context bundle: `../dev-loop/scripts/dev-mode-context.mjs` → `tmp/phases/phase-x/dev-mode-context.json`.
+2. Review the phase artifacts/logs for planning quality, review quality, validation friction, bash exit-code-1 patterns, and places where prompts or deterministic tooling should improve.
+3. Write `Dev Mode Retrospective` (`tmp/phases/phase-x/dev-mode-retrospective.md`) — required; name the highest-value prompt/workflow follow-ups revealed by the phase.
+4. Optionally write `Dev Mode Review` (`tmp/phases/phase-x/dev-mode-review.md`) when separate analytical notes help.
+5. Apply at least one bounded follow-up update to a relevant skill and/or agent prompt (supporting tooling/docs/template changes may accompany it but do not replace the prompt update), kept phase-bounded and tied directly to the retrospective findings.
+6. Write `Dev Mode Skill Changes` (`tmp/phases/phase-x/dev-mode-skill-changes.md`) recording which prompts and supporting changes landed; if no prompt update can be justified safely, stop and report that dev-mode exit criteria were not met.
+7. If skill scripts or deterministic tooling changed, rerun the skill-local tests.
+8. Stop after this bounded pass — do not recurse into endless self-editing loops.
 
-Use the deterministic helper:
-- `../dev-loop/scripts/log-bash-exit-1.mjs`
+Dev mode is still phase-bounded: it improves the loop around the completed phase and does not authorize work on the next product phase.
+
+## tmp/ logging requirements
 
-Each line should be one JSON object with at least:
-- `timestamp`
-- `phase`
-- `cwd`
-- `command`
-- `exitCode`
-- `purpose`
-- `summary`
+<!-- rule: LOCAL-TMP-EPHEMERAL-STATE -->
+The required durable-doc + `tmp/` artifact set for a phase is defined once in [Deterministic logging structure](#deterministic-logging-structure); this section MUST NOT duplicate that list. Those artifacts are normally temporary and do not need to be checked into git; do not force-add them unless the user explicitly wants checked-in examples or fixtures. Also log validation output summaries and notable decisions if they help evaluate the local dev loop later.
 
-If useful, also include truncated `stdout` and `stderr` fields or a path to a larger saved artifact. This log is for improving the local dev loop itself, so do not skip it just because the command was exploratory.
+Additionally, append every bash call that exits with code `1` to `tmp/phases/phase-x/bash-exit-1.jsonl` using the deterministic helper `../dev-loop/scripts/log-bash-exit-1.mjs`. Each line is one JSON object with at least `timestamp`, `phase`, `cwd`, `command`, `exitCode`, `purpose`, `summary` (optionally truncated `stdout`/`stderr` or a path to a larger saved artifact). This log improves the local dev loop itself, so do not skip it just because the command was exploratory.
 
 ## Stop conditions
 
@@ -628,28 +553,20 @@ See [Stop Conditions](../docs/stop-conditions.md). Local-specific stops: phase c
 
 ## Branch / review / merge policy
 
-- Do not implement directly on `main`.
-- Start or switch to a dedicated local working branch before the first mutating step.
-- If the repository is unborn (no commits yet), still create the working branch first and make the initial atomic commits there.
-- Use atomic local commits to log progress, but only for coherent reviewable slices.
-- Before merging, run a full parallel review / fix loop and resolve accepted findings on the same branch.
-- Rerun validation after review-driven fixes.
-- A phase is not operationally closed until its branch state is captured in commit history and the reviewed branch has been finalized according to session type (merged into local `main` for phase-doc-backed sessions; merged via GitHub PR for tracker-backed sessions), unless authorization for that finalization is still pending.
-- For tracker-backed sessions, the handoff path is always: push the working branch → open a PR → merge via GitHub; never merge the working branch into local `main`.
-- PR creation always goes through `dev-loops pr create`, which is ALWAYS draft and always assigned — self-assigned by default (`--assignee @me` when none is given; honors an explicit `--assignee <login>` / `-a <login>`), never via raw `gh pr create`, and the PR body must contain `Closes #N` (or `Fixes #N`) for the linked issue so GitHub auto-closes it on merge. When `.devloops` sets `workflow.requireDraftFirst` to true, use `dev-loops pr create --assignee @me ...`. Do not create a fresh PR directly in ready-for-review state unless the user explicitly overrides that policy for the current PR scope. The draft gate inspection is a real workflow boundary, so a new PR must exist in draft before `gh pr ready` is eligible.
-- When authorization is pending, record the phase as `awaiting-finalization` and describe the exact missing step.
+- Implement on a dedicated local working branch, never directly on `main`, switching to it before the first mutating step; if the repo is unborn (no commits yet), still create the working branch first and make the initial atomic commits there.
+- Use atomic local commits to log progress, but only for coherent reviewable slices — [Commit policy](#commit-policy) below governs commit timing/authorization.
+- Before merging, run a full parallel review / fix loop and resolve accepted findings on the same branch; rerun validation after review-driven fixes.
+- A phase is not operationally closed until its branch state is captured in commit history and the reviewed branch has been finalized according to session type (merged into local `main` for phase-doc-backed sessions; merged via GitHub PR for tracker-backed sessions); when authorization for that finalization is still pending, record the phase as `awaiting-finalization` and describe the exact missing step.
+- For tracker-backed sessions, the handoff path is always: push the working branch → open a PR → merge via GitHub; never merge the working branch into local `main`. PR creation follows [LOCAL-PR-CREATE-CANONICAL](#tracker-backed-local-implementation) above; a new PR must exist in draft before `gh pr ready` is eligible.
 - For phase-doc-backed sessions, merge the fully reviewed, locally validated branch back into local `main` when authorized.
+- Behind-branch integration before merge (for example a sibling PR merged first and both touch shared files): prefer a merge commit (`git merge origin/main`) over rebase + force-push. Since dev-loop PRs are squash-merged, intermediate branch history is discarded at merge time, so a merge commit lands an identical result on `main` while avoiding a non-fast-forward push to the remote. Force-push (`--force-with-lease` only, never bare `--force`) remains acceptable only for a branch the loop solely owns and where no integration alternative exists (rare); document that carve-out rather than leaving it implicit. After any integration that changes the head SHA, re-verify gate evidence at the new head (existing behavior — see [Merge Preconditions](../docs/merge-preconditions.md#required-before-merge)).
 
 ## Commit policy
 
-- Do not commit speculative work.
-- Do not commit before the relevant validation for that slice passes.
+- Do not commit speculative work or before the relevant validation for that slice passes.
 - Immediately before every `git add && git commit` sequence, assert branch identity with `git branch --show-current` and stop if it does not match the intended local working branch.
-- Keep commits small and phase-bounded.
-- Do not leave completed phase work stranded off `main`; once the reviewed branch is ready and authorized, finalize it according to session type (merge into local `main` for phase-doc-backed sessions; complete via PR merge for tracker-backed sessions).
-- Commit only when the coordination/main agent has decided the slice or phase is ready. **Exception:** in non-interactive subagent sessions, commit authorization is implicit — the subagent was dispatched to implement and must commit before exiting (see the commit sub-bullet under implementation loop step 3 and the exit validation gate in step 12).
+- Commit only when the coordination/main agent has decided the slice or phase is ready. **Exception:** in non-interactive subagent sessions, commit authorization is implicit — the subagent was dispatched to implement and must commit before exiting, enforced by [LOCAL-COMMIT-BEFORE-EXIT](#implementation-loop-for-the-phase) (implementation loop step 12; `git status --porcelain` must be empty before the session terminates).
 - If commit/merge authorization has not yet been given, do not call the phase `completed`; call it `awaiting-finalization` instead.
-- **Subagent exit contract:** before a subagent session terminates, the exit validation gate (implementation loop step 12) must pass — `git status --porcelain` must be empty. A subagent that exits with uncommitted changes in the worktree has not completed its task, regardless of what was implemented.
 
 ## Anti-patterns
 

package/.claude/skills/loop-grill/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: "loop-grill"
+description: "Standalone pre-loop Socratic Q&A grill for issues (tracker-first) or local plan files (local-planning). Detects spec gaps, asks clarifying questions (interactive) or self-answers them from codebase context (--auto), then writes a ## Grill findings section back to the source artifact."
+allowed-tools: Read Bash Edit Write
+user-invocable: false
+---
+<!-- GENERATED from skills/loop-grill/SKILL.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+# Loop-grill skill
+
+A standalone, on-demand pre-loop grilling skill. Run it against an issue or a local plan file **before** the dev loop starts to surface underspecified acceptance criteria, fuzzy scope boundaries, unresolved primary actors, and undocumented hard-to-reverse decisions.
+
+It is entirely separate from the in-loop docs-grill (`docs/docs-grill-step.md`), which audits code/doc drift while the loop runs. This skill operates on the *spec* before any implementation begins.
+
+## Interface
+
+```
+/loop-grill <issue-number>             # tracker-first, interactive
+/loop-grill <issue-number> --auto      # tracker-first, auto-answer
+/loop-grill <path/to/plan.md>          # local-planning, interactive
+/loop-grill <path/to/plan.md> --auto   # local-planning, auto-answer
+```
+
+## Argument validation (fail-closed)
+
+Before doing anything else:
+
+1. Confirm exactly one positional argument is present (issue number or path). No argument → error, stop.
+2. Confirm the only optional flag is `--auto`. Any other flag → error, stop.
+3. **Tracker-first:** verify the issue exists. Non-existent issue → `Error: issue #<n> not found.`, stop.
+4. **Local-planning:** verify the file exists. Missing file → `Error: plan file not found: <path>`, stop.
+5. Never mutate any artifact when argument validation fails.
+
+## Step 1 — Load the target
+
+- **Tracker-first:** fetch the issue body (title + description + any existing `## Grill findings` section).
+- **Local-planning:** read the plan file from disk.
+
+## Step 1b — Surface external resources
+
+Before detecting gaps, scan the loaded content for external resource references: links, other repo URLs, API endpoints, doc URLs, screenshots, or Playwright navigation descriptors.
+
+- **Interactive mode:** if external resources are present, ask the operator to confirm they are accessible or to provide them before the Q&A starts.
+- **`--auto` mode:** attempt to fetch each resource using bounded wrapper commands (e.g. `gh`, API wrapper scripts under `scripts/`). Do not fetch resources inline with raw `curl` or token-heavy calls. Flag any inaccessible resource as `unresolved` in the findings rather than silently skipping it.
+- When no external resources are present, skip this step silently.
+
+## Step 2 — Detect gaps
+
+Scan the loaded content and identify each gap. The minimum required gap detectors are:
+
+| Gap kind | Detection signal |
+|---|---|
+| Missing acceptance criteria | No `## Acceptance criteria` section, or section is empty / stub |
+| Missing scope boundary | No explicit in-scope / out-of-scope statement or non-goals section |
+| Unresolved primary actor | No named user, system, or role that is the main beneficiary of the feature |
+| Undocumented hard-to-reverse decision | Destructive or irreversible operations described without a rationale or rollback note |
+
+Additional gaps discovered through semantic reading of the spec are also recorded.
+
+For each gap, classify it as either:
+- **Bounded choice** — the answer is one of a small discrete set (e.g. yes/no, A/B/C).
+- **Open-ended** — the answer requires free-form elaboration.
+
+## Step 3 — Fill gaps
+
+### Interactive mode (default)
+
+For each gap, in order:
+
+- **Bounded choice gap:** use `AskUserQuestion` with the question text and the choice options, plus an "Other / free text" option. Block until the user answers.
+- **Open-ended gap:** present the question as a plain text turn. Block until the user answers.
+
+Record each answer with its source: `human`.
+
+> `AskUserQuestion` is a Claude Code–native construct. If you are running outside Claude Code, use `--auto` mode instead.
+
+### Auto mode (`--auto`)
+
+Answer every grilling question yourself without prompting the user. Source answers from (in priority order):
+
+1. **`codebase`** — inspectable source files, tests, scripts, config in the repository.
+2. **`docs`** — markdown files under `docs/`, `skills/docs/`, and adjacent contract docs.
+3. **`context`** — `CONTEXT.md` at the repo root, if present. When absent, skip silently — do not crash, no warning required.
+4. **`inferred`** — reasoning from the issue/plan text alone, with no external citation.
+
+Record the evidence source for every answer. Flag a question as **`unresolved`** when:
+- The only available source is `inferred`, **and**
+- No codebase path, doc section, or issue/plan text can be cited as the basis for the answer.
+
+Do not silently guess an `inferred` answer when no evidence can be cited — flag it `unresolved` instead.
+
+## Step 4 — Write back (replace-section semantics)
+
+Write a `## Grill findings` section back to the source artifact using **replace-section** semantics:
+
+- **Find** the existing `## Grill findings` section: the range from the `## Grill findings` heading through the next `##`-level heading (exclusive) or end of file.
+- **Replace** that range in place with the new section content.
+- If no `## Grill findings` section exists, **append** it.
+- This makes re-runs idempotent — no accumulated noise, no duplicate sections.
+- If parsing the section boundary fails, **abort with an error** rather than silently truncating.
+
+**Tracker-first write-back:** update the GitHub issue body using:
+
+```
+gh issue edit <n> --repo <owner/repo> --body-file <tmp-path>
+```
+
+The `## Grill findings` section lives in the issue body, not as a comment. Do not use `comment-issue.mjs` here — that creates a comment, not a body update.
+
+**GitHub body size guard:** issue bodies are capped at 65,536 characters. Before writing back, check whether the updated body would exceed this limit. If so, warn: `Warning: updated body would exceed GitHub's 65,536-character limit — write-back skipped. Truncate the findings or the issue body manually.` Do not silently truncate.
+
+**Local-planning write-back:** update the plan file in place using the edit tool.
+
+## Output artifact format
+
+The `## Grill findings` section written to the artifact:
+
+```markdown
+## Grill findings
+
+<!-- loop-grill: <timestamp> mode:<interactive|auto> -->
+
+### Resolved gaps
+
+| # | Gap | Question | Answer | Source |
+|---|-----|----------|--------|--------|
+| 1 | Missing AC | <question text> | <answer text> | codebase \| docs \| context \| inferred \| human |
+
+### Unresolved gaps
+
+| # | Gap | Question | Reason unresolved |
+|---|-----|----------|-------------------|
+| 1 | Unresolved primary actor | <question text> | No citable evidence found |
+
+### Verdict
+
+grill-clean
+```
+
+Replace `grill-clean` with `N unresolved items` when unresolved gaps remain.
+
+## Step 5 — Emit verdict
+
+After write-back, emit the verdict line to stdout:
+
+- `grill-clean` when no unresolved gaps remain.
+- `N unresolved items` (e.g. `3 unresolved items`) when gaps remain after all questions are answered.
+
+## CONTEXT.md degradation rule
+
+When `CONTEXT.md` is absent from the repo root, skip the context-source check silently. Do not crash. Do not emit a warning. The grill continues with the remaining sources (`codebase`, `docs`, `inferred`).
+
+## Idempotency guarantee
+
+Running `/loop-grill` twice on the same target must produce a single `## Grill findings` section, not two. The replace-section logic handles the already-present-section case. On the second run, if the gap set is identical to the first run, the section content is replaced with an equivalent section (same questions, same answers, updated timestamp).
+
+## Non-goals
+
+- Auto-triggering from `issue_intake` — this is on-demand only.
+- Replacing or modifying the in-loop docs-grill (`docs/docs-grill-step.md`, `scripts/loop/docs-grill-contract.mjs`) — different concern, different firing surface.
+- Full DDD `CONTEXT.md` management.
+- Scheduling or storing grill runs — stateless and on-demand.
+- Any CI/CD integration.

package/AGENTS.md

@@ -23,3 +23,4 @@
 - Keep workflow procedure out of AGENTS; put shared contracts under `skills/docs/`. Brief, high-signal main-agent dispatch contracts (e.g., sequential dispatch) are the narrow exception — they stay in AGENTS.md because AGENTS.md is the canonical main-agent instruction surface.
 - No PR scope has gate exemptions (#579): see skills/dev-loop/SKILL.md "No gate exemptions" section.
 - **Sequential dispatch contract (#693):** When the user says "sequential", "one at a time", "serially", or "in order" with multiple `dev-loop` targets, the main agent must dispatch `dev-loop` async subagents one at a time — each blocking on prior completion before the next starts. This is deterministic: the keyword must always produce serial execution, never concurrent. The main agent is the sequencer; do not dispatch all targets at once.
+- **Harness-agnostic non-regression (#1086):** dev-loops is harness-agnostic (Pi + Claude Code). Any harness-specific change MUST NOT regress other harnesses — add/keep cross-harness regression coverage. Canonical procedure: [Cross-Harness Regression Contract](skills/docs/cross-harness-regression-contract.md).