@magnusekdahl/parallix 1.5.289 → 1.5.396

package/build/prompts/draft-core.md

@@ -18,9 +18,19 @@ Forbidden actions:
 
 Mission state authority: `px status {{slug}}` is the authority for recorded Mission facts.
 
-Record the mission contract with typed commands. The slug is inferred from this worktree, and every write takes `--expected-version <n>`. Each write prints the new `version`; pass it to the next write instead of re-reading `px status`.
+Prefer one foreground px mission author invocation to record the complete contract atomically, then read it back once with px status {{slug}}. Run px mission --help for the typed flags. The slug is inferred from this worktree. Each write resolves its own current version automatically; --expected-version is optional when you want to pin an earlier read. Validation or a version conflict rejects the whole batch without partial writes.
 
-The contract, and what the harness requires before this draft can finish:
+For example, a small greeting fix can use plain criterion text:
+
+```sh
+px mission author --goal 'Fix the greeting' --why 'The greeting contains a typo' --scope 'Correct hello.sh greeting text' --out-of-scope 'Other behavior' --criterion 'hello.sh prints Hello, World! and exits successfully' --checkpoint CP-1 --checkpoint-text 'Correct the greeting and verify public execution' --gate './scripts/verify-local.sh all' --predicted Small --classification ai_sdlc
+```
+
+Supply every required part: goal and why, scope, at least one success criterion, an ordered checkpoint plan, exact runnable verification gates, a predicted NEL bucket, and classification. Repeat list flags within the same invocation; the lists replace recorded lists. Out-of-scope entries are optional; record them whenever review should check a deliberate boundary. Checkpoint descriptions are at most 512 characters. Gates contain only runnable commands, without prose, comments or expected outcomes. Expected outcomes belong in criteria.
+
+Use plain text in criteria and evidence values, without literal backticks or embedded double quotes. Quote shell arguments with single quotes as in the example. Execution can cite a repository-relative path such as hello.sh or test/unit/example.test.ts as its evidence reference; formatting characters are unnecessary.
+
+The required parts and their existing single-concept commands are listed below. The batch above records the same parts together; reproduction and dependencies use their own commands.
 
 | Part | Command | Required |
 |---|---|---|
@@ -34,13 +44,13 @@ The contract, and what the harness requires before this draft can finish:
 | Reproduction test | `px repro set --test <path>` | required for a `bug` mission only |
 | Dependencies | `px depends add --on <slug>`, one call each | optional; nothing enforces it |
 
-This table is the whole requirement. The draft does not complete while any required part is missing: the harness refuses it, names what is missing, and sends it back to you. Run any command with `--help` for its exact flags.
+Existing single-concept commands remain available for focused edits. Record a reproduction test with px repro set --test <path> for a bug mission; add optional dependencies with px depends add --on <slug>. Neither changes lifecycle state. Run any command with --help for exact flags.
 
-Run each write as its own foreground command and wait for it to finish. Do not chain the whole contract into one long command, do not move a write to the background, and never end your turn while a `px` command is still running: when your turn ends, anything still running is killed and was not recorded.
+Wait for each foreground write to finish; never end your turn while a `px` command is still running: when your turn ends, anything still running is killed and was not recorded.
 
 A write against a stale version is rejected with an explicit conflict and changes nothing; re-read the version with `px status {{slug}}` and retry.
 
-Before you finish, read the contract back with `px status {{slug}}` and check every required part in the table. Anything it does not report was not recorded.
+Before you finish, read the contract back with `px status {{slug}}` and check every required part above. Anything it does not report was not recorded.
 
 Plan the checkpoints; do not record their evidence. `px checkpoint record` is for execution: evidence is what the work produces, and there is nothing to cite yet.
 
@@ -48,18 +58,20 @@ Drafting requirements:
 - every part you record is concrete and specific to this mission; no placeholders or "TBD"
 - plan checkpoints as coherent, independently verifiable slices of the work; together they must cover every success criterion
 - each success criterion must be specific and checkable: execution records one Goal Check row of evidence per criterion
