openplanr 3.2.0 → 3.4.0

package/lib/host-packages/claude/openplanr/skills/ship/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: ship
-description: Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work.
+description: Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work, or to plan and implement an accepted change. Invoke before editing files for the requested change. Not for planning only, landing, release, or work handed to another coding agent.
 license: MIT
 ---
 
 # OpenPlanr Ship
 
-Produce an implementation-complete local repository in this active coding
-session. Landing and release preparation belong to `planr-land`. Ordinary
+Produce an implementation-complete local repository in this active coding session.
+Landing and release preparation belong to `planr-land`. Ordinary
 Ship stays host-native. Do not delegate implementation to a command-line or model subprocess. If the user explicitly asks another coding agent to implement,
 hand off to `planr-delegate` before implementation. That separate opt-in workflow
 previews the selected context, writable repository, profile, and destination;
@@ -19,7 +19,8 @@ For a selector, locate exactly one task and read it completely. Then follow its
 `storyId` and `specId` to the parent story, acceptance criteria, Gherkin file
 when present, and specification. Also read repository instructions, ADRs,
 planning rules, applicable stack guidance, relevant design/database context,
-implementation code, tests, and interfaces produced by declared dependencies.
+implementation code, tests, and interfaces produced by declared dependencies. Read any
+`.planr/conventions/<area>.md`, indexed from AGENTS.md, for the areas this task touches.
 
 Read [the design lineage contract](references/design-lineage.md). If the selected
 planning root contains `design-lineage.json`, load only the selected task's mapped
@@ -40,17 +41,40 @@ context is sufficient; missing planning files do not create a gate.
 
 ## Implement with native roles
 
-Use the host's read, edit, shell, browser, and test capabilities. When native
-agents are available, dispatch only the applicable frontend, backend, database,
-QA, DevOps, and documentation roles inside this session. Give each role its
-owned outcome, relevant context paths, and explicit file coordination boundary.
-Run independent work in parallel. Host-native role agents remain part of this
-Ship session and do not invoke the separate `planr-delegate` helper. When native
-agents are unavailable, perform the same lenses sequentially in the active agent.
+The main session owns scope, decisions, integration, and final verification.
+Use the host's read, edit, shell, browser, and test capabilities inside this session.
+Keep small coherent changes in this session. Delegate only a self-contained
+outcome that benefits from context isolation, a distinct capability boundary,
+or independent parallel work; agent availability alone is not a reason to dispatch.
+
+Frontend and backend own substantial bounded implementation assignments.
+Persistence implementation, including a task carrying the legacy `db-agent`
+identity, belongs to backend with the relevant database guidance; preserve the
+task's recorded identity. Database is optional read-only introspection when
+repository schemas are insufficient, never migration implementation. Keep small
+documentation updates with their implementation; delegate substantial documentation
+or requested configuration work separately. DevOps never deploys. Entity
+scaffolding remains manual, on explicit request.
+
+Use a separate QA reviewer for authorization, credentials, data-loss risk,
+migrations, public contracts, release behavior, or substantial delegated
+implementation. Small low-risk edits use focused verification in the main session.
+QA retains verification tools, subject to role policy and session permissions.
+
+Select the exact registered identity from the host's roster; Claude plugin
+agents use names such as `planr:planr-backend` and `planr:planr-qa`. Give each worker
+its outcome, the absolute task path with `MODE` and, in spec-driven mode, `SPEC_DIR`,
+authoritative paths, relevant decisions, file ownership, verification requirements,
+and concise return expectations. Parallel workers need disjoint
+writes or an agreed interface. Explain the delegation's purpose briefly in
+commentary. Host-native workers do not invoke the separate `planr-delegate` helper.
+When the host lacks the native role, perform the work sequentially in this session
+and disclose capability limitations; never claim an unavailable specialist ran.
 
 Integrate the complete change, then verify behavior. `reviewRisks` and
 `browserSurfaces` select useful checks; empty arrays are normal and neither field
-is a workflow gate.
+is a workflow gate. Re-run the cheap checks a worker reports as passed, and compare
+its `changed` list with `git diff --name-only` plus untracked files; report any difference.
 
 ## Discover and run verification
 
@@ -65,9 +89,14 @@ Run `openplanr ship checks --json --task <task-path>` (omit `--task` for a direc
 request; add `--tier story` or `--tier push` before pushing) and run its `checks`
 from each `cwd`. The command never executes checks or writes files. When
 `complete` is `false`, report its error diagnostics and treat the check set as
-incomplete: a pass is not CI-equivalent. Without the CLI, the packaged read-only
-[verification discovery helper](scripts/discover-verification.mjs) may list
-candidates. Resolve it relative to this `SKILL.md` and run
+incomplete: a pass is not CI-equivalent. Act on warning diagnostics too; each names
+the files or checks it affects. A diagnostic that a check could not run, such as
+`TYPESCRIPT_UNAVAILABLE`, is not a pass: name that check in `checks` and verify its
+concern yourself where you can (for a new test file, confirm some tsconfig includes
+it). For a `package-contents` check, account for every `expectFiles` entry in the
+tarball's `files`: packed or deliberately left out. Without
+the CLI, the packaged read-only [verification discovery helper](scripts/discover-verification.mjs)
+may list candidates. Resolve it relative to this `SKILL.md` and run
 `node <helper> --project <repository-root> --task <task-path>`; omit `--task` for a
 direct request. It never executes checks or writes files. If both are unavailable,
 inspect those four sources directly. Missing commands are diagnostics, not a
