joycraft 1.3.0 → 1.5.0
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 +154 -4
- package/dist/joycraft-release.json +1 -1
- package/package.json +3 -3
- package/payload/.agents/skills/joycraft-context/SKILL.md +5 -6
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +9 -8
- package/payload/.agents/skills/joycraft-entry/SKILL.md +8 -19
- package/payload/.agents/skills/joycraft-implement/SKILL.md +16 -17
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +10 -15
- package/payload/.agents/skills/joycraft-testing/SKILL.md +3 -9
- package/payload/.agents/skills/joycraft-verify/SKILL.md +20 -21
- package/payload/.claude/agents/joycraft-implementer.md +5 -5
- package/payload/.claude/agents/joycraft-reviewer.md +3 -6
- package/payload/.joycraft/contracts/types.d.ts +18 -0
- package/payload/.joycraft/references/architecture.md +2 -4
- package/payload/.joycraft/references/completion.md +16 -21
- package/payload/.joycraft/references/context.md +11 -34
- package/payload/.joycraft/references/dispatch.md +7 -40
- package/payload/.joycraft/references/gates.md +60 -0
- package/payload/.joycraft/references/retro.md +6 -15
- package/payload/.joycraft/references/settings.md +6 -3
- package/payload/.joycraft/references/setup.md +4 -4
- package/payload/.joycraft/references/testing.md +21 -21
- package/payload/.joycraft/references/worktrees.md +1 -1
- package/payload/.joycraft/runtime/completion.mjs +92 -6
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +1 -1
- package/payload/.joycraft/runtime/dispatch-start.mjs +61 -4
- package/payload/.joycraft/runtime/evidence.mjs +134 -0
- package/payload/.joycraft/runtime/gate.mjs +308 -0
- package/payload/.joycraft/runtime/identity.mjs +5 -1
- package/payload/.joycraft/runtime/queue-check.mjs +355 -0
- package/payload/.joycraft/runtime/status.mjs +46 -5
- package/payload/PIN +31 -28
- package/payload/scripts/export.mjs +5 -2
|
@@ -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;
|
|
@@ -79,10 +79,8 @@ subject or provide the reviewer with an intended verdict or implementer reasonin
|
|
|
79
79
|
Update only affected accepted facts in their owning reference, reconciling them
|
|
80
80
|
at session end before any eligible archival. Active choices remain in their
|
|
81
81
|
brief; rationale links to that choice; proposals stay marked as proposals.
|
|
82
|
-
References describe and navigate the project. They
|
|
83
|
-
|
|
84
|
-
extra live classification calls merely to maintain a map. Retrieval scores and
|
|
85
|
-
this procedure do not certify exhaustive discovery.
|
|
82
|
+
References describe and navigate the project. They do not grant permission.
|
|
83
|
+
Retrieval scores and this procedure do not certify exhaustive discovery.
|
|
86
84
|
|
|
87
85
|
Keep task context bounded to relevant sources. When evaluating the change,
|
|
88
86
|
record newly delivered input bytes, repeated reads/provider calls, human
|
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
# Guarded completion
|
|
2
2
|
|
|
3
|
-
Use this reference
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
@@ -43,19 +43,17 @@ and a snippet of at most 1,800 UTF-8 bytes around the first matching line.
|
|
|
43
43
|
Snippets include source line numbers and whether they are partial. Large files
|
|
44
44
|
are never described as searched or ranked. Read those separately when needed.
|
|
45
45
|
|
|
46
|
-
Every selected candidate is retained, including a zero-scored file
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
`batches` records candidate IDs, returned model, usage and elapsed time for each
|
|
56
|
-
successful call. `omitted`, `unreadable`, and `unranked` explain files that were
|
|
57
|
-
not scored. Hashes bind the result to the bytes read, not future edits. Open the
|
|
46
|
+
Every selected candidate is retained, including a zero-scored file; there is no
|
|
47
|
+
candidate cap or score cutoff. A keyword search can miss paraphrases or
|
|
48
|
+
dependencies; this result never claims exhaustive context. Refine and follow
|
|
49
|
+
relevant links.
|
|
50
|
+
|
|
51
|
+
The JSON `references` come in local-search order: local score, then path.
|
|
52
|
+
`status` is `local-search-only`, and `unranked` lists each candidate with the
|
|
53
|
+
reason `scoring-disabled`. `omitted` and `unreadable` explain files that were
|
|
54
|
+
not read. Hashes bind the result to the bytes read, not future edits. Open the
|
|
58
55
|
current source before relying on it; a bounded snippet is not the full file.
|
|
56
|
+
Invalid inputs or an unavailable Git inventory exit nonzero.
|
|
59
57
|
|
|
60
58
|
For an unclear state, data, or responsibility boundary, use the result as a
|
|
61
59
|
starting point and inspect the actual coupled sources as well: the owner and its
|
|
@@ -63,28 +61,7 @@ callers, readers, writers, or persistence boundary as applicable. Add discovered
|
|
|
63
61
|
paths to the brief/spec verification inputs before dispatch, and state any
|
|
64
62
|
unresolved coverage. Read `architecture.md` for focused examples. This expands
|
|
65
63
|
source discovery only when the seam matters; it does not make the context map a
|
|
66
|
-
second source of product decisions or a
|
|
67
|
-
|
|
68
|
-
Live scoring is the default. `.joycraft/hooks-config.json` supplies
|
|
69
|
-
`enabled`, `timeoutMs`, and Keychain service `JEV_API_KEY`; `--keychain-service` overrides it. The
|
|
70
|
-
shared `.joycraft/runtime/hooks/judge.mjs` primitive uses an existing
|
|
71
|
-
environment credential first, then the configured macOS Keychain service.
|
|
72
|
-
Credentials are never saved in the config, command arguments, result or project.
|
|
73
|
-
No dotenv file, transcript, or whole-project model dump is used.
|
|
74
|
-
The shared redactor removes recognizable credential patterns from outgoing
|
|
75
|
-
query/snippet strings before the Jev call; content hashes still identify the
|
|
76
|
-
original local bytes. Pattern redaction cannot identify arbitrary secret text.
|
|
77
|
-
Setting `enabled: false` selects explicit `local-search-only` output without
|
|
78
|
-
credential lookup; each candidate is marked unranked with `scoring-disabled`.
|
|
79
|
-
|
|
80
|
-
Missing credentials, malformed provider output or an outage stop further model
|
|
81
|
-
calls for that invocation. All selected references remain available in local
|
|
82
|
-
order where unranked; previously successful scores retain their provenance.
|
|
83
|
-
`status: incomplete-provider-ranking`, `provenance: local-search-fallback` and
|
|
84
|
-
`fallbackReason` make this explicit. Exit success means a usable result exists,
|
|
85
|
-
not that every candidate was scored; inspect `status` and `scoredCount`.
|
|
86
|
-
Invalid inputs or an unavailable Git inventory exit nonzero. Provider scores
|
|
87
|
-
advise reading order and never approve intent, authorize work or certify evidence.
|
|
64
|
+
second source of product decisions or a prohibition.
|
|
88
65
|
|
|
89
66
|
Treat only the context homes as current authority. `docs/features/` is working
|
|
90
67
|
material that can be stale until its feature is archived, and `docs/archive/` is
|
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
For normal native work, the host launches the worker and the child then uses the
|
|
4
4
|
dispatch-start entry point from its actual root before any tasked edit. A
|
|
5
5
|
coordinator uses it itself only when it is the worker actor. It validates delivery
|
|
6
|
-
and returns a ready
|
|
7
|
-
|
|
6
|
+
and returns a ready decision plus the bounded packet; it never launches a worker,
|
|
7
|
+
alters queue status, or accepts work.
|
|
8
8
|
For a mutable worker or stateful runtime check, first apply the conditional
|
|
9
9
|
[worker-isolation policy](worktrees.md); this preflight does not create a
|
|
10
10
|
worktree or a resource lease. A `read-only` workspace keeps declared source
|
|
@@ -18,7 +18,6 @@ those specs with `accept-waiver` instead.
|
|
|
18
18
|
|
|
19
19
|
- [Start a native dispatch](#start-a-native-dispatch)
|
|
20
20
|
- [Call the portable dispatch API](#call-the-portable-dispatch-api)
|
|
21
|
-
- [Bind the hook source view](#bind-the-hook-source-view)
|
|
22
21
|
- [Validate capabilities before dispatch](#validate-capabilities-before-dispatch)
|
|
23
22
|
- [Check the reviewer report](#check-the-reviewer-report)
|
|
24
23
|
|
|
@@ -90,6 +89,7 @@ it before the first implementer mutation, and startup preserves it. The separate
|
|
|
90
89
|
workspace `--base-revision` option keeps its documented topology check.
|
|
91
90
|
Implementer dispatch requires each dependency to be `done`; reviewer dispatch
|
|
92
91
|
does not require the target itself to be done. Unknown roles are rejected.
|
|
92
|
+
Reviewer startup prints `reviewRound` and `reviewLimit: 3`; a round is one distinct set of reviewed inputs, so a commit that changes none of the spec's verification inputs keeps the round, and a fourth round exits 2.
|
|
93
93
|
|
|
94
94
|
When a reviewer startup exits non-zero or returns `ready: false`, run it once
|
|
95
95
|
more, alone, with a fresh packet path. If it fails again, stop that spec's
|
|
@@ -101,17 +101,8 @@ cause and the repair it tried. The coordinator tells the user at the first hold,
|
|
|
101
101
|
in the conversation, while other workers keep running; it does not wait for the
|
|
102
102
|
session end. The session-end summary lists every held spec again.
|
|
103
103
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
prompt history for an enforced startup is explicit
|
|
107
|
-
`ready: false`, exit code 2, and `unenforced`; it is not a permission request,
|
|
108
|
-
an invented prompt, or a substitute session ID. Continue discovery and other
|
|
109
|
-
unrelated authorized work, including manual/disabled workflows, but do not
|
|
110
|
-
dispatch the claimed enforced worker. Do not
|
|
111
|
-
select an arbitrary task to make a native relationship appear valid. A child
|
|
112
|
-
binding uses its own root and a real prompt; it may inherit the same native
|
|
113
|
-
parent session authority only when an observed linked coordinator relationship
|
|
114
|
-
is valid. A unique new root session needs its own actual prompt.
|
|
104
|
+
A valid startup returns `hooks: { enabled: false, reason: "hooks-not-installed" }`
|
|
105
|
+
and `ready: true`. It is not a cryptographic attestation.
|
|
115
106
|
|
|
116
107
|
When the host reports a native agent/invocation ID, also pass
|
|
117
108
|
`--implementer-host <host> --implementer-agent <actual-agent-id>`. For a root
|
|
@@ -142,8 +133,8 @@ from a legacy self-attested call.
|
|
|
142
133
|
|
|
143
134
|
Call the portable API from a Codex, Claude, Pi, OMP, or Copilot adapter. Normal
|
|
144
135
|
native startup calls `startDispatch(options, nativeEvent)` so the runtime can
|
|
145
|
-
validate the observed session
|
|
146
|
-
|
|
136
|
+
validate the observed session and agent relationship before it returns a
|
|
137
|
+
packet:
|
|
147
138
|
|
|
148
139
|
```js
|
|
149
140
|
import { startDispatch } from './.joycraft/runtime/dispatch-start.mjs';
|
|
@@ -171,30 +162,6 @@ When `AGENTS.md` has a `## Review loop` section or this machine has
|
|
|
171
162
|
`{ path, section, local? }`, the shared section plus, when present,
|
|
172
163
|
`local: { path, record }` with this machine's host tools.
|
|
173
164
|
|
|
174
|
-
## Bind the hook source view
|
|
175
|
-
|
|
176
|
-
Dispatch-start prepares and binds its hash-bound `hookSourceView` with actual
|
|
177
|
-
native IDs. The lower-level manual bind command remains only for an explicit
|
|
178
|
-
non-native boundary. It uses the actual native session ID reported at startup,
|
|
179
|
-
never a generated UUID:
|
|
180
|
-
|
|
181
|
-
```sh
|
|
182
|
-
node .joycraft/runtime/hooks/cli.mjs bind-source \
|
|
183
|
-
--session <actual-native-session-id> --packet <project-relative-packet.json>
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
Bind a known parent session before launching children when the host exposes
|
|
187
|
-
parent inheritance. Otherwise, bind the child after it reports its own actual
|
|
188
|
-
session ID. For children sharing a parent session but working on different
|
|
189
|
-
specs, add `--agent <actual-native-child-id>` when binding each child. Its task
|
|
190
|
-
view remains separate while human prompts still inherit from the parent.
|
|
191
|
-
Rebind after the brief changes. The hook view currently receives only
|
|
192
|
-
hash-checked brief and decision pointers; the worker packet retains the exact
|
|
193
|
-
decision records. An unknown ID leaves the dependent
|
|
194
|
-
Jev check advisory and unverified; it does not permit a substitute ID. The view
|
|
195
|
-
makes selected saved answers available to Jev, but never grants permission or
|
|
196
|
-
an expected review outcome.
|
|
197
|
-
|
|
198
165
|
## Validate capabilities before dispatch
|
|
199
166
|
|
|
200
167
|
`claims.capabilities` must include `filesystem:read`,
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Gates
|
|
2
|
+
|
|
3
|
+
Joycraft's rule is that only an accepted review completes a spec. The gate
|
|
4
|
+
check makes the rule a command, so it does not depend on the agent.
|
|
5
|
+
|
|
6
|
+
## What the gate checks
|
|
7
|
+
|
|
8
|
+
`node .joycraft/runtime/gate.mjs check` exits 2 and names each problem on
|
|
9
|
+
stderr. Each message names its next step:
|
|
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;
|
|
14
|
+
- a spec whose queue status and frontmatter status are different: pending
|
|
15
|
+
journal: run the named `recover` command, stop on a conflict; accepted: run
|
|
16
|
+
`node .joycraft/runtime/status.mjs --fix`; unaccepted `done`: the step above
|
|
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.
|
|
19
|
+
|
|
20
|
+
A spec held at `in-review` is never a problem. Queues older than
|
|
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.
|
|
24
|
+
|
|
25
|
+
## The Stop hook
|
|
26
|
+
|
|
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, 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.
|
|
32
|
+
|
|
33
|
+
## Turn the gates on
|
|
34
|
+
|
|
35
|
+
The user says "Turn on Joycraft's gates", or says yes to the offer in setup.
|
|
36
|
+
|
|
37
|
+
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.
|
|
42
|
+
2. Show the change to `.claude/settings.json` (`before` and `after`) on a page,
|
|
43
|
+
as [showing a page](artifacts.md#showing-a-page) says. In two lines, say
|
|
44
|
+
what the Stop hook does and how to turn it off.
|
|
45
|
+
3. On the user's yes, run `node .joycraft/runtime/gate.mjs hook --on`. Do not
|
|
46
|
+
edit `.claude/settings.json` by hand.
|
|
47
|
+
|
|
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.
|
|
52
|
+
|
|
53
|
+
## Turn the gates off
|
|
54
|
+
|
|
55
|
+
The user says "Turn off Joycraft's gates". That request is the yes. Run
|
|
56
|
+
`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.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Use `joycraft-retro` on a requested session worth learning from, including a
|
|
4
4
|
successful session with unexpected friction. It proposes environment improvements;
|
|
5
|
-
it does not run on every session end
|
|
5
|
+
it does not run on every session end or change acceptance.
|
|
6
6
|
|
|
7
7
|
## Prepare native session evidence
|
|
8
8
|
|
|
@@ -22,9 +22,9 @@ node .joycraft/runtime/retro.mjs prepare --source /absolute/path/session.jsonl -
|
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
Line selection reduces the prepared context, not source-read memory: this small
|
|
25
|
-
helper reads the supplied file into memory. Use an existing episode export
|
|
26
|
-
|
|
27
|
-
|
|
25
|
+
helper reads the supplied file into memory. Use an existing episode export for
|
|
26
|
+
sources too large for that approach, retaining the original source references
|
|
27
|
+
and any selection limits.
|
|
28
28
|
|
|
29
29
|
Read `coverage.json` first, then `conversation.md` and `tools.jsonl`. The source
|
|
30
30
|
hash and physical line references let you return to exact raw evidence. The
|
|
@@ -45,17 +45,8 @@ inspect material before sharing it. It creates no permission or decision state.
|
|
|
45
45
|
Other harness formats can be read directly; do not describe an unsupported
|
|
46
46
|
format as normalized or invent native coverage.
|
|
47
47
|
|
|
48
|
-
Keep any linked session/worker files
|
|
49
|
-
|
|
50
|
-
Existing hook metrics can summarize explicit receipts without replaying paid
|
|
51
|
-
checks:
|
|
52
|
-
|
|
53
|
-
```sh
|
|
54
|
-
node .joycraft/runtime/hooks/metrics.mjs --log /absolute/path/events.jsonl
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
Provider-reported usage is not an invoice; absent calls, timing or usage remain
|
|
58
|
-
unknown. Do not equate a missing receipt with a free or absent call.
|
|
48
|
+
Keep any linked session/worker files and final review reports as separate
|
|
49
|
+
sources. A single file may not contain all workers or continuations.
|
|
59
50
|
|
|
60
51
|
## Judge a candidate
|
|
61
52
|
|
|
@@ -49,9 +49,12 @@ On "uninstall Joycraft" or "remove Joycraft":
|
|
|
49
49
|
1. Read `.joycraft/installation.json`. Its `files` list holds each installed path
|
|
50
50
|
and the `sha256` it had at install.
|
|
51
51
|
2. Show the user what goes: the listed files, with each file whose bytes changed
|
|
52
|
-
since install marked as edited,
|
|
53
|
-
|
|
52
|
+
since install marked as edited, Joycraft's Stop hook in `.claude/settings.json`
|
|
53
|
+
when the gates are on, and `.joycraft/` itself. Say what stays: `AGENTS.md`,
|
|
54
|
+
`CLAUDE.md`, `docs/` and `joycraft.yaml` are theirs.
|
|
54
55
|
3. Offer to remove the Joycraft lines from `AGENTS.md` and `CLAUDE.md` (the context
|
|
55
56
|
map rows that point into `.joycraft/`, and the Joycraft rules). Show that diff
|
|
56
57
|
separately.
|
|
57
|
-
4. On the user's yes,
|
|
58
|
+
4. On the user's yes, first run `node .joycraft/runtime/gate.mjs hook --off`. It
|
|
59
|
+
removes Joycraft's Stop hook. When the gates are off, it changes nothing. Then
|
|
60
|
+
delete the files, then `.joycraft/`. Do not commit.
|
|
@@ -320,15 +320,15 @@ the owning brief and do not ask it again.
|
|
|
320
320
|
## Finish setup and continue
|
|
321
321
|
|
|
322
322
|
Step 5 of [Set up the context map](#set-up-the-context-map) is the finish
|
|
323
|
-
check; also check that command claims match their cited source. Setup does not
|
|
324
|
-
dependencies, or replace the user's workflow.
|
|
325
|
-
|
|
323
|
+
check; also check that command claims match their cited source. Setup does not
|
|
324
|
+
change credentials, install dependencies, or replace the user's workflow.
|
|
325
|
+
When `.joycraft/installation.json` lists the `claude` host, offer the [gates](gates.md) once, in one line; turn them on only on the user's yes.
|
|
326
326
|
|
|
327
327
|
## Upgrade and agent onboarding
|
|
328
328
|
|
|
329
329
|
Updates go through the Joycraft CLI; follow [update guidance](update.md). The
|
|
330
330
|
installation manifest `.joycraft/installation.json` records the installed bytes;
|
|
331
|
-
it is dispatch input, not proof that
|
|
331
|
+
it is dispatch input, not proof that a review was independent.
|
|
332
332
|
|
|
333
333
|
A new worker reads `.joycraft/preferences.json` before work, reuses explicit
|
|
334
334
|
model, effort, role, concurrency, verification and question-style choices, and inspects the
|
|
@@ -21,30 +21,30 @@ end-to-end requirement follows from these examples.
|
|
|
21
21
|
|
|
22
22
|
### Running tests
|
|
23
23
|
|
|
24
|
-
Run
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
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; exit 0
|
|
30
|
+
only means the run was recorded. At the limit it ends the process group:
|
|
31
|
+
`exitCode: null`, `timedOut: true`. Set the host tool timeout to at least this
|
|
32
|
+
limit. A shorter default (for example 120000 ms) ends the wrapper before the
|
|
33
|
+
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
|
+
with the receipt; do not keep rerunning. Never wait in a foreground loop
|
|
36
|
+
(`until …; do sleep`, `kill -0`, polling a log): start a long command in the
|
|
37
|
+
background, keep working, and act on its completion notice. If a shared lock
|
|
38
|
+
or verify slot stays busy over 5 minutes, stop and report it. Never
|
|
39
|
+
give a verdict while your own command is still running. A reviewer may reuse
|
|
40
|
+
a suite receipt bound to the same revision. A bug fix needs a meaningful
|
|
41
|
+
failing regression only when one can distinguish the repaired fault.
|
|
39
42
|
|
|
40
43
|
## Commands and receipt records
|
|
41
44
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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.
|
|
45
|
+
In `test` and `command` observations, `command.exitCode` is the actual outcome;
|
|
46
|
+
`null` means unavailable. Never substitute grepped success text or a
|
|
47
|
+
pipeline's final status for it. A nonzero or missing status cannot support PASS.
|
|
48
48
|
|
|
49
49
|
Each observation has at least one supporting receipt with a project-relative path
|
|
50
50
|
and SHA-256. A receipt may be raw command output, inspection notes, an image, or a
|
|
@@ -128,7 +128,7 @@ guidance](https://code.claude.com/docs/en/hooks#reference-scripts-by-path).
|
|
|
128
128
|
|
|
129
129
|
On hosts without that native capability, create an equivalent manual Git linked
|
|
130
130
|
worktree at an explicit, verified ref. Build each packet from its actual root:
|
|
131
|
-
`workerRoot`, manifest path, source paths,
|
|
131
|
+
`workerRoot`, manifest path, source paths, commands,
|
|
132
132
|
receipts, and report paths must resolve there. A coordinator may not substitute
|
|
133
133
|
the shared checkout merely because its sources look equivalent.
|
|
134
134
|
|