+- Before locking, check that all criteria and scope constraints can hold together. Challenge absolute guarantees with boundary cases; finite budgets must include all mandatory content, metadata and request overhead. Resolve contradictions during drafting.
 - {{classificationInstructions}}
 - preserve `{{taskPath}}`: update content as needed but do not delete, rename, or move the file
 - do not edit the backlog `assignee` field; the workflow records ownership itself
 - predict the size of the change as a net engineering lines (NEL) bucket — Small (0–80), Medium (81–235) or Large (235+)
+- Plan a brief check where the implementer exercises the changed behavior through the running application’s public interface and records the observed result, using existing tools without adding E2E tests unless explicitly asked for in the intent.
 
 Bug-labeled missions (regression-test-first / "lock the bug"):
 - this section applies only when the backlog task at `{{taskPath}}` carries a `bug` label (in addition to its `ai_sdlc` or `user_value` classification). If there is no `bug` label, ignore this section entirely.
-- make the **first planned checkpoint** (`px checkpoint plan --name CP-1`) the authoring of a failing reproduction test that locks the bug before any fix is written. Describe in that checkpoint: the test file location (under `test/`), the reproduction scenario, and the assertion that fails at the mission's parent commit (red) and will pass once the fix lands (green).
+- make the **first planned checkpoint** (--checkpoint CP-1 in the batch) the authoring of a failing reproduction test that locks the bug before any fix is written. Describe in that checkpoint: the test file location (under `test/`), the reproduction scenario, and the assertion that fails at the mission's parent commit (red) and will pass once the fix lands (green).
 - record the reproduction test's path with `px repro set --test <path>` (for example, `px repro set --test test/task-1354-repro.test.ts`); the table above makes it required for a bug mission. `px status {{slug}}` reports it back for the reviewer to check against the diff.
 - do not author the fix during draft — the reproduction test and its recorded path are the only bug-specific drafting outputs.
 
-Graphify-first: before drafting, check if `graphify-out/graph.json` exists. If it does, run `graphify query "{{slug}} mission scope and dependencies"` to understand the codebase context before filling in the mission contract. Do not refresh Graphify after drafting; freshness is maintained at the autonomous-review boundary on the final verified tree.
+Graphify-first: before drafting, check if `graphify-out/graph.json` exists. If it does, run `graphify query "{{slug}} mission scope and dependencies"` to understand the codebase context before filling in the mission contract. Parallix updates existing Graphify graphs after successful squash integration on the receiving base worktree; review, edits and checkpoints do not trigger updates.
 
 Finishing:
 - verify the draft with `{{verifyCmd}}` before stopping

package/build/prompts/execute-core.md

@@ -12,12 +12,12 @@ Mission context is application-owned. Load it with:
 
 Execution supports evidence and completion writes:
 
-- `px mission mark-complete --slug {{slug}} --criterion <index> --expected-version <n>` — mark a verified success criterion complete using its one-based index and the current status Version.
+- `px mission mark-complete --slug {{slug}} --criterion <index>` — mark a verified success criterion complete using its one-based index. The write resolves its own current version; the status Version is diagnostic.
 - `px checkpoint record --name <CP-N> --criterion <text> --evidence <text> --next <text>` — `--criterion` and `--evidence` repeat and pair up in order.
 
 You do not change the mission here. The goal, scope, out-of-scope, success criteria, checkpoint plan and gates were settled at draft and are what your work is judged against; if you believe one of them is wrong, say so in your response and stop rather than editing it to match what you built.
 
-The slug is inferred from this worktree, so you do not pass it. The write takes `--expected-version <n>`, whose value is the `version` field reported by `px status {{slug}}`. A write against a stale version is rejected with an explicit conflict and changes nothing; re-read the status and retry deliberately. Run the command with `--help` for its exact flags.
+The slug is inferred from this worktree, so you do not pass it. Writes resolve their own current version, so you do not pass `--expected-version`; pass it only to pin a version. A competing write still fails with an explicit conflict and changes nothing. Run the command with `--help` for its exact flags.
 
 Harness preflight already confirmed:
 - branch/worktree shape
