joycraft 1.5.0 → 1.5.2
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.
- package/README.md +35 -10
- package/dist/cli.js +24 -1
- package/dist/cli.js.map +1 -1
- package/dist/joycraft-release.json +1 -1
- package/package.json +3 -3
- package/payload/.agents/skills/joycraft-implement/SKILL.md +3 -1
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +4 -1
- package/payload/.joycraft/contracts/types.d.ts +16 -2
- package/payload/.joycraft/references/completion.md +27 -21
- package/payload/.joycraft/references/gates.md +22 -22
- package/payload/.joycraft/references/testing.md +6 -6
- package/payload/.joycraft/runtime/archive.mjs +10 -1
- package/payload/.joycraft/runtime/completion.mjs +80 -9
- package/payload/.joycraft/runtime/evidence.mjs +3 -1
- package/payload/.joycraft/runtime/gate.mjs +59 -13
- package/payload/.joycraft/runtime/identity.mjs +4 -3
- package/payload/.joycraft/runtime/status.mjs +17 -3
- package/payload/PIN +14 -14
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "joycraft",
|
|
3
|
-
"version": "1.5.
|
|
3
|
+
"version": "1.5.2",
|
|
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.5.
|
|
17
|
-
"summary": "
|
|
16
|
+
"release": "1.5.2",
|
|
17
|
+
"summary": "When you turn on the gates, the agent names specs marked done with no review on record and asks one question: accept them as they are, or send them back for review. Your words are recorded verbatim in a file committed beside the queue.",
|
|
18
18
|
"autoSafeEligible": false
|
|
19
19
|
},
|
|
20
20
|
"scripts": {
|
|
@@ -32,7 +32,7 @@ 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
|
|
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
37
|
Before the first dispatch, claim the queue with your actual host session ID and
|
|
38
38
|
pass it as `--coordinator-session` to every startup:
|
|
@@ -126,6 +126,8 @@ delivery; never push with a promise to verify later or hide failure in a shell
|
|
|
126
126
|
chain. This command cannot replace independent review or authorize a push.
|
|
127
127
|
|
|
128
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.
|
|
129
131
|
Report blockers and the next action first, then measured progress. Tell the user
|
|
130
132
|
when a run stops or planned work is omitted, with the reason and retained state;
|
|
131
133
|
explain any needed external setting and its effect. Give concise stage updates
|
|
@@ -28,6 +28,9 @@ 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
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.
|
|
31
34
|
Then preview `node .joycraft/runtime/worktrees.mjs prune` and apply it with
|
|
32
35
|
`--apply`: it removes only clean, integrated trees of done specs and keeps the
|
|
33
36
|
rest with their reason. Report kept trees and their size from `list`.
|
|
@@ -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,
|
|
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
|
|
|
@@ -68,8 +68,8 @@ export interface QueueSpec {
|
|
|
68
68
|
/** Written by `completion.mjs submit` with the move to in-review; subject bindings leave it out, like status. */
|
|
69
69
|
submitted?: { at: string };
|
|
70
70
|
acceptedReport?: { path: string; sha256: string };
|
|
71
|
-
/** Explicit owner exception, mutually exclusive with acceptedReport; not a PASS. */
|
|
72
|
-
ownerAcceptance?: Receipt;
|
|
71
|
+
/** Explicit owner exception, mutually exclusive with acceptedReport; not a PASS. `legacy: true` names a LegacyAcceptance file (no review). */
|
|
72
|
+
ownerAcceptance?: Receipt & { legacy?: true };
|
|
73
73
|
/** The feature's FeatureWaiver file, plus the UNVERIFIED report a tool-break waiver completed on; mutually exclusive with acceptedReport and ownerAcceptance. */
|
|
74
74
|
waiver?: Receipt & { review?: Receipt };
|
|
75
75
|
}
|
|
@@ -164,6 +164,20 @@ export interface ReviewFinding {
|
|
|
164
164
|
/** The reading the reviewer took for a case the spec does not decide. */
|
|
165
165
|
assumption?: string;
|
|
166
166
|
}
|
|
167
|
+
/** The owner's own words accepting specs marked done with no review on record, as they are; written by `accept-owner --legacy`. The runtime checks the record, not who spoke. */
|
|
168
|
+
export interface LegacyAcceptance {
|
|
169
|
+
schemaVersion: 1;
|
|
170
|
+
kind: 'legacy';
|
|
171
|
+
/** Project-relative; must equal --queue. */
|
|
172
|
+
queuePath: string;
|
|
173
|
+
/** The owner's verbatim words, nonempty. */
|
|
174
|
+
statement: string;
|
|
175
|
+
statedAt: string;
|
|
176
|
+
/** Equal to the --spec ids; each was done with no acceptance. */
|
|
177
|
+
specs: number[];
|
|
178
|
+
/** What the user said about why the specs stand as they are. */
|
|
179
|
+
reason: string;
|
|
180
|
+
}
|
|
167
181
|
/** Scoped human instruction recorded by the host; bindings do not authenticate its origin. */
|
|
168
182
|
export interface OwnerAcceptance {
|
|
169
183
|
schemaVersion: 1;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Guarded completion
|
|
2
2
|
|
|
3
|
-
Use this reference to submit
|
|
3
|
+
Use this reference to submit, snapshot, finalize, accept or recover a spec.
|
|
4
4
|
|
|
5
5
|
## Stable local interface
|
|
6
6
|
|
|
@@ -12,6 +12,7 @@ node .joycraft/runtime/completion.mjs scope --queue <queue-path> --spec <id>
|
|
|
12
12
|
node .joycraft/runtime/completion.mjs snapshot --queue <queue-path> --spec <id> --out <subject.json>
|
|
13
13
|
node .joycraft/runtime/completion.mjs finalize-review --queue <queue-path> --spec <id> --report <report.json>
|
|
14
14
|
node .joycraft/runtime/completion.mjs accept-owner --queue <queue-path> --spec <id> --decision <owner-acceptance.json>
|
|
15
|
+
node .joycraft/runtime/completion.mjs accept-owner --legacy --queue <queue-path> --spec <id>[,<id>...] --decision <legacy.json>
|
|
15
16
|
node .joycraft/runtime/completion.mjs accept-waiver --queue <queue-path> --spec <id> --waiver <feature-waiver.json> [--report <report.json>]
|
|
16
17
|
node .joycraft/runtime/completion.mjs recover --queue <queue-path>
|
|
17
18
|
```
|
|
@@ -24,7 +25,7 @@ An optional `verification.changeScope` records an explicit full Git commit SHA i
|
|
|
24
25
|
|
|
25
26
|
A requirement input may optionally declare exact `scope.anchors` or `scope.decisionIds`. Anchors bind complete named heading subtrees together with their ancestor context and non-decision document context; decision IDs bind complete stable JSON decision records. They may be combined for a canonical brief whose frontmatter contains a `decisions:` JSON array. A criterion may name such a record as `frontmatter.decisions.<id>`; an explicit `decisionIds` selector must include that ID. Heading-only scopes keep all frontmatter decisions governing. Pure JSON decision records support `decisionIds` only, so unsupported JSON heading anchors fail instead of being ignored. Anchor selection supports ATX (`#`) headings outside fenced code blocks; setext and linked headings are not selectors. A required criterion anchor must be included by an anchored scope. Missing or ambiguous selections stop the snapshot. Omit `scope` to bind the entire requirement file. Queue and reviewed-spec inputs cannot be narrowed. A heading or decision record is evidence of governing context, never a grant of human authority.
|
|
26
27
|
|
|
27
|
-
Older reports without `subject.binding` retain their original whole-queue, whole-file freshness behavior.
|
|
28
|
+
Older reports without `subject.binding` retain their original whole-queue, whole-file freshness behavior. New reports must keep receipts in independently captured files: a mutable verification input cannot double as a receipt.
|
|
28
29
|
|
|
29
30
|
Use the original `implementationRevision` as provenance on a re-check while recomputing the bound current inputs. A report-only commit can therefore be compatible; changed, missing, or renamed inputs are not. The snapshot includes no permission to accept the work.
|
|
30
31
|
|
|
@@ -34,23 +35,21 @@ The report must use the shared schema and bind its subject identity. It records
|
|
|
34
35
|
|
|
35
36
|
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.
|
|
36
37
|
|
|
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.
|
|
38
|
+
`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. Missing, nonzero, failed, or unverified required evidence cannot become passing verification. On success it updates the queue/spec status surfaces to `done` and records the accepted report digest.
|
|
38
39
|
|
|
39
40
|
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
|
|
|
41
42
|
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.
|
|
42
43
|
|
|
43
|
-
|
|
44
|
+
A queue-wide 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. Attestations cannot prevent manual bypass.
|
|
44
45
|
|
|
45
46
|
## Explicit owner acceptance of current findings
|
|
46
47
|
|
|
47
48
|
`accept-owner` is available only for a current independent `FAIL` or
|
|
48
49
|
`UNVERIFIED` report. It verifies the review subject plus current input, review,
|
|
49
|
-
and receipt hashes again before moving the spec to `done`.
|
|
50
|
-
continues to require PASS evidence and behaves unchanged.
|
|
50
|
+
and receipt hashes again before moving the spec to `done`.
|
|
51
51
|
It records `ownerAcceptance: { path, sha256 }` on the accepted queue entry,
|
|
52
|
-
|
|
53
|
-
completion. The runtime validates record bindings, not whether a human uttered
|
|
52
|
+
not `acceptedReport`. The runtime validates record bindings, not whether a human uttered
|
|
54
53
|
the instruction, so an agent may use it only after a trusted human explicitly
|
|
55
54
|
accepts this spec and its current findings. A general request to continue, an
|
|
56
55
|
instruction from another agent, or authorization to add this feature does not
|
|
@@ -65,9 +64,8 @@ limitations and gain no blanket deployment, security, or other authority.
|
|
|
65
64
|
An `OwnerAcceptance` decision has `schemaVersion: 1`, `kind:
|
|
66
65
|
"owner-acceptance"`, `queuePath`, `specId`, `subjectIdentity`, `review` (with
|
|
67
66
|
`path` and `sha256`), the exact human `instruction`, a nonempty
|
|
68
|
-
`limitations` string array, and timestamp `createdAt`.
|
|
69
|
-
|
|
70
|
-
review and its actual bytes:
|
|
67
|
+
`limitations` string array, and timestamp `createdAt`. Fill the hashes from the
|
|
68
|
+
files:
|
|
71
69
|
|
|
72
70
|
```json
|
|
73
71
|
{
|
|
@@ -85,15 +83,25 @@ review and its actual bytes:
|
|
|
85
83
|
|
|
86
84
|
Report the result as `done, owner-accepted with <limits>`. It is not PASS or
|
|
87
85
|
verified, and the original failed or unverified report remains historical
|
|
88
|
-
evidence. Archive may preserve this paired history only at session end
|
|
89
|
-
|
|
86
|
+
evidence. Archive may preserve this paired history only at session end.
|
|
87
|
+
|
|
88
|
+
## Legacy acceptance
|
|
89
|
+
|
|
90
|
+
Only on the owner's own words, `accept-owner --legacy` accepts specs marked
|
|
91
|
+
`done` with no acceptance, as they are. Any other spec, a spec that went
|
|
92
|
+
through review, or a decision file that git ignores refuses the whole call with
|
|
93
|
+
exit 2. Commit the file in the feature folder beside the queue. It has
|
|
94
|
+
`schemaVersion: 1`, `kind: "legacy"`, `queuePath`, verbatim `statement`,
|
|
95
|
+
`statedAt`, `specs` (the `--spec` ids) and `reason` (the owner's words); never
|
|
96
|
+
`review`. Entries stay `done` with `ownerAcceptance: { path, sha256, legacy:
|
|
97
|
+
true }`; a rerun changes nothing. The runtime checks only the record: it cannot
|
|
98
|
+
tell an old `done` spec from a new one, or check that the owner spoke.
|
|
90
99
|
|
|
91
100
|
## Feature waiver
|
|
92
101
|
|
|
93
|
-
|
|
102
|
+
A `FeatureWaiver` loosens the review defaults for
|
|
94
103
|
one feature's queue, only in the user's own words from that feature's
|
|
95
|
-
interview. The agent never proposes or asks about one
|
|
96
|
-
starts from the defaults. Record the user's words in the note of a settled brief
|
|
104
|
+
interview. The agent never proposes or asks about one. Record the user's words in the note of a settled brief
|
|
97
105
|
decision, then write the feature's one waiver file, `waiver.json` beside
|
|
98
106
|
`brief.md` (never a verification input), before any review runs:
|
|
99
107
|
|
|
@@ -121,17 +129,15 @@ words (at least three; whitespace and line wraps are normalized).
|
|
|
121
129
|
- **Skip means review never runs** (decision `block-review-dispatch`).
|
|
122
130
|
`dispatch-preflight.mjs` refuses a reviewer for a queue whose `waiver.json`
|
|
123
131
|
covers `no-review`, in the worker tree or the coordinator tree, and refuses
|
|
124
|
-
while that file is unreadable.
|
|
125
|
-
that `no-review` completes. Without `--report`, `no-review` completes an
|
|
132
|
+
while that file is unreadable. Without `--report`, `no-review` completes an
|
|
126
133
|
`in-review` spec. As an extra guard it still refuses when a review report for
|
|
127
134
|
the spec is visible in the feature folder or `.joycraft/local/packets/`.
|
|
128
135
|
- With `--report`, the report must be current and independent (validated as for
|
|
129
136
|
`accept-owner`), `UNVERIFIED`, and every non-`PASS` observation must carry
|
|
130
137
|
`cause: "tool-break"`; the waiver must cover `tool-break`. The report keeps
|
|
131
|
-
its verdict; evidence errors are returned as diagnostics.
|
|
132
|
-
waiver does not block reviewer dispatch.
|
|
138
|
+
its verdict; evidence errors are returned as diagnostics.
|
|
133
139
|
- A `FAIL` verdict or any `FAIL` observation never completes, whatever `covers`
|
|
134
|
-
says.
|
|
140
|
+
says.
|
|
135
141
|
|
|
136
142
|
Limit: a review that ran before `waiver.json` existed is caught only by the
|
|
137
143
|
folder guard. The waiver comes from the interview, so it exists before dispatch.
|
|
@@ -8,53 +8,53 @@ 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:
|
|
12
|
-
back to `in-review`, get an independent
|
|
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
|
|
17
17
|
first; else set the frontmatter to the queue's status and tell the user;
|
|
18
|
-
- a current queue or spec file that does not parse: repair it and tell the user
|
|
18
|
+
- a current queue or spec file that does not parse: repair it and tell the user;
|
|
19
|
+
- a legacy acceptance whose decision file is missing or changed: restore it
|
|
20
|
+
from git, else stop and tell the user.
|
|
19
21
|
|
|
20
22
|
A spec held at `in-review` is never a problem. Queues older than
|
|
21
23
|
`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.
|
|
24
24
|
|
|
25
25
|
## The Stop hook
|
|
26
26
|
|
|
27
27
|
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,
|
|
29
|
-
message
|
|
30
|
-
|
|
31
|
-
check finds that result at the next stop.
|
|
28
|
+
gate check each time it is about to stop. On exit 2, the agent gets the
|
|
29
|
+
message and must do the step it names. The hook is not a sandbox: a shell
|
|
30
|
+
command can still write the queue file.
|
|
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"
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
37
|
+
- `change: "none"`: tell the user the `message`.
|
|
38
|
+
- `problems`: The user is here, so ask one question that names each spec
|
|
39
|
+
marked `done` with no review on record: accept them as they are, or send
|
|
40
|
+
them back for review? On "accept", per queue write one decision file
|
|
41
|
+
whose `statement` quotes the user verbatim and whose `reason`
|
|
42
|
+
records what the user says, and run one
|
|
43
|
+
[`accept-owner --legacy`](completion.md#legacy-acceptance) call; on
|
|
44
|
+
"review", set them back to `in-review`. Never accept without the user's
|
|
45
|
+
words. Run the command a drift message names. Tell the user what you
|
|
46
|
+
changed, then plan again. Stop and ask about a file that does not parse.
|
|
47
|
+
- else: continue.
|
|
42
48
|
2. Show the change to `.claude/settings.json` (`before` and `after`) on a page,
|
|
43
49
|
as [showing a page](artifacts.md#showing-a-page) says. In two lines, say
|
|
44
50
|
what the Stop hook does and how to turn it off.
|
|
45
51
|
3. On the user's yes, run `node .joycraft/runtime/gate.mjs hook --on`. Do not
|
|
46
52
|
edit `.claude/settings.json` by hand.
|
|
47
53
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
changes nothing. If the file is not valid JSON, the command stops and writes
|
|
51
|
-
nothing; tell the user.
|
|
54
|
+
`--on` adds one Stop hook and changes no other byte of the user's file. If the
|
|
55
|
+
file is not valid JSON, it writes nothing; tell the user.
|
|
52
56
|
|
|
53
57
|
## Turn the gates off
|
|
54
58
|
|
|
55
59
|
The user says "Turn off Joycraft's gates". That request is the yes. Run
|
|
56
60
|
`node .joycraft/runtime/gate.mjs hook --off` and tell the user its message.
|
|
57
|
-
When nobody changed the file after `--on`, the file is again byte for byte as
|
|
58
|
-
it was before `--on`. `.joycraft/local/gate-hook.json` keeps the record for
|
|
59
|
-
this. Without a usable record, it removes Joycraft's Stop hook and any
|
|
60
|
-
`hooks.Stop` list or `hooks` object left empty, and its message names each one.
|
|
@@ -26,13 +26,14 @@ timeout, through
|
|
|
26
26
|
`node .joycraft/runtime/evidence.mjs run --receipt <path> -- <command...>`
|
|
27
27
|
(`--timeout-ms <n>` changes the limit). It uses no shell and saves raw stdout
|
|
28
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
|
|
30
|
-
|
|
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:
|
|
31
32
|
`exitCode: null`, `timedOut: true`. Set the host tool timeout to at least this
|
|
32
33
|
limit. A shorter default (for example 120000 ms) ends the wrapper before the
|
|
33
34
|
child. A timeout during parallel runs is not yet a hang: rerun once, alone,
|
|
34
|
-
with fewer workers. If it times out again, report it
|
|
35
|
-
|
|
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
|
|
36
37
|
(`until …; do sleep`, `kill -0`, polling a log): start a long command in the
|
|
37
38
|
background, keep working, and act on its completion notice. If a shared lock
|
|
38
39
|
or verify slot stays busy over 5 minutes, stop and report it. Never
|
|
@@ -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.
|
|
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
|
|
|
@@ -284,6 +284,15 @@ function historicalDecision(root, queuePath, state, reconciliation) {
|
|
|
284
284
|
}
|
|
285
285
|
requireValue(isObject(owner) && isSha256(owner.sha256), `Spec ${state.spec.id} is not accepted`);
|
|
286
286
|
const ownerPath = relativePath(owner.path);
|
|
287
|
+
if (owner.legacy === true) {
|
|
288
|
+
// Done before the gates and accepted as it is: the owner's words are the only record.
|
|
289
|
+
let ownerBytes;
|
|
290
|
+
try { ownerBytes = readLocal(root, ownerPath); } catch { ownerBytes = null; }
|
|
291
|
+
requireValue(ownerBytes !== null && sha256(ownerBytes) === owner.sha256, `Legacy acceptance decision is missing or changed: ${ownerPath}. Restore it from git; if you cannot, stop and tell the user`);
|
|
292
|
+
const decision = parseJson(ownerBytes, ownerPath);
|
|
293
|
+
validateOwnerAcceptance({ decision, decisionPath: ownerPath, state, legacy: true });
|
|
294
|
+
return { kind: 'legacy-acceptance', path: ownerPath, sha256: owner.sha256, report: null, receipts: [], limitations: [`accepted as it is by the owner, with no review: "${decision.statement}"`] };
|
|
295
|
+
}
|
|
287
296
|
const ownerBytes = readLocal(root, ownerPath);
|
|
288
297
|
requireValue(sha256(ownerBytes) === owner.sha256, `Owner acceptance is missing or changed: ${ownerPath}`);
|
|
289
298
|
const decision = parseJson(ownerBytes, ownerPath);
|
|
@@ -362,7 +371,7 @@ export function previewArchiveFeature({ root = process.cwd(), feature, phase, at
|
|
|
362
371
|
const reconciliation = readReconciliation(root, feature, reconciliationPath);
|
|
363
372
|
const evidence = [];
|
|
364
373
|
for (const item of queue.specs ?? []) {
|
|
365
|
-
const state = readQueue({ root, queuePath, specId: item.id });
|
|
374
|
+
const state = readQueue({ root, queuePath, specId: item.id, criteria: item?.ownerAcceptance?.legacy !== true });
|
|
366
375
|
evidence.push(historicalDecision(root, queuePath, state, reconciliation));
|
|
367
376
|
}
|
|
368
377
|
requireValue(Array.isArray(queue.specs) && queue.specs.length > 0 && queue.specs.every(spec => spec.status === 'done'), 'Every spec must be done before archiving the whole feature');
|
|
@@ -176,9 +176,9 @@ export function recover({ root = process.cwd(), queuePath }) {
|
|
|
176
176
|
return { status: 'restored', queuePath, specId: journal.specId };
|
|
177
177
|
}
|
|
178
178
|
|
|
179
|
-
async function writeCompletion({ root, queuePath, specId, state, status = 'done', metadataKey, metadata, validate, stableFiles }) {
|
|
179
|
+
async function writeCompletion({ root, queuePath, specId, state, status = 'done', metadataKey, metadata, validate, stableFiles, specIds = [specId], criteria = true }) {
|
|
180
180
|
const updatedQueue = structuredClone(state.queue);
|
|
181
|
-
Object.assign(updatedQueue.specs.find(spec => spec.id ===
|
|
181
|
+
for (const id of specIds) Object.assign(updatedQueue.specs.find(spec => spec.id === id), { status, [metadataKey]: metadata });
|
|
182
182
|
const journal = {
|
|
183
183
|
schemaVersion: 1, queuePath, specId,
|
|
184
184
|
files: [
|
|
@@ -203,7 +203,7 @@ async function writeCompletion({ root, queuePath, specId, state, status = 'done'
|
|
|
203
203
|
// Catch overlapping worker edits during the two writes before accepting them.
|
|
204
204
|
for (const file of journal.files) requireValue(sha256(readLocal(root, file.path)) === file.after.sha256, `Completion conflict: ${file.path} changed after write`);
|
|
205
205
|
for (const stable of stableFiles) requireValue(sha256(readLocal(root, stable.path)) === stable.sha256, `${stable.label} changed during completion`);
|
|
206
|
-
validate(readQueue({ root, queuePath, specId }));
|
|
206
|
+
validate(readQueue({ root, queuePath, specId, criteria }));
|
|
207
207
|
unlinkSync(pendingFile);
|
|
208
208
|
} catch (error) {
|
|
209
209
|
// Before the first write there is nothing to restore; a kept journal would
|
|
@@ -274,7 +274,13 @@ export async function submit({ root = process.cwd(), queuePath, specId }) {
|
|
|
274
274
|
* JSON cannot authenticate that a human said it, so this validates only the
|
|
275
275
|
* scoped binding and deliberately never treats the text as cryptographic proof.
|
|
276
276
|
*/
|
|
277
|
-
export function validateOwnerAcceptance({ decision, decisionPath, state, report, reportPath, reportBytes }) {
|
|
277
|
+
export function validateOwnerAcceptance({ decision, decisionPath, state, report, reportPath, reportBytes, legacy = false }) {
|
|
278
|
+
if (legacy) {
|
|
279
|
+
// A record marked legacy reads only a legacy decision that names this spec; it has no review.
|
|
280
|
+
validateLegacyDecision(decision, Array.isArray(decision?.specs) ? decision.specs : [], state.queuePath);
|
|
281
|
+
requireValue(decision.specs.includes(state.spec.id), `Legacy acceptance ${decisionPath} does not name spec ${state.spec.id}`);
|
|
282
|
+
return;
|
|
283
|
+
}
|
|
278
284
|
decisionPath = relativePath(decisionPath);
|
|
279
285
|
reportPath = relativePath(reportPath);
|
|
280
286
|
requireValue(isObject(decision) && decision.schemaVersion === 1 && decision.kind === 'owner-acceptance', 'Owner acceptance needs schemaVersion 1 and kind owner-acceptance');
|
|
@@ -340,6 +346,65 @@ export async function acceptOwner({ root = process.cwd(), queuePath, specId, dec
|
|
|
340
346
|
return { status: 'done', unchanged: false, ownerAcceptance, verdict: report.verdict, unresolved: report.unresolved, evidenceErrors, limitations: decision.limitations, implementationRevision: report.subject.implementationRevision };
|
|
341
347
|
}
|
|
342
348
|
|
|
349
|
+
const legacyFields = ['schemaVersion', 'kind', 'queuePath', 'statement', 'statedAt', 'specs', 'reason'];
|
|
350
|
+
const idList = ids => [...ids].sort((left, right) => left - right).join(',');
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* A legacy decision holds the owner's own words accepting specs that were done
|
|
354
|
+
* before the gates, as they are. It names no review. Like owner acceptance,
|
|
355
|
+
* local JSON cannot prove a human said them; this validates only the record.
|
|
356
|
+
*/
|
|
357
|
+
export function validateLegacyDecision(decision, specIds, queuePath) {
|
|
358
|
+
requireValue(isObject(decision) && decision.schemaVersion === 1 && decision.kind === 'legacy', 'Legacy acceptance needs schemaVersion 1 and kind legacy');
|
|
359
|
+
requireValue(decision.review === undefined, 'A legacy acceptance has no review field; a reviewed spec uses accept-owner without --legacy');
|
|
360
|
+
requireValue(Object.keys(decision).every(key => legacyFields.includes(key)), `Legacy acceptance has unknown fields; it has only ${legacyFields.join(', ')}`);
|
|
361
|
+
requireValue(nonempty(decision.queuePath) && relativePath(decision.queuePath) === relativePath(queuePath), `Legacy acceptance is for another queue (${decision.queuePath}); it must name ${queuePath}`);
|
|
362
|
+
requireValue(nonempty(decision.statement), "Legacy acceptance needs the owner's own words in statement");
|
|
363
|
+
requireValue(nonempty(decision.statedAt) && Number.isFinite(Date.parse(decision.statedAt)), 'Legacy acceptance needs a valid statedAt date');
|
|
364
|
+
requireValue(nonempty(decision.reason), 'Legacy acceptance needs a reason');
|
|
365
|
+
requireValue(Array.isArray(decision.specs) && decision.specs.length > 0 && decision.specs.every(Number.isSafeInteger) && new Set(decision.specs).size === decision.specs.length, 'Legacy acceptance specs must be distinct spec ids');
|
|
366
|
+
requireValue(idList(decision.specs) === idList(specIds), `Legacy acceptance specs (${idList(decision.specs)}) must equal the --spec ids (${idList(specIds)})`);
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* Accept specs that are done in queue and frontmatter with no acceptance, as
|
|
371
|
+
* they are, on the owner's own words. All or nothing: any other spec refuses
|
|
372
|
+
* with exit 2 before a write. The same decision again changes nothing.
|
|
373
|
+
*/
|
|
374
|
+
export async function acceptLegacy({ root = process.cwd(), queuePath, specIds, decisionPath }) {
|
|
375
|
+
try {
|
|
376
|
+
queuePath = relativePath(queuePath);
|
|
377
|
+
decisionPath = relativePath(decisionPath);
|
|
378
|
+
requireValue(specIds.length > 0 && new Set(specIds).size === specIds.length, 'Name each spec once');
|
|
379
|
+
assertNoJournal(root, queuePath);
|
|
380
|
+
const decisionBytes = readLocal(root, decisionPath);
|
|
381
|
+
validateLegacyDecision(parseJson(decisionBytes, decisionPath), specIds, queuePath);
|
|
382
|
+
const { gitIgnored } = await import('./evidence.mjs');
|
|
383
|
+
requireValue(!gitIgnored(root, decisionPath), `Git ignores the legacy decision ${decisionPath}; put it in the feature folder beside the queue and commit it`);
|
|
384
|
+
const ownerAcceptance = { path: decisionPath, sha256: sha256(decisionBytes), legacy: true };
|
|
385
|
+
// Returns the ids that still need the record; refuses any spec that cannot take it.
|
|
386
|
+
const pending = () => specIds.filter(id => {
|
|
387
|
+
const { spec, specPath, queue } = readQueue({ root, queuePath, specId: id, criteria: false });
|
|
388
|
+
requireValue(spec.status === 'done', `Spec ${id} is ${spec.status}; legacy acceptance is only for a spec that is done with no acceptance`);
|
|
389
|
+
requireValue(spec.submitted === undefined && visibleReports({ root, queuePath, specId: id }).length === 0, `Spec ${id} went through review; complete it with finalize-review or the normal owner acceptance`);
|
|
390
|
+
requireValue(decisionPath !== queuePath && !queue.specs.some(item => path.posix.join(path.posix.dirname(queuePath), item.file) === decisionPath) && !spec.verification.inputs.some(input => relativePath(input.path) === decisionPath), 'The legacy decision must be its own file, not a queue, spec or verification input');
|
|
391
|
+
if (canonical(spec.ownerAcceptance) === canonical(ownerAcceptance)) return false;
|
|
392
|
+
requireValue(spec.acceptedReport === undefined && spec.ownerAcceptance === undefined && spec.waiver === undefined, `Spec ${id} (${specPath}) already has an accepted report, owner acceptance or waiver; legacy acceptance cannot replace it`);
|
|
393
|
+
return true;
|
|
394
|
+
});
|
|
395
|
+
const todo = pending();
|
|
396
|
+
if (todo.length) {
|
|
397
|
+
await writeCompletion({
|
|
398
|
+
root, queuePath, specId: todo[0], specIds: todo, criteria: false, state: readQueue({ root, queuePath, specId: todo[0], criteria: false }),
|
|
399
|
+
metadataKey: 'ownerAcceptance', metadata: ownerAcceptance,
|
|
400
|
+
stableFiles: [{ path: decisionPath, sha256: ownerAcceptance.sha256, label: 'Legacy decision' }],
|
|
401
|
+
validate: () => { pending(); },
|
|
402
|
+
});
|
|
403
|
+
}
|
|
404
|
+
return { status: 'done', legacy: true, unchanged: todo.length === 0, specs: specIds, ownerAcceptance };
|
|
405
|
+
} catch (error) { throw refused(error); }
|
|
406
|
+
}
|
|
407
|
+
|
|
343
408
|
const waiverCovers = ['no-review', 'tool-break'];
|
|
344
409
|
|
|
345
410
|
/** The feature folder holds the brief that quotes a waiver and the one waiver file itself. */
|
|
@@ -539,8 +604,11 @@ export async function acceptWaiver({ root = process.cwd(), queuePath, specId, wa
|
|
|
539
604
|
}
|
|
540
605
|
|
|
541
606
|
function argumentsFor(argv) {
|
|
542
|
-
const [command, ...
|
|
543
|
-
|
|
607
|
+
const [command, ...rest] = argv;
|
|
608
|
+
const legacy = command === 'accept-owner' && rest.includes('--legacy');
|
|
609
|
+
const args = legacy ? rest.filter(arg => arg !== '--legacy') : rest;
|
|
610
|
+
requireValue(args.length === rest.length - (legacy ? 1 : 0), 'Invalid or duplicate argument: --legacy');
|
|
611
|
+
requireValue(['snapshot', 'scope', 'submit', 'complete', 'finalize-review', 'accept-owner', 'accept-waiver', 'recover'].includes(command), 'Usage: completion.mjs scope|submit --queue <path> --spec <id> | snapshot --queue <path> --spec <id> --out <subject.json> | complete|finalize-review --queue <path> --spec <id> --report <report.json> | accept-owner --queue <path> --spec <id> --decision <decision.json> | accept-owner --legacy --queue <path> --spec <id>[,<id>...] --decision <decision.json> | accept-waiver --queue <path> --spec <id> --waiver <waiver.json> [--report <report.json>] | recover --queue <path>');
|
|
544
612
|
const flags = {};
|
|
545
613
|
for (let i = 0; i < args.length; i += 2) {
|
|
546
614
|
requireValue(['--queue', '--spec', '--out', '--report', '--decision', '--waiver'].includes(args[i]) && nonempty(args[i + 1]) && flags[args[i]] === undefined, `Invalid or duplicate argument: ${args[i]}`);
|
|
@@ -549,12 +617,14 @@ function argumentsFor(argv) {
|
|
|
549
617
|
const expected = command === 'recover' ? ['--queue'] : command === 'scope' || command === 'submit' ? ['--queue', '--spec'] : ['--queue', '--spec', command === 'snapshot' ? '--out' : command === 'accept-owner' ? '--decision' : command === 'accept-waiver' ? '--waiver' : '--report'];
|
|
550
618
|
const optional = command === 'accept-waiver' ? ['--report'] : [];
|
|
551
619
|
requireValue(expected.every(flag => flags[flag] !== undefined) && Object.keys(flags).every(flag => expected.includes(flag) || optional.includes(flag)), `Missing or unexpected arguments for ${command}`);
|
|
552
|
-
|
|
553
|
-
|
|
620
|
+
const id = /^(?:0|[1-9]\d*)$/;
|
|
621
|
+
if (legacy) { if (!flags['--spec'].split(',').every(item => id.test(item) && Number.isSafeInteger(Number(item)))) throw refused(new Error('Spec IDs must be nonnegative integers separated by commas')); }
|
|
622
|
+
else if (command !== 'recover') requireValue(id.test(flags['--spec']) && Number.isSafeInteger(Number(flags['--spec'])), 'Spec ID must be a nonnegative integer');
|
|
623
|
+
return { command, flags, legacy };
|
|
554
624
|
}
|
|
555
625
|
|
|
556
626
|
export async function main(argv = process.argv.slice(2)) {
|
|
557
|
-
const { command, flags } = argumentsFor(argv);
|
|
627
|
+
const { command, flags, legacy } = argumentsFor(argv);
|
|
558
628
|
const root = process.cwd();
|
|
559
629
|
const queuePath = flags['--queue'];
|
|
560
630
|
let result;
|
|
@@ -575,6 +645,7 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
575
645
|
for (const id of result.untraced) process.stderr.write(`Warning: criterion ${id} has no [AC:${id}] test in the spec's check inputs\n`);
|
|
576
646
|
} else if (command === 'recover') result = recover({ root, queuePath });
|
|
577
647
|
else if (command === 'accept-waiver') result = await acceptWaiver({ root, queuePath, specId: Number(flags['--spec']), waiverPath: flags['--waiver'], reportPath: flags['--report'] });
|
|
648
|
+
else if (legacy) result = await acceptLegacy({ root, queuePath, specIds: flags['--spec'].split(',').map(Number), decisionPath: flags['--decision'] });
|
|
578
649
|
else if (command === 'accept-owner') result = await acceptOwner({ root, queuePath, specId: Number(flags['--spec']), decisionPath: flags['--decision'] });
|
|
579
650
|
else result = await complete({ root, queuePath, specId: Number(flags['--spec']), reportPath: flags['--report'] });
|
|
580
651
|
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
|
|
@@ -154,7 +154,7 @@ const usage = 'Usage: evidence.mjs run --receipt <path> [--timeout-ms <n>] -- <c
|
|
|
154
154
|
const refusal = message => Object.assign(new Error(message), { exitCode: 2 });
|
|
155
155
|
const refuse = (condition, message) => { if (!condition) throw refusal(message); };
|
|
156
156
|
|
|
157
|
-
function gitIgnored(root, relative) {
|
|
157
|
+
export function gitIgnored(root, relative) {
|
|
158
158
|
try {
|
|
159
159
|
execFileSync('git', ['check-ignore', '-q', '--', relative], { cwd: root, stdio: 'ignore' });
|
|
160
160
|
return true;
|
|
@@ -265,6 +265,8 @@ export async function main(args = process.argv.slice(2)) {
|
|
|
265
265
|
const result = await runEvidence({ receipt: flags['--receipt'], argv: rest.slice(end + 1),
|
|
266
266
|
timeoutMs: flags['--timeout-ms'] === undefined ? defaultTimeoutMs : Number(flags['--timeout-ms']) });
|
|
267
267
|
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
|
|
268
|
+
// The receipt is written either way; a failed, killed or timed-out command exits 1. Exit 2 is only for a refusal.
|
|
269
|
+
if (result.command.exitCode !== 0) process.exitCode = 1;
|
|
268
270
|
return result;
|
|
269
271
|
}
|
|
270
272
|
|