@@ -77,6 +106,8 @@ Run the strongest applicable focused checks while working, then the relevant
 regression checks. Run each check on its own or under `set -o pipefail`, and judge
 it by its own exit code; to shorten output, write it to a log and read the tail.
 Fix failures caused by the change and rerun affected checks.
+For an acceptance check written or changed for this task, follow
+[fail-first](references/fail-first.md) and report what it proved in that check's result.
 Read [the result contract](references/result-contract.md) before reporting.
 
 Report defects you notice outside the task as [findings](references/findings.md),
@@ -95,10 +126,12 @@ behavior, link material changes by purpose, and summarize actual verification.
 Retain complete file inventories and command diagnostics in their existing
 results instead of reproducing them in chat.
 
-- **Outcome:** `completed`, `partial`, or `blocked`, followed by what now works.
+- **Outcome:** `completed`, `partial`, `blocked`, or `awaiting-acceptance` (repository
+  work done; acceptance needs a run only the owner can do), followed by what now works.
 - **Task:** task ID and path, or `direct-request`.
-- **Changed:** material paths grouped by purpose.
-- **Checks:** command, `passed`, `failed`, or `not-run`, plus a concise result.
+- **Changed:** material paths grouped by purpose, files outside Create and Modify apart.
+- **Checks:** command, `passed`, `failed`, or `not-run`, plus a concise result and the
+  acceptance IDs it covers; list acceptance criteria no check covers.
 - **Issues:** blockers with problem, impact, and next action, or `none`; then
   findings outside the task, each with its disposition.
 

package/lib/host-packages/claude/openplanr/skills/ship/references/fail-first.md

@@ -0,0 +1,40 @@
+# Fail-first
+
+A check proves an acceptance criterion only if it fails without the change.
+
+## Applies to
+
+A check mapped to an acceptance ID, or a test written for this task. For
+Investigate, the regression test for the fix.
+
+## Fail-first
+
+- Write or run the check before the implementation. It counts only when the
+  runner reports at least one failed assertion or test.
+- A load error does not count: a missing module, a syntax or compile error, "no
+  tests found", or a collection error. Report it as "fails only on load".
+- If the runner output is unclear, say so instead of guessing.
+- A test written after the code is `not-run` for fail-first. Never revert the
+  implementation to prove it.
+
+A check that already passes before the change: report "passes before the change;
+proves nothing", then narrow or strengthen the check yourself and record that in
+`checks`.
+
+## Seeded fault
+
+Off by default. Offer it only when an acceptance check is new code or fail-first
+failed only on load; the question's default is skip.
+
+1. Record `git status --porcelain` and confirm nothing staged (`git diff --cached --quiet`).
+2. Copy the target file outside the repository.
+3. Make one small edit that breaks behaviour the criterion names.
+4. Rebuild if the tests run built output.
+5. Run the check. It must fail on an assertion.
+6. Restore from the copy, and rebuild if step 4 did; never `git checkout`, which
+   also discards the uncommitted implementation.
+7. Confirm `cmp` against the copy, an identical `--porcelain` output, and nothing staged.
+
+A seed that survives goes in `checks` with a question whose default is "add a
+test for it". Report all of this in the existing `checks` result text: no new
+field, no new stop, no record file.

package/lib/host-packages/claude/openplanr/skills/ship/references/result-contract.md

@@ -2,11 +2,15 @@
 
 Return one concise human rendering backed by these five machine fields:
 
-1. `outcome`: `completed`, `partial`, or `blocked`, plus the achieved result.
+1. `outcome`: `completed`, `partial`, `blocked`, or `awaiting-acceptance` (repository
+   work done; acceptance needs a run only the owner can do), plus the achieved result.
 2. `task`: exact task identity and path, or `direct-request`.
-3. `changed`: material files grouped by purpose.
+3. `changed`: material files grouped by purpose; files outside the task's Create
+   and Modify lists form their own group.
 4. `checks`: each executed or applicable check with `passed`, `failed`, or
-   `not-run` and a concise result.
+   `not-run`, a concise result, and the acceptance IDs it covers. The result says
+   what fail-first proved, for example `failed before the change on an assertion;
+   seed in src/x.ts caught`.
 5. `issues`: `blockers` for this task, each with problem, impact, and next
    action, and `findings` outside the task, shaped as `findings.md` describes;
    use `none` when both are empty.

package/lib/host-packages/claude/openplanr/skills/spec/SKILL.md

@@ -23,6 +23,12 @@ mutually exclusive questions at once and put the recommended option first. If
 the host lacks that interface, ask one concise chat question. Do not present a
 long prose questionnaire.
 
+If no one can answer, as in a headless run, do not ask: choose the
+repository-backed default, or the recommended one when the repository does not
+settle it, and record each such choice as a bullet starting `Assumption:` under
+`## Notes for Decomposition`, naming the decision and the alternative not taken.
+Record a decision you settle inside a functional requirement the same way.
+
 When native agents are available, use the specification role to consolidate the
 contract and dispatch database or designer roles only when their lens affects
 the decision. Otherwise perform those lenses sequentially in the active agent.

package/lib/host-packages/claude/openplanr/skills/spec/references/specification-contract.md

@@ -30,7 +30,9 @@ template:
 
 Keep evidence and rollback as useful planning context, not approval gates or
 receipt requirements. A risk-specialist section may be empty when no specialist
-lens applies.
+lens applies. Under `## Notes for Decomposition`, list each decision made without
+an answer as a bullet starting `Assumption:` that names the decision and the
+alternative not taken.
 
 For a repository intentionally using default mode, write
 `input/specs/spec-{slug}.md` and preserve its active schema. Do not create a