@@ -25,29 +25,28 @@ Harness preflight already confirmed:
 
 Execution requirements:
 - execute checkpoint-by-checkpoint per the checkpoint plan reported by `px status {{slug}}`, starting with the first planned checkpoint that has no recorded evidence. That is also where you resume after a relaunch.
-- after each completed checkpoint, record its evidence with `px checkpoint record --name <its planned CP-N>`, one `--criterion`/`--evidence` pair per Goal Check row, and a non-generic `--next`. Use the exact text of the success criterion a row evidences as its `--criterion`; handoff matches the final checkpoint's rows against the recorded success criteria and refuses a criterion with no row. That is the durable write; read it back with `px status {{slug}}`. Do not write a checkpoint document.
+- after each completed checkpoint, record its evidence with `px checkpoint record --name <its planned CP-N>`, one `--criterion`/`--evidence` pair per Goal Check row, and a non-generic `--next`. Use the exact text of the success criterion a row evidences as its `--criterion` so a reviewer can map rows to criteria. Handoff checks every recorded checkpoint, not just the final one: every criterion must be marked complete, and the recorded checkpoints taken together must carry a row naming each completed criterion, each citing a verifiable reference; handoff matches each row to the success criterion its `criterion` text names and refuses when the recorded checkpoints leave any completed criterion without a matching row. A repair checkpoint that carries only its affected criteria is not a shortfall while earlier evidence covers the others. That is the durable write; read it back with `px status {{slug}}`. Do not write a checkpoint document.
 - never create, edit, or commit files under the mission dir or anywhere under `missions/`: it is a retired legacy location, the tree must contain no files there, and handoff fails if it does. Measurements, timings, and populations belong inline in `px checkpoint record --evidence` text, citing runnable commands and test paths.
-- Immediately after recording a checkpoint's evidence, compact your working context: reload only the mission goal, scope, success criteria and checkpoint plan with `px status {{slug}}`, then continue.
+- Immediately after recording a checkpoint's evidence, {{checkpointContextAction}} only the mission goal, scope, success criteria and checkpoint plan with `px status {{slug}}`, then continue.
 - Completing a checkpoint is **non-terminal**: after recording its evidence, immediately continue to the next planned checkpoint without recorded evidence. Do not send a final response or exit merely because one checkpoint is complete; break large checkpoints into safe slices and keep progressing.
 - You may terminate this execution only when exactly one of these conditions applies: (a) every success criterion is marked complete, every planned checkpoint has recorded evidence, the final one covers every success criterion, and every mission-declared gate passes, (b) a mission stop rule applies, or (c) a genuine external dependency blocks progress. Checkpoint size, uncertainty, or needing further investigation are not terminal conditions.
 - Keep Goal Check evidence durable: prefer stable file references and commands that can be rerun against the committed tree. Do not claim that `git diff HEAD` proves a committed change—its expected output is empty after committing. If historical diff evidence is needed, state the exact non-HEAD baseline or describe the observed change without implying that an empty post-commit diff will reproduce it.
-- the final checkpoint MUST record one Goal Check row per success criterion, citing real, durable references such as runnable project commands, test names, decision-record references, or test paths
 - **One row per criterion:** each `--criterion` is paired with the `--evidence` that follows it, in order. Pass the flags as many times as you have criteria; the counts must match or the write is rejected.
