joycraft 1.4.1 → 1.5.1

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.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "releaseVersion": "1.4.1",
3
+ "releaseVersion": "1.5.1",
4
4
  "manifestSchemas": [
5
5
  1
6
6
  ],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "joycraft",
3
- "version": "1.4.1",
3
+ "version": "1.5.1",
4
4
  "description": "Install and update Joycraft, a skill bundle and runtime for agent-led software work, in any project",
5
5
  "type": "module",
6
6
  "bin": {
@@ -13,8 +13,8 @@
13
13
  "payload"
14
14
  ],
15
15
  "joycraft": {
16
- "release": "1.4.1",
17
- "summary": "Gates: say \"Turn on Joycraft's gates\" and Claude Code cannot stop while a spec is done without an accepted review; session end runs the same check on every agent, and a fourth review is refused.",
16
+ "release": "1.5.1",
17
+ "summary": "Turning on the gates now checks first, and the agent fixes what it can before the hook goes in. When the gate blocks a stop, the agent restores the spec without asking you. A failed test run exits 1. Rolling back the 1.0 upgrade also removes the gate hook.",
18
18
  "autoSafeEligible": false
19
19
  },
20
20
  "scripts": {
@@ -27,9 +27,9 @@ environment can show is not a criterion; list it under the spec's "Deferred unti
27
27
  deploy" section instead. Include the brief, spec and exact
28
28
  relevant code, test/configuration and fixture paths as verification inputs. Plan
29
29
  paths explicitly and update them when implementation reveals more relevant files.
30
- Inputs are present by default. Declare a deletion only as an explicit
30
+ Declare a deletion only as an explicit
31
31
  non-requirement input with `state: 'absent'`; a rename needs the old absent input
32
- and the new present one. A requirement cannot be absent. Change scope is opt-in:
32
+ and the new present one. Change scope is opt-in:
33
33
  add `verification.changeScope` only when a spec needs a scope check, with an
34
34
  explicit full base SHA recorded before implementation. Give any unrelated changed
35
35
  path a narrow path-and-reason exclusion; do not turn a broad branch or directory
@@ -54,12 +54,13 @@ between the intended behavior and the coupled path. Use
54
54
  check; omit this detail for a simple local edit. It does not replace the brief as
55
55
  the authority for product behavior.
56
56
 
57
- Before queueing, check each spec; a spec that fails this check does not enter
58
- the queue and goes back to the brief as an open decision: every acceptance bullet has a `Check:` and
59
- open-input rules name their check set, costlier error and threshold; no
60
- criterion depends on an unbuilt spec; cited evidence files exist; runtime and
61
- visual criteria carry their environment recipe or are deferred; settled rulings
62
- are quoted with their ID. Check coverage against the original request and
57
+ Before handing the queue on, run
58
+ `node .joycraft/runtime/queue-check.mjs --queue <queue>` and act on each gap it
59
+ names. Then check what it cannot; a failing spec goes back to the brief as an
60
+ open decision: open-input rules name their check set, costlier error and
61
+ threshold; no criterion depends on an unbuilt spec; runtime and visual criteria
62
+ carry their environment recipe or are deferred; settled rulings are quoted with
63
+ their ID. Check coverage against the original request and
63
64
  resolved answers, not just the spec list. Retain visible pending choices and dependencies. Pass the ready queue
64
65
  to `joycraft-implement`, which continues authorized work without per-spec approval.
65
66
  For native execution, hand off raw sources and the selected queue/spec to the
@@ -32,17 +32,18 @@ implementer` with its actual native identity before any tasked edit or mutation.
32
32
  The coordinator runs that start itself only when it is the implementer actor.
33
33
  Use the returned packet only when `ready` is true.
34
34
 
35
- If existing independent reports reveal a possible recurring failure, follow [recurring failure guidance](../../../.joycraft/references/recurring-failures.md) before carrying it forward: inspect the current scoped sources and actual counterpart path or journey, then provide any proposed lesson as exact inputs through the existing dispatch flow. A verified repair may establish its local project fact; a broader method benefit remains pending later reuse.
35
+ If existing independent reports reveal a possible recurring failure, follow [recurring failure guidance](../../../.joycraft/references/recurring-failures.md) before carrying it forward.
36
36
 
37
- Before the first dispatch, claim the queue as its coordinator with your actual
38
- host session ID, and pass that ID as `--coordinator-session` to every startup:
37
+ Before the first dispatch, claim the queue with your actual host session ID and
38
+ pass it as `--coordinator-session` to every startup:
39
39
 
40
40
  ```sh
41
41
  node .joycraft/runtime/coordinator.mjs claim --queue <queue> --session <your-session-id> --host <host>
42
42
  ```
43
43
 
44
- If another session holds the queue, stop and report the holder; take it over
45
- with `--take-over` only when the user says that session has ended.
44
+ If another session holds the queue, stop and report the holder; use
45
+ `--take-over` only when the user says that session has ended. Then run
46
+ `node .joycraft/runtime/queue-check.mjs --queue <queue>`; act on each gap.
46
47
 
47
48
  For a spec marked `execution.parallel: true`, use a separate linked worktree for
48
49
  each concurrent mutator, including its build/cache state. Create it with
@@ -55,7 +56,7 @@ isolation cannot be obtained, replan the affected wave and set the current
55
56
  queue entry's `execution.parallel` to `false` before dispatch, recording why;
56
57
  then run it serially. Otherwise leave it unstarted.
57
58
 
58
- Implement the spec and run meaningful checks and any relevant rendered inspection during implementation. Do not defer ordinary checks to the batch boundary. Run each test command once in single-run mode with `CI=1` and a 300000 ms timeout; follow [running tests](../../../.joycraft/references/testing.md#running-tests) when one times out. Write one focused test per acceptance `Check:`, from the spec rather than the code, and tag it with its queue criterion ID as `[AC:<criterion-id>]` in the test name or a comment; if a criterion or test looks wrong, report a spec gap instead of editing it to pass. When the implementation is finished, update both the queue entry and the spec's top-level frontmatter `status:` to `in-review` together. A passing test suite, commit, or empty ready set does not accept the work.
59
+ Implement the spec and run meaningful checks and any relevant rendered inspection during implementation. Do not defer ordinary checks to the batch boundary. Run each test command with `node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command>`; see [running tests](../../../.joycraft/references/testing.md#running-tests). Write one focused test per acceptance `Check:`, from the spec rather than the code, and tag it with its queue criterion ID as `[AC:<criterion-id>]` in the test name or a comment; if a criterion or test looks wrong, report a spec gap instead of editing it to pass. When the implementation is finished, set it `in-review` with `node .joycraft/runtime/completion.mjs submit --queue <queue> --spec <id>`. A passing test suite, commit, or empty ready set does not accept the work.
59
60
 
60
61
  Honor the queue's commit mode. In `batch`, commit and review the independent ready
61
62
  wave at its boundary before advancing its dependents; do not wait for an entire
@@ -99,11 +100,11 @@ Only the guarded completion path can move an `in-review` spec to `done`. Use its
99
100
  When a current independent review is `FAIL` or `UNVERIFIED`, first fix
100
101
  straightforward failures within the existing authorization and obtain a fresh
101
102
  review. A spec gets at most three reviews: reviewer startup prints
102
- `reviewRound` and refuses a fourth. Settled briefs and checked specs should make
103
- this rare. If startup refuses a review, or a second FAIL on the same criterion
104
- or a "decision needed" finding still occurs, send no
105
- further fix and never amend acceptance yourself: note it under `## Decision
106
- needed` in the spec, leave it `in-review`, and continue independent ready work. An owner can explicitly accept the
103
+ `reviewRound` and refuses a fourth. If startup refuses a review or a second FAIL
104
+ on the same criterion occurs, send no further fix and never amend acceptance
105
+ yourself: note it under `## Decision needed` in the spec, leave it `in-review`,
106
+ and continue independent ready work. Treat a held `decision-needed` finding
107
+ (`$joycraft-verify`) the same, without the note: `status.mjs` lists it. An owner can explicitly accept the
107
108
  current findings and their stated limits through `accept-owner`; that is a
108
109
  bounded exception, not a PASS or verified result. Do not ask merely because a
109
110
  review failed. Ask only when an explicit override is needed to proceed and a
@@ -125,6 +126,8 @@ delivery; never push with a promise to verify later or hide failure in a shell
125
126
  chain. This command cannot replace independent review or authorize a push.
126
127
 
127
128
  After review and completion, continue with the next ready authorized spec.
129
+ When no spec can start, that is, each remaining spec is held or waits on a
130
+ held spec, run `$joycraft-session-end` without waiting for the user.
128
131
  Report blockers and the next action first, then measured progress. Tell the user
129
132
  when a run stops or planned work is omitted, with the reason and retained state;
130
133
  explain any needed external setting and its effect. Give concise stage updates
@@ -27,6 +27,10 @@ Before ending, run `node .joycraft/runtime/status.mjs --fix` (repairs lagging
27
27
  frontmatter of accepted specs, lists features ready to archive) and
28
28
  `node .joycraft/runtime/gate.mjs check`. Do the step each gate message names,
29
29
  such as a completing command. Tell the user each message you could not clear.
30
+ Ask the user each status `questions` entry (findings rule: `$joycraft-verify`).
31
+ Write each answer where it lasts: a decision in the decision log; a requested
32
+ change in a new spec or the held spec. Never archive a feature whose question
33
+ the user asked to wait.
30
34
  Then preview `node .joycraft/runtime/worktrees.mjs prune` and apply it with
31
35
  `--apply`: it removes only clean, integrated trees of done specs and keeps the
32
36
  rest with their reason. Report kept trees and their size from `list`.
@@ -36,8 +40,7 @@ when the session used parallel mutable workers.
36
40
 
37
41
  When an `UNVERIFIED` review identifies only an environment condition, record
38
42
  that condition and arrange a fresh review after it is corrected. Do not create
39
- an unchanged-code fix round. The existing completion process remains the sole
40
- owner of acceptance and status changes.
43
+ an unchanged-code fix round.
41
44
 
42
45
  Before ending, and before any archival, route each reusable fact the session established (a decision with its reason, a trap, a reference, a production fact) to its one home per [knowledge guidance](../../../.joycraft/references/knowledge.md). Rewrite a changed fact in place and put its reason in the decision log; add a context-map row for a new home; keep each touched row's "read when" true. Leave feature intent in the brief. A session with nothing reusable changes no context file.
43
46
 
@@ -48,7 +51,7 @@ project. Put its findings on the session-end page with the rest of the report an
48
51
  apply only the fixes the user approves there. With no findings, say so in one
49
52
  line.
50
53
 
51
- When independent reports suggest a reusable failure lesson, use the compact, conditional process in [recurring failure guidance](../../../.joycraft/references/recurring-failures.md): keep only a source-linked shortlist in active task material, inspect current sources before relying on history, and route any proposed lesson as exact next-worker inputs through the existing dispatch path.
54
+ When independent reports suggest a reusable failure lesson, follow [recurring failure guidance](../../../.joycraft/references/recurring-failures.md).
52
55
 
53
56
  ## Session-end archival
54
57
 
@@ -36,9 +36,9 @@ than from the code, sized like neighboring tests. Do not commit tests of one-off
36
36
  run state. If a criterion or test looks wrong, or conflicts with a later owner
37
37
  decision, report a spec gap; never edit it to pass.
38
38
 
39
- Run each test command once in single-run mode with `CI=1` and a 300000 ms
40
- timeout; follow [running tests](../../../.joycraft/references/testing.md#running-tests)
41
- when one times out.
39
+ Run each test command with
40
+ `node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command>`;
41
+ see [running tests](../../../.joycraft/references/testing.md#running-tests).
42
42
 
43
43
  Retain the executed command, actual exit status and unfiltered output. Describe
44
44
  what happened separately from what was expected. Bind observations and supporting
@@ -50,25 +50,27 @@ Review scope as well as behavior: determine whether the listed inputs and criter
50
50
 
51
51
  Create a schema-v1 verification report tied to that subject, using the shared fields in [.joycraft/contracts/types.d.ts](../../../.joycraft/contracts/types.d.ts). For every declared criterion, provide PASS observations for its required evidence kinds. Keep unfiltered command output and its real exit status in hashed, project-relative receipts. A source scan supports only structural observations. Visual observations require a reviewer-inspected render plus route, state, viewport, interactions, and outcomes. Take evidence with the package's recorded tool, start command and evidence command from the packet's `reviewLoop` (`section`: the `Review loop` section of `AGENTS.md`; `local`: this machine's host tools), within that tool's `canShow`. A claim beyond `canShow`, or in a package the user skipped, is an agreed limit, not `UNVERIFIED`: check what the agreed tool can show, say in plain words how you checked, and leave what is left to the parent agent. A picture-only tool gives `interactions: []`. `UNVERIFIED` means a check that should have run and did not: the tool broke, the app did not start, or a render was saved but not inspected. On a tool break, first repair with what the user agreed to: restart the dev server, free the port, relaunch the browser or simulator, retry once. A repair never installs, upgrades or reconfigures anything. If it still fails, record `UNVERIFIED` with `cause: 'tool-break'` and the reason. Mark a failing result or an unresolved concern as `FAIL` or `UNVERIFIED` truthfully.
52
52
 
53
- Run each test command once in single-run mode with `CI=1` and a 300000 ms
54
- timeout; follow [running tests](../../../.joycraft/references/testing.md#running-tests)
55
- when one times out. Record an unresolved hang as `UNVERIFIED` with its receipt.
53
+ Run each test command with
54
+ `node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command>`;
55
+ see [running tests](../../../.joycraft/references/testing.md#running-tests). Record an unresolved hang as `UNVERIFIED` with its receipt.
56
56
 
57
57
  Run the dispatch helper's `check-report` before completion. It reuses the same
58
58
  subject, receipt, and evidence validators without changing a queue status. If
59
59
  it rejects a packaging or report problem, return the correction to this same
60
60
  reviewer; do not invent observations or replace the independent identity.
61
61
 
62
- Items under a spec's "Deferred until deploy" section are not criteria. Do not
63
- fail or hold the spec for them; list them in the report as open for the owner.
64
-
65
- Report every finding with a severity and the criterion it touches. A finding
66
- blocks only when it shows a stated criterion failing, or a reproducible
67
- correctness defect or regression in the changed code, with file:line or a
68
- receipt. A case the spec does not decide is "decision needed" for the
69
- coordinator, not a FAIL. A probe outside the spec's named check set is a
70
- non-blocking follow-up unless it regresses against the base. Name the class of a
71
- defect once; do not repeat a finding from an earlier round as new.
62
+ Items under a spec's "Deferred until deploy" section are not criteria; list
63
+ each as a `follow-up` finding for the owner.
64
+
65
+ Findings rule: give each `findings` entry its `class`, `origin`, and `criterion`
66
+ or `at` (file:line or receipt). `blocking` is only a failing stated criterion or
67
+ a reproducible defect or regression in the changed code. A case the spec does
68
+ not decide is a `follow-up`: take the reading closest to the brief's intent,
69
+ recorded as `assumption`. `decision-needed` is only for two readings that give
70
+ opposite verdicts on a stated criterion, or a guess that cannot be undone; it
71
+ holds this spec and its dependents, never the queue. A probe outside the named
72
+ checks is a `follow-up` unless it regresses. Never repeat an earlier round's
73
+ finding as new.
72
74
 
73
75
  Set a PASS verdict only when scope is reviewed, all required evidence is sufficient, and no blocking finding or unresolved UNVERIFIED evidence remains. Then run guarded completion:
74
76
 
@@ -24,14 +24,14 @@ message.
24
24
 
25
25
  Write one focused test per acceptance `Check:`, taken from the spec rather than
26
26
  from your code, sized like neighboring tests. Tag each with its queue criterion
27
- ID as `[AC:<criterion-id>]` in the test name or a comment. Run each test command once in
28
- single-run mode with `CI=1` and a 300000 ms timeout; on a timeout follow
27
+ ID as `[AC:<criterion-id>]` in the test name or a comment. Run each test command with
28
+ `node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command>`; see
29
29
  `.joycraft/references/testing.md#running-tests`. Never wait in a
30
30
  foreground loop, never weaken an existing test, and never change the spec's acceptance:
31
31
  if a criterion or test looks wrong, report it as a spec gap.
32
32
 
33
33
  For a user-facing change, render and inspect it as `joycraft-testing` describes.
34
- Before you finish, run the project's own test, typecheck and lint commands named
35
- in `AGENTS.md`, commit by file name, and report each command with its exit
36
- status and the commit it ran on. Keep the final message short: what changed,
34
+ Before you finish, run the project's test, typecheck and lint commands named
35
+ in `AGENTS.md`, then `node .joycraft/runtime/completion.mjs submit`, commit by
36
+ file name, and report each command, its exit status and the commit. Keep the final message short: what changed,
37
37
  checks and results, open gaps.
@@ -23,18 +23,15 @@ message.
23
23
 
24
24
  Judge the current code against every acceptance bullet and its `Check:`, and
25
25
  against the owner intent in the brief. Reuse a suite receipt bound to the same
26
- revision instead of rerunning the full suite; run the spec's own tests once in
27
- single-run mode with `CI=1` and a 300000 ms timeout. Never give a verdict while
26
+ revision instead of rerunning the full suite; run the spec's own tests once with
27
+ `node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command>`. Never give a verdict while
28
28
  a command you started is still running.
29
29
 
30
30
  Startup output includes `trace`: each criterion with its `[AC:<id>]` tests. Report
31
31
  each untraced criterion as a finding. A missing tag alone is not a FAIL; judge the
32
32
  criterion by what you observe.
33
33
 
34
- Report every finding with a severity and the criterion it touches. Only a failing
35
- stated criterion, or a reproducible defect or regression in the changed code with
36
- file:line or a receipt, blocks. A case the spec does not decide is "decision
37
- needed", not FAIL. Do not repeat an earlier round's finding as new.
34
+ Record findings by the findings rule in the verify skill.
38
35
 
39
36
  Take evidence with each package's recorded tool from the packet's `reviewLoop`,
40
37
  within its `canShow`, and say in plain words how you checked. A limit the user
@@ -65,6 +65,8 @@ export interface QueueSpec {
65
65
  /** Captured before implementation; never infer it from a moving upstream branch. */
66
66
  changeScope?: { baseRevision: string; exclusions?: Array<{ path: string; reason: string }> };
67
67
  };
68
+ /** Written by `completion.mjs submit` with the move to in-review; subject bindings leave it out, like status. */
69
+ submitted?: { at: string };
68
70
  acceptedReport?: { path: string; sha256: string };
69
71
  /** Explicit owner exception, mutually exclusive with acceptedReport; not a PASS. */
70
72
  ownerAcceptance?: Receipt;
@@ -144,8 +146,24 @@ export interface VerificationReport {
144
146
  verdict: Result;
145
147
  flows: FlowEvidence[];
146
148
  unresolved: string[];
149
+ /** Optional; a report without it reads as before. */
150
+ findings?: ReviewFinding[];
147
151
  createdAt: string;
148
152
  }
153
+ /** A follow-up never blocks; a blocking or decision-needed finding refuses completion (exit 2). */
154
+ export interface ReviewFinding {
155
+ /** Unique in the report. */
156
+ id: string;
157
+ class: 'blocking' | 'decision-needed' | 'follow-up';
158
+ origin: 'new' | 'pre-existing' | 'unknown';
159
+ /** A criterion id of the spec. A blocking or decision-needed finding needs `criterion` or `at`. */
160
+ criterion?: string;
161
+ /** file:line or a receipt path. */
162
+ at?: string;
163
+ summary: string;
164
+ /** The reading the reviewer took for a case the spec does not decide. */
165
+ assumption?: string;
166
+ }
149
167
  /** Scoped human instruction recorded by the host; bindings do not authenticate its origin. */
150
168
  export interface OwnerAcceptance {
151
169
  schemaVersion: 1;
@@ -1,12 +1,13 @@
1
1
  # Guarded completion
2
2
 
3
- Use this reference when snapshotting a verification subject, submitting an independent review report, or responding to a completion failure.
3
+ Use this reference to submit a spec, snapshot a subject, finalize a review or recover a write.
4
4
 
5
5
  ## Stable local interface
6
6
 
7
7
  Run these commands from the consumer project root. Paths are project-relative.
8
8
 
9
9
  ```sh
10
+ node .joycraft/runtime/completion.mjs submit --queue <queue-path> --spec <id>
10
11
  node .joycraft/runtime/completion.mjs scope --queue <queue-path> --spec <id>
11
12
  node .joycraft/runtime/completion.mjs snapshot --queue <queue-path> --spec <id> --out <subject.json>
12
13
  node .joycraft/runtime/completion.mjs finalize-review --queue <queue-path> --spec <id> --report <report.json>
@@ -15,7 +16,9 @@ node .joycraft/runtime/completion.mjs accept-waiver --queue <queue-path> --spec
15
16
  node .joycraft/runtime/completion.mjs recover --queue <queue-path>
16
17
  ```
17
18
 
18
- `scope` checks a queue's declared change scope without writing a subject. `snapshot` does the same check first, then exclusively creates a new `--out` subject file without changing a status. It binds the implementation revision, queue/spec identity, criteria, and SHA-256 values for exact relevant inputs. The shared record shapes are defined in [.joycraft/contracts/types.d.ts](../contracts/types.d.ts). New subjects carry `binding.version: 1`: their queue projection contains the reviewed spec and its transitive dependencies, with completion metadata (`status`, `acceptedReport`, `ownerAcceptance`, and `waiver`) removed from those records. An unrelated queue record can change without staling that subject; a selected spec's other metadata and dependency edges remain bound. A spec binding preserves raw bytes except for its top-level `status:` value.
19
+ `submit` moves a `todo` spec to `in-review` in the queue and frontmatter with one journaled write, recording `submitted: { at }`. It warns about each criterion with no `[AC:<id>]` test, leaves an `in-review` spec unchanged, and exits 2 on a conflict, a `done` spec or an unfinished dependency.
20
+
21
+ `scope` checks a queue's declared change scope without writing a subject. `snapshot` does the same check first, then exclusively creates a new `--out` subject file without changing a status. It binds the implementation revision, queue/spec identity, criteria, and SHA-256 values for exact relevant inputs. The shared record shapes are defined in [.joycraft/contracts/types.d.ts](../contracts/types.d.ts). New subjects carry `binding.version: 1`: their queue projection contains the reviewed spec and its transitive dependencies, with completion metadata (`status`, `submitted`, `acceptedReport`, `ownerAcceptance`, `waiver`) removed from those records. An unrelated queue record can change without staling that subject; a selected spec's other metadata and dependency edges remain bound. A spec binding preserves raw bytes except for its top-level `status:` value.
19
22
 
20
23
  An optional `verification.changeScope` records an explicit full Git commit SHA in `baseRevision`; a branch name, `origin/main`, or inferred base is rejected. Changed verification inputs are captured from NUL-delimited Git status records, including staged, unstaged, rename, and deletion topology. Any changed path outside the verification inputs must be named exactly in `exclusions` with its reason. Store temporary packets and subjects in the project's ignored local-artifact home when it has one; otherwise add each exact untracked snapshot packet output to `exclusions`. `complete` filters only its exact report, receipt, owner-decision, and pending-journal paths while rechecking scope. A deliberate deletion needs a non-requirement verification input with `state: "absent"`; requirement inputs cannot be absent. A rename needs the new present input and the old non-requirement input declared absent.
21
24
 
@@ -27,13 +30,15 @@ Use the original `implementationRevision` as provenance on a re-check while reco
27
30
 
28
31
  ## Independent report and guarded acceptance
29
32
 
30
- The report must use the shared schema and bind its subject identity. It records the actual implementer/reviewer native identities, `independent: true` only when a separate reviewer context actually reviewed the work, scope review, flow evidence, receipts, limits, unresolved items, and a PASS/FAIL/UNVERIFIED verdict.
33
+ The report must use the shared schema and bind its subject identity. It records the actual implementer/reviewer native identities, `independent: true` only when a separate reviewer context actually reviewed the work, scope review, flow evidence, receipts, limits, unresolved items, optional `findings`, and a PASS/FAIL/UNVERIFIED verdict.
31
34
 
32
35
  A native child can share its parent session. Supply `implementerActor` and `reviewer.actor` together, each with the observed `host`, `sessionId`, and the actual `agentId` when the host issued a child invocation ID. Preserve the matching legacy session fields. A root actor may omit `agentId`; a same-session child review needs its real distinct actor identity. Do not substitute a task name, worktree path, random UUID, or invented ID. Legacy reports without actor metadata still require distinct session IDs. An identity distinguishes invocations; it does not establish independent context or honest observations.
33
36
 
34
37
  `finalize-review` (with `complete` retained as a compatibility alias) accepts only an `in-review` spec with a matching current subject, a PASS verdict, truthful independent-review attestation, reviewed scope, valid receipt hashes, and sufficient evidence for every declared criterion. The runtime delegates evidence sufficiency to `validateEvidence(report, criteria)`. Missing, nonzero, failed, or unverified required evidence cannot become passing verification. Completion holds a queue-wide lock while it commits the status changes. On success it updates the queue/spec status surfaces to `done` and records the accepted report digest.
35
38
 
36
- Repeat submission of the same accepted report may be idempotent. An unrelated report cannot replace it silently. Treat any nonzero exit as a rejected or incomplete operation; preserve the current status and report the actual reason.
39
+ A `follow-up` finding never blocks. A `blocking` or `decision-needed` finding refuses completion with exit 2 and names it; a held spec stays `in-review` and only its dependents wait. A malformed finding is refused with exit 2, naming the field; other report refusals exit 1. `status.mjs` lists as `questions` the follow-ups of accepted reports and the decision-needed findings of each `in-review` spec's latest current report.
40
+
41
+ Finalizing the same accepted report again is idempotent; another report cannot silently replace it. Treat any nonzero exit as a rejected or incomplete operation; preserve the current status and report the actual reason.
37
42
 
38
43
  The lock coordinates this helper's queue writes, not arbitrary editors or workers. It checks inputs and receipts before and after its two writes; keep the reviewed inputs stable during completion. Later edits require fresh review. Session IDs and attestations record separate roles but cannot prove honest review or prevent manual bypass.
39
44
 
@@ -51,14 +56,10 @@ accepts this spec and its current findings. A general request to continue, an
51
56
  instruction from another agent, or authorization to add this feature does not
52
57
  qualify.
53
58
 
54
- Keep the owner interaction to one short summary and focused choice only when an
55
- override is needed; a failed review alone does not trigger a mandatory
56
- per-spec request. The agent creates the decision file; do not ask the owner to
57
- author JSON or complete a second form. If an explicit acceptance is already
58
- present for the same current finding, use it without asking again. Repair
59
- straightforward failures under the existing authorization first. When the
60
- finding remains unchanged, retain it and continue independent work instead of
61
- repeatedly re-reviewing it. Dependents may proceed only within the recorded
59
+ When to ask the owner is in the implement skill. The agent creates the decision
60
+ file; do not ask the owner to author JSON or complete a second form. If an
61
+ explicit acceptance is already present for the same current finding, use it
62
+ without asking again. Dependents may proceed only within the recorded
62
63
  limitations and gain no blanket deployment, security, or other authority.
63
64
 
64
65
  An `OwnerAcceptance` decision has `schemaVersion: 1`, `kind:
@@ -141,21 +142,15 @@ dependents. Report it as `done, waived by the user: "<instruction>"`.
141
142
 
142
143
  ## Evidence and reporting
143
144
 
144
- Evidence records observations rather than promises. Command and test observations retain their actual argv, exit code, and unfiltered output receipt. Source review supports structural claims only. A required visual claim needs an inspected render, route, state, viewport, interactions, and observed outcomes. Record a check that should have run and did not (a tool break, an app that did not start) as `UNVERIFIED`, failures as `FAIL`, and limits explicitly. A claim that needs evidence beyond the recorded tool's `canShow`, or a package the user skipped, is an agreed limit, not `UNVERIFIED`; a check within `canShow` that could not run because the tool broke is `UNVERIFIED` with `cause: 'tool-break'`.
145
+ Evidence records observations rather than promises: a command's actual argv, exit code and unfiltered output receipt; structural claims only from source review; an inspected render with route, state, viewport, interactions and outcomes for a visual claim. A check that should have run and did not is `UNVERIFIED` (with `cause: 'tool-break'` when the tool broke), a failure is `FAIL`, and a claim beyond the recorded tool's `canShow`, or in a package the user skipped, is an agreed limit.
145
146
 
146
147
  Report the command result, reviewer identity, receipt paths, actual observations, and limitations. A green suite or an implementation commit alone is not accepted completion.
147
148
 
148
149
  ## Interrupted writes and recovery
149
150
 
150
- The helper uses `.joycraft-completion.pending.json` in the queue directory as a bounded local journal for the queue status, spec frontmatter status, and accepted-report receipt. If it detects an interrupted or conflicting write, it stops and prints recovery information. A normal caught failure rolls back when safe but retains the journal for inspection. Do not hand-edit the files to force completion.
151
-
152
- Inspect the journal and affected project-relative files first. Then run:
153
-
154
- ```sh
155
- node .joycraft/runtime/completion.mjs recover --queue <queue-path>
156
- ```
151
+ Each status write is journaled in `.joycraft-completion.pending.json` beside the queue. A caught failure rolls back when safe and keeps the journal unless nothing was written; an interrupted one leaves it. Do not hand-edit the files to force completion.
157
152
 
158
- Recovery preflights both captured files before changing either: each current file must match the journal's before or after hash. It restores only the recorded before bytes, leaves conflicts untouched, and removes the journal only after a successful restore. Replaying recovery is safe until that journal is removed. Preserve the journal and rejected report for diagnosis. Retry `complete` or `accept-owner` only while its original review and any owner instruction remain current; otherwise obtain fresh evidence and authorization appropriate to the changed scope. If recovery reports a conflict or invalid journal, stop and report the local recovery blocker.
153
+ Inspect the journal and affected files, then run `recover`. It restores the before bytes only when each file matches the journal's before or after hash, and removes the journal only after that, so replaying it is safe. Preserve the journal and rejected report for diagnosis. Retry `complete` or `accept-owner` only while its original review and any owner instruction remain current; otherwise obtain fresh evidence and authorization appropriate to the changed scope. If recovery reports a conflict or invalid journal, stop and report it.
159
154
 
160
155
  Host names compare without letter-case differences; session and agent IDs stay
161
156
  opaque and case-exact. IDs must be nonempty, bounded, trim-stable and free of
@@ -8,9 +8,9 @@ check makes the rule a command, so it does not depend on the agent.
8
8
  `node .joycraft/runtime/gate.mjs check` exits 2 and names each problem on
9
9
  stderr. Each message names its next step:
10
10
 
11
- - a `done` spec with no accepted report, owner acceptance or waiver: set it
12
- back to `in-review`, get an independent review, then run the completing
13
- command that the message names;
11
+ - a `done` spec with no accepted report, owner acceptance or waiver: at once,
12
+ without asking the user, set it back to `in-review`, get an independent
13
+ review, then run the completing command that the message names;
14
14
  - a spec whose queue status and frontmatter status are different: pending
15
15
  journal: run the named `recover` command, stop on a conflict; accepted: run
16
16
  `node .joycraft/runtime/status.mjs --fix`; unaccepted `done`: the step above
@@ -19,36 +19,36 @@ stderr. Each message names its next step:
19
19
 
20
20
  A spec held at `in-review` is never a problem. Queues older than
21
21
  `schemaVersion: 1` are skipped. With no problem, it exits 0 and prints nothing.
22
- Any agent can run the check, and the session-end skill runs it. Without a hook,
23
- that step depends on the agent.
22
+ Any agent can run the check, and the session-end skill runs it.
24
23
 
25
24
  ## The Stop hook
26
25
 
27
26
  The hook is for Claude Code only for now. When it is on, Claude Code runs the
28
- gate check each time it is about to stop. On exit 2, Claude Code gives the
29
- message to the agent, and the agent must do the step that the message names.
30
- The hook is not a sandbox: a shell command can still write the queue file. The
31
- check finds that result at the next stop.
27
+ gate check each time it is about to stop. On exit 2, the agent gets the
28
+ message and must do the step it names.
29
+ The hook is not a sandbox: a shell command can still write the queue file; the
30
+ next stop finds it.
32
31
 
33
32
  ## Turn the gates on
34
33
 
35
34
  The user says "Turn on Joycraft's gates", or says yes to the offer in setup.
36
35
 
37
36
  1. Run `node .joycraft/runtime/gate.mjs hook --plan`. It writes nothing.
38
- - `change: "none"` and a `message`: tell the user the message. On a host
39
- other than Claude Code, the message says that the hook is not available
40
- and how to run the check by hand.
41
- - `change: "add"`: continue.
37
+ - `change: "none"`: tell the user the `message`.
38
+ - `problems`: `--on` refuses until the check is clean. Clear them
39
+ yourself: set an unaccepted `done` spec back to `in-review`; run the
40
+ command a drift message names. Tell the user what you changed, then plan
41
+ again. Stop and ask only about a file that does not parse.
42
+ - else: continue.
42
43
  2. Show the change to `.claude/settings.json` (`before` and `after`) on a page,
43
44
  as [showing a page](artifacts.md#showing-a-page) says. In two lines, say
44
45
  what the Stop hook does and how to turn it off.
45
46
  3. On the user's yes, run `node .joycraft/runtime/gate.mjs hook --on`. Do not
46
47
  edit `.claude/settings.json` by hand.
47
48
 
48
- `.claude/settings.json` is the user's file. `--on` adds one Stop hook whose
49
- command runs `gate.mjs check`, and it changes no other byte. A second `--on`
50
- changes nothing. If the file is not valid JSON, the command stops and writes
51
- nothing; tell the user.
49
+ `.claude/settings.json` is the user's file. `--on` adds one Stop hook that
50
+ runs `gate.mjs check` and changes no other byte; a second `--on` changes
51
+ nothing. If the file is not valid JSON, it writes nothing; tell the user.
52
52
 
53
53
  ## Turn the gates off
54
54
 
@@ -21,30 +21,31 @@ end-to-end requirement follows from these examples.
21
21
 
22
22
  ### Running tests
23
23
 
24
- Run focused checks once, in the runner's non-interactive single-run mode (for
25
- example `vitest run`, `jest --watchAll=false`, or the project script with that
26
- flag passed through) with `CI=1` set. Never start watch mode. Give each test
27
- command a 300000 ms tool timeout or the project's available supervisor. A
28
- timeout while other test runs share the machine is not yet a hang: rerun once,
29
- alone, with fewer workers. If it times out again, stop leftover test processes
30
- and report the condition with the command; do not keep rerunning. Never wait
31
- in a foreground loop (`until …; do sleep`, `kill -0`, polling a log): start a
32
- long command in the background, keep working, and act on its completion
33
- notice. If a shared lock or verify slot stays busy for more than 5 minutes,
34
- stop and report it instead of waiting. Never give a verdict while your own
35
- command is still running. A
36
- reviewer may reuse a suite receipt bound to the same revision instead of
37
- rerunning it. A bug fix needs a meaningful failing regression only when one
38
- can distinguish the repaired fault. Ordinary edits do not require ritual red/green.
24
+ Run each test command once, in single-run mode with `CI=1` and a 300000 ms
25
+ timeout, through
26
+ `node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command...>`
27
+ (`--timeout-ms <n>` changes the limit). It uses no shell and saves raw stdout
28
+ and stderr to a new git-ignored or feature-folder receipt. Never start watch
29
+ mode. Copy the printed `command` and `receipts` into the observation. It exits
30
+ 1 when the command fails, is killed or times out, and still writes the
31
+ receipt; exit 2 means it refused to run. At the limit it ends the process group:
32
+ `exitCode: null`, `timedOut: true`. Set the host tool timeout to at least this
33
+ limit. A shorter default (for example 120000 ms) ends the wrapper before the
34
+ child. A timeout during parallel runs is not yet a hang: rerun once, alone,
35
+ with fewer workers. If it times out again, report it with the receipt; do
36
+ not keep rerunning. Never wait in a foreground loop
37
+ (`until …; do sleep`, `kill -0`, polling a log): start a long command in the
38
+ background, keep working, and act on its completion notice. If a shared lock
39
+ or verify slot stays busy over 5 minutes, stop and report it. Never
40
+ give a verdict while your own command is still running. A reviewer may reuse
41
+ a suite receipt bound to the same revision. A bug fix needs a meaningful
42
+ failing regression only when one can distinguish the repaired fault.
39
43
 
40
44
  ## Commands and receipt records
41
45
 
42
- For `test` and `command` observations, `command.argv` records the executed command
43
- and `command.exitCode` records its actual outcome. `null` means unavailable.
44
- Keep raw stdout/stderr, including failure output, in a receipt; do not substitute
45
- grepped success text or a pipeline's final status for the command outcome. A
46
- nonzero or missing status cannot support PASS. Do not claim a process finished
47
- while it is still running.
46
+ In `test` and `command` observations, `command.exitCode` is the actual outcome;
47
+ `null` means unavailable. Never substitute grepped success text or a
48
+ pipeline's final status for it. A nonzero or missing status cannot support PASS.
48
49
 
49
50
  Each observation has at least one supporting receipt with a project-relative path
50
51
  and SHA-256. A receipt may be raw command output, inspection notes, an image, or a
@@ -73,8 +74,7 @@ The validator does not inspect receipt contents, execute commands, determine
73
74
  whether inputs are representative, or discover omitted dependencies/requirements.
74
75
  The independent reviewer checks those judgments against the actual brief/spec.
75
76
  Completion separately checks current identity, receipt hashes, review independence,
76
- scope review and verdict before changing status. Tests of this validator protect
77
- its mechanical boundary; they are not an independent judge of a product outcome.
77
+ scope review and verdict before changing status.
78
78
 
79
79
  ## Visual observations and the repair loop
80
80