-- **Accepted evidence forms** (each `--evidence` value must cite at least one verifiable reference from this list):
-  1. **Runnable project commands or stable paths** — e.g., `` `make test` ``, `` `go test ./...` ``, or `` `tests/integration/` ``
-  2. **Test names** — e.g., `"saving a record preserves its identifier"` (must match a test name found in the project)
-  3. **Decision-record references** — e.g., `ADR 0048` (when the project uses ADRs or an equivalent decision record)
-  4. **Test paths** — e.g., `tests/integration/` (must be an existing test path)
-  5. **File:line references** — accepted when needed, but line numbers eventually rot; prefer the forms above
-- **Not sufficient by themselves:** raw `stat`/`ls` output or generic prose claims. You may include them as supporting context, but the same `--evidence` value must also cite at least one accepted reference from the list above.
+- **Evidence references:** `px checkpoint record` and handoff apply the same check, and recording refuses a row that cites none of these, naming the offending row:
+  1. an existing repository-relative path such as `test/store.test.ts`; a bare basename such as `store.test.ts` does not resolve
+  2. an exact test name in quotes, as written in `test(...)` or `it(...)` in a `.test`, `.spec` or `.cases` module under `test/`
+  3. a backticked command: `npm`, `npx`, `node`, `git` or `px`, a `./` script that exists, or a shell reader such as `grep` or `cat` with an existing file argument
+  4. an ADR reference such as `ADR 0012` whose file exists in `docs/adr/`
+  Raw stat/ls output and prose claims are context only. Prefer a repository-relative path reference and plain evidence text with no literal backticks or embedded double quotes. Example: px checkpoint record --name CP-2 --criterion '<exact success criterion text>' --evidence 'test/unit/example.test.ts passes under npm test -- test/unit/example.test.ts' --next 'CP-3: update the operator guidance'
 - run targeted checks needed to develop and validate the change; handoff owns the authoritative execution of mission-declared Gates, so do not rerun a complete declared gate solely as lifecycle ritual (run one when diagnosing a concrete issue)
-- Immediately after **each successful mission-declared Gate**, compact your working context before starting the next gate, checkpoint work, or handoff work. Reload only the locked mission goal and scope plus committed checkpoint or successful-gate evidence that is present, re-reading them with `px status {{slug}}` rather than from repository files. Do not compact for a failed gate: retain its failure diagnostic while repairing it.
+- Immediately after **each successful mission-declared Gate**, {{gateContextAction}} only the locked mission goal and scope plus committed checkpoint or successful-gate evidence that is present, re-reading them with `px status {{slug}}` rather than from repository files. Retain a failed gate's failure diagnostic while repairing it.
 - preserve `{{taskPath}}`: update mission-relevant content as needed but do not delete, rename, or move the file
-- do not change the Backlog task's status, assignee, labels, or lifecycle metadata, and do not run `px active`, `px review`, `px integrate`, `px assign` or `px unassign`; Parallix performs lifecycle transitions and review decisions itself. `px status {{slug}}` and `px history` are the supported reads in this phase, and `px checkpoint record` and `px mission mark-complete` are the supported writes.
+- do not change the Backlog task's status, assignee, labels, or lifecycle metadata, and do not run `px active`, `px review`, `px integrate`, `px assign` or `px unassign`; Parallix performs lifecycle transitions and review decisions itself. `px status {{slug}}`, `px checkpoint check --json` and `px history` are the supported reads in this phase, and `px checkpoint record` and `px mission mark-complete` are the supported writes.
 - earlier agent runs of this Mission (before a relaunch, a fallback family or a fresh context) are retained: `px history search <pattern>` and `px history show <ref>` return bounded slices with `run:` references and coverage notes. Cite those references instead of pasting transcripts into your context.
-- After verifying a success criterion, record completion with `px mission mark-complete --slug {{slug}} --criterion <index> --expected-version <n>`, using its one-based index and the current Version from `px status {{slug}}`. Reload status after each write. Use `--all` only when every criterion is verified. Recording checkpoint evidence does not mark criteria complete.
+- After verifying a success criterion, record completion with `px mission mark-complete --slug {{slug}} --criterion <index>`, using its one-based index. The write resolves its own current version; the status Version is diagnostic. Reload status after each write. Use `--all` only when every criterion is verified. Recording checkpoint evidence does not mark criteria complete.
+- Before declaring completion, run `px checkpoint check --slug {{slug}} --json`. Inspect `ready`, `version`, `findings`, `primaryStopReason` and `nextCommands`; a successful read is not evidence readiness. A recorded unresolved human-only contract blocker is the primary stop reason even when evidence is incomplete: stop for the operator, without fabricated evidence or repeated evidence-only repair. Do not use `record --force` or treat prose as resolution; only an explicit operator decision can clear the recorded blocker.
 - do not hand off to review until every success criterion is marked complete, or with uncommitted implementation work, or before the final checkpoint's evidence is recorded
 
-Graphify-first: before executing, check if `graphify-out/graph.json` exists. If it does, use `graphify query "<question>"` for codebase questions, `graphify path "<A>" "<B>"` for relationships, and `graphify explain "<concept>"` for focused concepts. Read `graphify-out/GRAPH_REPORT.md` only for broad architecture review. Graph freshness is handled at the autonomous-review boundary, after its final verification and immediately before reviewer launch; do not refresh after ordinary edits. If `graphify-out/wiki/index.md` exists, use it for broad navigation.
+Graphify-first: before executing, check if `graphify-out/graph.json` exists. If it does, use `graphify query "<question>"` for codebase questions, `graphify path "<A>" "<B>"` for relationships, and `graphify explain "<concept>"` for focused concepts. Read `graphify-out/GRAPH_REPORT.md` only for broad architecture review. Parallix updates existing Graphify graphs after successful squash integration on the receiving base worktree; review, edits and checkpoints do not trigger updates. If `graphify-out/wiki/index.md` exists, use it for broad navigation.
 
 {{checkpoint_context}}

package/build/prompts/review-core.md

@@ -20,7 +20,7 @@ Review history is not optional context:
 - Treat a `PUSHBACK_ALL` in the history as a response awaiting your decision, not as an approval and not as a fresh set of findings.
 
 Minimum loop contract:
-- When `{{attempt}}` is 2 or later, before beginning this review round compact the prior-round working context. Reload the locked mission goal and scope; committed checkpoint or gate evidence when present; current round and disposition; unresolved findings and implementer resolutions; and the exact post-rebase revision and review baseline shown by `git diff {{reviewBaseline}}..HEAD`. This compaction is independent of the mission's declared gates.
+- When `{{attempt}}` is 2 or later, before beginning this review round {{reviewContextAction}} the locked mission goal and scope; committed checkpoint or gate evidence when present; current round and disposition; unresolved findings and implementer resolutions; and the exact post-rebase revision and review baseline shown by `git diff {{reviewBaseline}}..HEAD`. This compaction is independent of the mission's declared gates.
 - Load the Mission context with `px status {{slug}}` and read `AGENTS.md` before reviewing.
 - The block below reports which controls the workflow has already executed for this mission and which it has not, derived from machine records rather than from anyone's prose. Do not re-run a listed command whose recorded status is `passed`; cite the recorded result from this block instead. Re-running is permitted only when the block reports no recorded gate result, reports a `failed` status, reports a control as not yet run, or the command you need is not listed here.
 {{completedControls}}
@@ -49,9 +49,10 @@ Check:
 - maintainability issues that materially affect future work
 
 - Decision submission is mandatory: your final chat response does **not** submit a review. Before stopping, run exactly one of:
-  - `px verdict approve --slug {{slug}} --actor {{reviewer}} --expected-version <n> --comment "<review summary>"`
-  - `px verdict request-changes --slug {{slug}} --actor {{reviewer}} --expected-version <n> --finding <finding-id> --summary "<issue>" [--location "<path>"] ... --comment "<review summary>"`
+  - `px verdict approve --slug {{slug}} --actor {{reviewer}} --comment "<review summary>"`
+  - `px verdict request-changes --slug {{slug}} --actor {{reviewer}} --finding <finding-id> --summary "<issue>" [--location "<path>"] ... --comment "<review summary>"`
 - Every request-change finding needs a distinct stable `F<number>` id and non-empty summary. `px verdict` persists the decision and publishes through the established workflow; do not post to Forgejo directly.
+- When a finding concerns specific success criteria, name them in its summary as `Success criterion N` (or `criteria N, M`, 1-based as `px status` lists them). Checkpoint recording and handoff read these references to require fresh fix evidence for exactly those criteria in the repair round.
 - Do not edit repo files; do not switch into implementer behavior.
 - Graphify-first: before reviewing, check if `graphify-out/graph.json` exists. If it does, run `graphify query "review {{slug}} for correctness and completeness"` to get a graph-based view of the mission scope before examining the diff.