joycraft 0.7.17 → 1.0.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.
- package/README.md +148 -140
- package/dist/cli.js +1593 -373
- package/dist/cli.js.map +1 -1
- package/dist/joycraft-release.json +1 -1
- package/package.json +9 -3
- package/payload/.agents/skills/joycraft-context/SKILL.md +36 -0
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +68 -0
- package/payload/.agents/skills/joycraft-entry/SKILL.md +109 -0
- package/payload/.agents/skills/joycraft-implement/SKILL.md +118 -0
- package/payload/.agents/skills/joycraft-retro/SKILL.md +54 -0
- package/payload/.agents/skills/joycraft-retro/agents/openai.yaml +5 -0
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +82 -0
- package/payload/.agents/skills/joycraft-testing/SKILL.md +60 -0
- package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +59 -0
- package/payload/.agents/skills/joycraft-ui-slice/scripts/serve.mjs +97 -0
- package/payload/.agents/skills/joycraft-verify/SKILL.md +103 -0
- package/payload/.claude/agents/joycraft-implementer.md +36 -0
- package/payload/.claude/agents/joycraft-reviewer.md +35 -0
- package/payload/.joycraft/assets/artifacts/kit.css +102 -0
- package/payload/.joycraft/assets/artifacts/kit.js +301 -0
- package/payload/.joycraft/assets/artifacts/transports.js +236 -0
- package/payload/.joycraft/contracts/types.d.ts +185 -0
- package/payload/.joycraft/references/architecture.md +90 -0
- package/payload/.joycraft/references/archive.md +211 -0
- package/payload/.joycraft/references/artifacts.md +176 -0
- package/payload/.joycraft/references/completion.md +109 -0
- package/payload/.joycraft/references/context.md +85 -0
- package/payload/.joycraft/references/delivery.md +32 -0
- package/payload/.joycraft/references/dispatch.md +231 -0
- package/payload/.joycraft/references/recurring-failures.md +33 -0
- package/payload/.joycraft/references/retro.md +94 -0
- package/payload/.joycraft/references/setup.md +295 -0
- package/payload/.joycraft/references/testing.md +120 -0
- package/payload/.joycraft/references/update.md +44 -0
- package/payload/.joycraft/references/workflow.md +113 -0
- package/payload/.joycraft/references/worktrees.md +174 -0
- package/payload/.joycraft/runtime/archive.mjs +463 -0
- package/payload/.joycraft/runtime/artifacts/cli.mjs +61 -0
- package/payload/.joycraft/runtime/artifacts/decisions.mjs +214 -0
- package/payload/.joycraft/runtime/artifacts/model.mjs +161 -0
- package/payload/.joycraft/runtime/artifacts/preferences.mjs +127 -0
- package/payload/.joycraft/runtime/artifacts/render.mjs +21 -0
- package/payload/.joycraft/runtime/artifacts/server.mjs +40 -0
- package/payload/.joycraft/runtime/completion.mjs +300 -0
- package/payload/.joycraft/runtime/context/cli.mjs +75 -0
- package/payload/.joycraft/runtime/context/index.mjs +29 -0
- package/payload/.joycraft/runtime/context/search.mjs +149 -0
- package/payload/.joycraft/runtime/coordinator.mjs +169 -0
- package/payload/.joycraft/runtime/delivery.mjs +142 -0
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +535 -0
- package/payload/.joycraft/runtime/dispatch-start.mjs +106 -0
- package/payload/.joycraft/runtime/evidence.mjs +137 -0
- package/payload/.joycraft/runtime/identity.mjs +486 -0
- package/payload/.joycraft/runtime/kickoff.mjs +174 -0
- package/payload/.joycraft/runtime/redact.mjs +9 -0
- package/payload/.joycraft/runtime/retro.mjs +151 -0
- package/payload/.joycraft/runtime/review-tools.json +34 -0
- package/payload/.joycraft/runtime/review-tools.mjs +331 -0
- package/payload/.joycraft/runtime/scope.mjs +129 -0
- package/payload/.joycraft/runtime/status.mjs +96 -0
- package/payload/.joycraft/runtime/update-check.mjs +142 -0
- package/payload/.joycraft/runtime/worktrees.mjs +201 -0
- package/payload/.joycraft/templates/README.md +7 -0
- package/payload/.joycraft/templates/artifact.json +33 -0
- package/payload/.joycraft/templates/brief.md +35 -0
- package/payload/.joycraft/templates/decisions.md +13 -0
- package/payload/.joycraft/templates/project-context.md +36 -0
- package/payload/.joycraft/templates/queue.json +27 -0
- package/payload/.joycraft/templates/spec.md +39 -0
- package/payload/.joycraft/templates/ui-slice.html +71 -0
- package/payload/PIN +77 -0
- package/payload/scripts/export.mjs +301 -0
- package/payload/scripts/hook-paths.mjs +35 -0
- package/payload/scripts/legacy-hooks.mjs +128 -0
- package/payload/scripts/legacy-inventory.json +117 -0
- package/dist/chunk-35RQLGKM.js +0 -2167
- package/dist/chunk-35RQLGKM.js.map +0 -1
- package/dist/chunk-7BPB2IKY.js +0 -255
- package/dist/chunk-7BPB2IKY.js.map +0 -1
- package/dist/chunk-B73DPYYC.js +0 -377
- package/dist/chunk-B73DPYYC.js.map +0 -1
- package/dist/chunk-K4AI6FKB.js +0 -417
- package/dist/chunk-K4AI6FKB.js.map +0 -1
- package/dist/chunk-KKDKC4FM.js +0 -115
- package/dist/chunk-KKDKC4FM.js.map +0 -1
- package/dist/chunk-OMFGDJW4.js +0 -97
- package/dist/chunk-OMFGDJW4.js.map +0 -1
- package/dist/chunk-YLWBDXF4.js +0 -3999
- package/dist/chunk-YLWBDXF4.js.map +0 -1
- package/dist/chunk-Z5JFEGWG.js +0 -563
- package/dist/chunk-Z5JFEGWG.js.map +0 -1
- package/dist/init-O2QC5X57.js +0 -60
- package/dist/init-O2QC5X57.js.map +0 -1
- package/dist/init-autofix-2DMBO4QN.js +0 -122
- package/dist/init-autofix-2DMBO4QN.js.map +0 -1
- package/dist/install-manifest-EQHT4474.js +0 -37
- package/dist/install-manifest-EQHT4474.js.map +0 -1
- package/dist/release-artifact-4TL5L2ZY.js +0 -14
- package/dist/release-artifact-4TL5L2ZY.js.map +0 -1
- package/dist/release-resolver-P2H46QTU.js +0 -293
- package/dist/release-resolver-P2H46QTU.js.map +0 -1
- package/dist/telemetry-store-IBO5GRTA.js +0 -14
- package/dist/telemetry-store-IBO5GRTA.js.map +0 -1
- package/dist/update-LYHS4FBH.js +0 -21
- package/dist/update-LYHS4FBH.js.map +0 -1
- package/dist/update-check-YT765NE7.js +0 -36
- package/dist/update-check-YT765NE7.js.map +0 -1
- package/dist/upgrade-GMP6JQ52.js +0 -28
- package/dist/upgrade-GMP6JQ52.js.map +0 -1
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Evidence at the boundary of the claim
|
|
2
|
+
|
|
3
|
+
The requirement owns the claim; choose evidence that can distinguish a correct
|
|
4
|
+
implementation from a plausible fault. Prefer the nearest meaningful boundary.
|
|
5
|
+
A test or command that only scans source still supplies structural evidence;
|
|
6
|
+
running it successfully does not turn its claim into runtime proof.
|
|
7
|
+
|
|
8
|
+
| Claim | Useful observation | Limit |
|
|
9
|
+
|---|---|---|
|
|
10
|
+
| Discount precedes tax | Call the real invoice function with multiple quantities, a nonzero discount and tax; assert exact totals | Establishes bounded arithmetic, not payment, storage or UI behavior |
|
|
11
|
+
| Repair advances through a lifecycle | Compose real transitions; check final state, rejected transition and unchanged prior state | Individual handler tests alone may miss the composed sequence |
|
|
12
|
+
| Module exports a specified contract | Inspect the export or compile a real consumer | Structural evidence; source presence cannot prove execution |
|
|
13
|
+
| Narrow layout remains usable | Inspect the actual narrow render; operate relevant controls and inspect results | Screenshot capture alone is not inspection; appearance cannot establish durable persistence |
|
|
14
|
+
|
|
15
|
+
An unchanged characterization can pass while a new regression fails. Red/green
|
|
16
|
+
means the new assertion detects the right fault, not that every test must fail.
|
|
17
|
+
Do not edit production code merely to manufacture red evidence; an isolated
|
|
18
|
+
temporary copy or existing failing behavior can demonstrate sensitivity when
|
|
19
|
+
useful. Record exactly what was exercised. No universal coverage target or
|
|
20
|
+
end-to-end requirement follows from these examples.
|
|
21
|
+
|
|
22
|
+
### Running tests
|
|
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.
|
|
39
|
+
|
|
40
|
+
## Commands and receipt records
|
|
41
|
+
|
|
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.
|
|
48
|
+
|
|
49
|
+
Each observation has at least one supporting receipt with a project-relative path
|
|
50
|
+
and SHA-256. A receipt may be raw command output, inspection notes, an image, or a
|
|
51
|
+
browser trace. Hash the bytes after saving. Completion checks the file bytes;
|
|
52
|
+
evidence validation itself never reads files. A hash proves which bytes were
|
|
53
|
+
reviewed, not that their assertions are true.
|
|
54
|
+
|
|
55
|
+
## One flow, several criteria
|
|
56
|
+
|
|
57
|
+
Use the shared `FlowEvidence` shape. Give the flow a stable id, subject identity,
|
|
58
|
+
the relevant criterion ids, representative input/initial state, expected result,
|
|
59
|
+
actual observations, receipt references and explicit limits. Multiple observations
|
|
60
|
+
can supply different required evidence kinds. One composed booking/cancellation
|
|
61
|
+
flow, for example, can support several related criteria when the observations
|
|
62
|
+
actually cover them. Do not attach unrelated criteria merely to fill the matrix.
|
|
63
|
+
|
|
64
|
+
`validateEvidence(report, criteria)` returns `{ ok, errors }`. It fails on malformed
|
|
65
|
+
evidence, a missing criterion/kind pair, an unknown criterion, a mismatched flow
|
|
66
|
+
identity, a source scan labelled runtime/visual, unresolved FAIL/UNVERIFIED,
|
|
67
|
+
unsuccessful command status or uninspected visual evidence. Earlier failing runs
|
|
68
|
+
belong in diagnostic history; an acceptance report must contain the current
|
|
69
|
+
observations after repair. Do not relabel a failure as resolved without rerunning
|
|
70
|
+
the affected check against the current subject.
|
|
71
|
+
|
|
72
|
+
The validator does not inspect receipt contents, execute commands, determine
|
|
73
|
+
whether inputs are representative, or discover omitted dependencies/requirements.
|
|
74
|
+
The independent reviewer checks those judgments against the actual brief/spec.
|
|
75
|
+
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.
|
|
78
|
+
|
|
79
|
+
## Visual observations and the repair loop
|
|
80
|
+
|
|
81
|
+
Record the rendered route, relevant state, viewport width/height, what the observer
|
|
82
|
+
actually inspected, and each performed interaction with its resulting outcome.
|
|
83
|
+
For routing claims, exercise the real router state, including reopen/reload,
|
|
84
|
+
back/forward, and scrolling when they are part of the journey.
|
|
85
|
+
`visual.inspected` is true only after the observer examined the render. A
|
|
86
|
+
screenshot saved to a path but never viewed leaves the check UNVERIFIED. DOM or
|
|
87
|
+
accessibility checks can support runtime observations without certifying visual
|
|
88
|
+
appearance. Use a separate runtime observation when the claim includes durable
|
|
89
|
+
state, backend effects or another behavior that appearance alone cannot prove.
|
|
90
|
+
|
|
91
|
+
When a visual requirement specifically calls for restoration or comparison, name
|
|
92
|
+
the actual visible element and its owning clarified requirement. Compare it with
|
|
93
|
+
an accepted reference only when that reference is part of the requirement or is
|
|
94
|
+
available and relevant to the comparison. This does not create a universal
|
|
95
|
+
before/after gate.
|
|
96
|
+
|
|
97
|
+
An empty `visual.interactions` list is appropriate for a static appearance-only
|
|
98
|
+
claim. For an interactive requirement, the reviewer must require the relevant
|
|
99
|
+
actions and outcomes; the validator cannot infer them from a criterion id. A
|
|
100
|
+
disabled control or error state can itself be an observed result; explain it.
|
|
101
|
+
|
|
102
|
+
When an inspection finds a scoped defect: retain the observation, fix it, render
|
|
103
|
+
again, repeat affected interactions and inspect the result. If the fix changes a
|
|
104
|
+
bound input, obtain a new subject and fresh affected observations before seeking
|
|
105
|
+
completion. Keep the final flow concise and link prior diagnostics rather than
|
|
106
|
+
copying a transcript. An unavailable browser, inaccessible route or blocked tool
|
|
107
|
+
is a limit and UNVERIFIED check, not permission to bypass access controls or
|
|
108
|
+
declare visual PASS. Do not wrap, relay, or otherwise route around a denied
|
|
109
|
+
command; ask the host for the legitimate correction. Continue independent work
|
|
110
|
+
that remains possible.
|
|
111
|
+
|
|
112
|
+
## Where checks run
|
|
113
|
+
|
|
114
|
+
Read the project's owning CI and runtime policy before adding a check to CI.
|
|
115
|
+
Local browser verification, routine CI checks and one-off data/media studies
|
|
116
|
+
can have different environments and lifetimes. A required local visual check
|
|
117
|
+
does not automatically belong in CI. Diagnose an environment-only UNVERIFIED
|
|
118
|
+
result as an environment limitation, repair that setup, and rerun the affected
|
|
119
|
+
review; do not send unchanged code through a speculative fix round. A genuine
|
|
120
|
+
test race still needs a code/test diagnosis, not just a longer timeout.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Updates
|
|
2
|
+
|
|
3
|
+
`node .joycraft/runtime/update-check.mjs check` tells you if a newer Joycraft
|
|
4
|
+
exists. It reads npm once a day at most, sends no project data, and stops after
|
|
5
|
+
two seconds. If it prints nothing, say nothing and continue.
|
|
6
|
+
|
|
7
|
+
If it prints JSON, read `action`. Put the line below in your next reply to the user,
|
|
8
|
+
even when the request is about something else and even when your reply is short:
|
|
9
|
+
|
|
10
|
+
- `note`: tell the user `message` in one line. Do not ask anything.
|
|
11
|
+
- `ask`: tell the user `message` in one line and ask once: update now, not now, or
|
|
12
|
+
turn off. Do not ask again in this session.
|
|
13
|
+
- `apply`: the user chose automatic updates. Follow "Update" below without asking.
|
|
14
|
+
If the plan would back up an edited file, stop and ask instead.
|
|
15
|
+
|
|
16
|
+
Finish or park the work in progress before you update. Do not update in the middle
|
|
17
|
+
of a spec.
|
|
18
|
+
|
|
19
|
+
## Update
|
|
20
|
+
|
|
21
|
+
Use the version from `latest`:
|
|
22
|
+
|
|
23
|
+
1. Run `npx joycraft@<latest> update . --plan --json`. Show the user the plan in
|
|
24
|
+
short lists: files changed and files backed up. With `apply`, skip this display.
|
|
25
|
+
2. Run `npx joycraft@<latest> update . --yes`. If `kind` is `migration`, this prints a
|
|
26
|
+
migration plan and stops: show the plan and follow its steps with the user. Never
|
|
27
|
+
apply a migration without the user's yes.
|
|
28
|
+
3. Run `npx joycraft@<latest> doctor .`.
|
|
29
|
+
4. Tell the user in plain words what is different now.
|
|
30
|
+
|
|
31
|
+
If the update fails, run `npx joycraft@<latest> update . --recover`, tell the user
|
|
32
|
+
that the files are back as they were, and continue your work.
|
|
33
|
+
|
|
34
|
+
## Other answers
|
|
35
|
+
|
|
36
|
+
- Not now: `node .joycraft/runtime/update-check.mjs snooze <latest>` stays quiet about
|
|
37
|
+
that version for seven days.
|
|
38
|
+
- Turn off: `node .joycraft/runtime/update-check.mjs policy off`.
|
|
39
|
+
- Automatic updates: `node .joycraft/runtime/update-check.mjs policy auto-safe`. Only
|
|
40
|
+
a release marked safe applies by itself. A new major version always asks.
|
|
41
|
+
- Stay on this version: `node .joycraft/runtime/update-check.mjs pin`, and `unpin` to
|
|
42
|
+
undo it.
|
|
43
|
+
|
|
44
|
+
These choices stay in `.joycraft/local/preferences.json`, on this machine.
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Brief, slice and queue
|
|
2
|
+
|
|
3
|
+
## Context and decisions
|
|
4
|
+
|
|
5
|
+
Read boundaries/context map before retrieving relevant existing decisions and
|
|
6
|
+
facts. Preserve those homes. The feature brief owns current intent and its
|
|
7
|
+
frontmatter `decisions:` is the single current decision-state authority.
|
|
8
|
+
`docs/context/decision-log.md` may link to a decision with reusable rationale;
|
|
9
|
+
visuals render the brief rather than keeping another answer database.
|
|
10
|
+
|
|
11
|
+
Retain every requested goal. Track factual/agent-only work separately from the
|
|
12
|
+
human-needed choice. A repair and a feature can share a brief and queue. Explicit
|
|
13
|
+
assumptions permit exploration and understood work, but do not settle a material
|
|
14
|
+
uncertainty. Keep questions contextual and short; use detail on demand. An open
|
|
15
|
+
choice blocks only its affected commitments, so continue independent authorized
|
|
16
|
+
work.
|
|
17
|
+
|
|
18
|
+
States are `open`, `clarified`, `backlogged`, `discarded`, `assigned`. A clarified
|
|
19
|
+
answer remains valid until materially affected by new intent or evidence. Reopen
|
|
20
|
+
that same ID with the reason and affected specs/evidence, clearing the current
|
|
21
|
+
answer; preserve prior rationale as history. Stop or revise affected production
|
|
22
|
+
commitments, not unrelated work.
|
|
23
|
+
Routine refinements within the answer do not require another approval.
|
|
24
|
+
|
|
25
|
+
## Decision artifacts
|
|
26
|
+
|
|
27
|
+
Ask the user to choose between options through the artifact workflow in
|
|
28
|
+
[artifacts.md](artifacts.md), not as a list in chat. Plain chat is only for one
|
|
29
|
+
quick yes/no or an open question with no options.
|
|
30
|
+
The brief remains authoritative; artifact data selects what to show and does not
|
|
31
|
+
copy the brief or hold independent answers.
|
|
32
|
+
|
|
33
|
+
## Interactive slices
|
|
34
|
+
|
|
35
|
+
The optional `joycraft-ui-slice/scripts/serve.mjs` helper supports a JSON flow
|
|
36
|
+
array under top-level `decisions:` in YAML frontmatter, as in the brief template.
|
|
37
|
+
Each displayed record has `id`, `status`, `question`, `answer` (null or an option
|
|
38
|
+
value), `options` (two or more `{value,label}` records) and `affected` (paths/IDs).
|
|
39
|
+
Options may additionally have a concise `description` and `requiresNote: true`.
|
|
40
|
+
Other record fields and all text outside that array are preserved. Unsupported or
|
|
41
|
+
malformed frontmatter is rejected; adapt the artifact to an existing project
|
|
42
|
+
format instead of migrating it without cause. This is an authoring convention,
|
|
43
|
+
not an additional shared runtime schema.
|
|
44
|
+
|
|
45
|
+
Use the existing decision or review surface for an unanswered choice when it is
|
|
46
|
+
already runnable and current; otherwise provide a self-contained HTML file. The shell
|
|
47
|
+
previews it in an isolated iframe; the `choice` query parameter contains the
|
|
48
|
+
selected option value. With no explicit decision id, the helper selects the first
|
|
49
|
+
unanswered `open` or `assigned` decision, then advances to the next one when the
|
|
50
|
+
brief changes. It presents a settled state when none remain; an explicit decision
|
|
51
|
+
id stays bound. Selecting an option previews it; “Save choice” writes the answer
|
|
52
|
+
and `clarified` status into the brief. Until that write succeeds, the on-screen
|
|
53
|
+
choice is only a draft. No localStorage or separate answer file is used. The shell
|
|
54
|
+
polls the current brief so another answer or relevant evidence change appears
|
|
55
|
+
without relying on stale page state; it preserves a valid draft when an unrelated
|
|
56
|
+
brief revision arrives. Reopening/reloading also reads the brief. The helper cannot
|
|
57
|
+
create production authorization: use the answer only within the scope already
|
|
58
|
+
authorized by the user.
|
|
59
|
+
|
|
60
|
+
The helper binds loopback, checks its request token and origin, and refuses stale
|
|
61
|
+
brief revisions. A clarified answer cannot be changed through this form. Reopen it
|
|
62
|
+
in the brief explicitly, recording the reason and affected specs/evidence first.
|
|
63
|
+
Backlogged/discarded choices are read-only. Keep the server private and stop it
|
|
64
|
+
after feedback. It is a local authoring aid, not a production service.
|
|
65
|
+
|
|
66
|
+
Inspect the render and relevant interactions with permitted tools. Record observed
|
|
67
|
+
outcomes, viewport, route/state and limits. A screenshot or static render is
|
|
68
|
+
enough for an appearance-only choice only when it is actually inspected; it cannot
|
|
69
|
+
prove that the answer was saved. Ask concise visual-detail questions before making
|
|
70
|
+
a pixel-sensitive choice when the available render leaves them material. Check
|
|
71
|
+
both file state and reload. If tools are unavailable or denied, mark required
|
|
72
|
+
visual work UNVERIFIED and continue disjoint work. Never bypass a denial with
|
|
73
|
+
another route.
|
|
74
|
+
|
|
75
|
+
## Commitment and queue
|
|
76
|
+
|
|
77
|
+
Use `docs/features/<slug>/specs/.joycraft-spec-queue.json` and the exact shapes in
|
|
78
|
+
`.joycraft/contracts/types.d.ts`. Only `todo`, `in-review`, `done` are
|
|
79
|
+
spec statuses, mirrored in spec frontmatter. Open or unknown decision state blocks
|
|
80
|
+
affected specs. Assigned work needs its answer or explicit permission to work
|
|
81
|
+
around it, recorded in the brief; backlogged/discarded scope is excluded.
|
|
82
|
+
|
|
83
|
+
Criterion IDs are stable; requirement paths and heading anchors point to the
|
|
84
|
+
source of the requirement, including clarified choices. Declare visual evidence
|
|
85
|
+
for relevant UI claims and runtime evidence for persistence/behavior. Structural
|
|
86
|
+
inspection alone cannot establish either. Keep the list complete against the
|
|
87
|
+
request. Verification inputs include exact brief/spec, implementation, check and
|
|
88
|
+
fixture paths; no globs. Include relevant files discovered during implementation.
|
|
89
|
+
When a clarified answer or relevant evidence changes, update and recheck only the
|
|
90
|
+
specs, criteria and inputs that depend on it; preserve independent completed or
|
|
91
|
+
authorized work.
|
|
92
|
+
|
|
93
|
+
For a shared requirement file containing independent work, an optional input
|
|
94
|
+
`scope` can select governing heading subtrees and decision IDs using the
|
|
95
|
+
[completion reference](completion.md). Include every current requirement that
|
|
96
|
+
governs the spec; keep whole-file binding when that boundary is unclear. A
|
|
97
|
+
selector narrows freshness binding, not human authority or review scope.
|
|
98
|
+
Prepared worker packets carry the exact selected answered decision records;
|
|
99
|
+
unanswered or ambiguous records remain visible limitations. New review subjects
|
|
100
|
+
bind the target queue record and its transitive dependencies; legacy subjects
|
|
101
|
+
retain their original strict binding.
|
|
102
|
+
|
|
103
|
+
Use dependencies for real ordering, not to serialize independent repairs behind
|
|
104
|
+
a visual decision. The implementation skill owns autonomous execution and the
|
|
105
|
+
independent-review/completion path. A queue produced here is not evidence of
|
|
106
|
+
successful behavior, authorization outside the request, or accepted completion.
|
|
107
|
+
|
|
108
|
+
For each spec in an independent concurrent wave, set
|
|
109
|
+
`execution: { "parallel": true }`; absent `execution` preserves legacy serial
|
|
110
|
+
behavior. If required worker isolation is unavailable, replan the affected wave
|
|
111
|
+
and set `execution.parallel` to `false` in the current queue before dispatch,
|
|
112
|
+
recording the reason; otherwise leave it unstarted. The coordinator applies
|
|
113
|
+
[worker isolation](worktrees.md) to that plan.
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# Worker isolation
|
|
2
|
+
|
|
3
|
+
Use this reference when planning, dispatching, testing, integrating, or closing
|
|
4
|
+
a queue with concurrent work.
|
|
5
|
+
|
|
6
|
+
## Choose an execution shape
|
|
7
|
+
|
|
8
|
+
`execution: { parallel: true }` marks a `QueueSpec` in an independent concurrent
|
|
9
|
+
wave. Omit `execution` for legacy serial behavior. Mark each spec only when its
|
|
10
|
+
planned wave can run independently; dependencies and overlapping ownership still
|
|
11
|
+
decide whether it is ready.
|
|
12
|
+
|
|
13
|
+
Known parallel mutators must use distinct linked worktrees with the same Git
|
|
14
|
+
common directory. A worker owns its worktree, its mutable build/dependency/cache
|
|
15
|
+
state, and the paths it changes until its result is integrated. The coordinator
|
|
16
|
+
retains the integration tree. Read-only reviewers may share the reviewed source
|
|
17
|
+
tree only while its declared inputs are fixed. They may write declared review
|
|
18
|
+
reports and receipts outside those frozen source inputs in a separately owned
|
|
19
|
+
output location. Runtime checks that mutate caches, browsers, or other state
|
|
20
|
+
need their own mutable runtime state.
|
|
21
|
+
|
|
22
|
+
This is a portable policy, not a host command recipe. Use only worktree,
|
|
23
|
+
worker, and runtime-isolation facilities the active host actually exposes. Do
|
|
24
|
+
not infer native flags, session IDs, or lifecycle features. If the required
|
|
25
|
+
isolation, project-owned disk capacity, or required resource lease is
|
|
26
|
+
unavailable, do not dispatch that spec as parallel. Replan the affected wave,
|
|
27
|
+
set its current queue entry's `execution.parallel` to `false` before dispatch,
|
|
28
|
+
and record the reason; then it may run serially. If that replan cannot be made,
|
|
29
|
+
leave the spec unstarted. The queue's `isolated` mode remains a separate
|
|
30
|
+
fresh-context requirement; a worktree alone does not satisfy it.
|
|
31
|
+
`read-only` describes source handling here; it does not create a filesystem
|
|
32
|
+
sandbox.
|
|
33
|
+
|
|
34
|
+
Before a large concurrent queue, print and retain a deterministic dispatch plan:
|
|
35
|
+
the target branch and captured refs, queue and integration owner, dependency
|
|
36
|
+
order, actual aggregate resource capacity across active runs, and any
|
|
37
|
+
project-owned leases. Verify the active workflow's real isolation and host
|
|
38
|
+
capabilities; do not assume agent frontmatter, a planned worktree, or a
|
|
39
|
+
runtime lifecycle feature is applied. These are observations to recheck on the
|
|
40
|
+
active host, not runtime enforcement.
|
|
41
|
+
|
|
42
|
+
Only one active queue/integration owner may advance a target branch at a time.
|
|
43
|
+
Other work may proceed only when its project-declared inputs, leases, and
|
|
44
|
+
integration boundary make that safe. Record durable coordinator ownership and
|
|
45
|
+
the captured refs before dispatch or restart, so recovery can distinguish this
|
|
46
|
+
run's resources from another session's.
|
|
47
|
+
|
|
48
|
+
## Commands
|
|
49
|
+
|
|
50
|
+
`worktrees.mjs` is the one home for worker trees on hosts without native
|
|
51
|
+
worktree isolation:
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
node .joycraft/runtime/worktrees.mjs create --queue <queue> --spec <id> --session <coordinator-session>
|
|
55
|
+
node .joycraft/runtime/worktrees.mjs list
|
|
56
|
+
node .joycraft/runtime/worktrees.mjs prune # preview
|
|
57
|
+
node .joycraft/runtime/worktrees.mjs prune --apply
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`create` adds `.joycraft/local/worktrees/<feature>-<spec>` on branch
|
|
61
|
+
`joycraft/<feature>-<spec>` from the current or `--base` revision and records the
|
|
62
|
+
owner in `.joycraft/local/worktrees.json`. `list` shows every linked tree with
|
|
63
|
+
its spec status, merged and clean state and size; a tree not in the ledger is
|
|
64
|
+
`unknown-owner`. `prune --apply` removes a tree only when it is recorded, its spec
|
|
65
|
+
is `done`, it is clean and its branch is contained in `--into` (default `HEAD`).
|
|
66
|
+
It never forces a removal. If the project's test runner discovers files under
|
|
67
|
+
dot folders, exclude `.joycraft/` from discovery.
|
|
68
|
+
|
|
69
|
+
`coordinator.mjs claim|heartbeat|release|show` keeps one coordinator lease per
|
|
70
|
+
queue in the main checkout's `.joycraft/local/coordinators/`. Every worker tree
|
|
71
|
+
reads the same lease. While a lease exists, `dispatch-start.mjs` starts a task only
|
|
72
|
+
with a matching `--coordinator-session` and names the coordinator in its output.
|
|
73
|
+
|
|
74
|
+
## Workspace input and project setup
|
|
75
|
+
|
|
76
|
+
Dispatch accepts an optional runtime workspace input:
|
|
77
|
+
|
|
78
|
+
```js
|
|
79
|
+
{ coordinatorRoot, parallel?: boolean, access: 'mutating' | 'read-only', baseRevision?: '<full-commit-SHA>' }
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
For a known parallel mutator, `access` is `mutating` and the runtime derives and
|
|
83
|
+
attests real paths, Git topology, and the actual `workerRoot` in the packet. A
|
|
84
|
+
read-only reviewer may use the coordinator root while its inputs remain stable,
|
|
85
|
+
and write only its declared report/receipt outputs outside those inputs. It must
|
|
86
|
+
not write governing inputs or run cache-mutating runtime work there. The host
|
|
87
|
+
must not claim a planned path as the actual root.
|
|
88
|
+
|
|
89
|
+
Record project-specific bootstrap, ignored-file, disk, and resource requirements
|
|
90
|
+
in `docs/context/worktrees.md` when that is the project's context home, or in
|
|
91
|
+
the existing context-map destination. Do not require a new record when no such
|
|
92
|
+
facts are needed. The worker's first action after its tree exists is to run the
|
|
93
|
+
documented bootstrap before edits, stateful runtime work, or packet preparation.
|
|
94
|
+
If the project lockfile changed since a tree was bootstrapped, complete its
|
|
95
|
+
documented dependency bootstrap again before its runtime or data commands. A
|
|
96
|
+
project-owned data lease remains serial across every tree when its project
|
|
97
|
+
defines one.
|
|
98
|
+
|
|
99
|
+
For initial mutable dispatch, supply the captured commit as `baseRevision`
|
|
100
|
+
(`prepare --base-revision <full-SHA>`). Preflight checks the actual Git root and
|
|
101
|
+
requires its `HEAD` to equal that commit, catching a tree created at a stale
|
|
102
|
+
base. Re-capture deliberately after integration instead of reusing an old
|
|
103
|
+
startup expectation. Omitting this optional field retains legacy topology-only
|
|
104
|
+
attestation; it does not prove the intended starting revision.
|
|
105
|
+
|
|
106
|
+
## Create and dispatch
|
|
107
|
+
|
|
108
|
+
Create each worker tree from the coordinator's captured base revision before
|
|
109
|
+
work starts. Do not copy untracked caches, credentials, or mutable state from
|
|
110
|
+
another worker. If bootstrap fails, preserve the tree and its failure output for
|
|
111
|
+
diagnosis; do not reuse it for another worker.
|
|
112
|
+
|
|
113
|
+
With [Claude Code worktrees](https://code.claude.com/docs/en/worktrees), use a
|
|
114
|
+
native agent's `isolation: "worktree"` capability when it is actually available,
|
|
115
|
+
or a custom-agent frontmatter worktree isolation setting. Claude's default
|
|
116
|
+
subagent base is the default branch, so select the captured current revision with
|
|
117
|
+
`worktree.baseRef: "head"` or an explicit manual ref and verify it. A native
|
|
118
|
+
auto-created path is unknown until the child launches: the child bootstraps, then
|
|
119
|
+
prepares or checks its packet from its real root before mutation. The coordinator
|
|
120
|
+
must not prepare a packet against an invented path.
|
|
121
|
+
|
|
122
|
+
`.worktreeinclude` is Claude-native only and applies to matching Git-ignored
|
|
123
|
+
files. A `WorktreeCreate` hook replaces creation and disables that automatic
|
|
124
|
+
include behavior. `CLAUDE_PROJECT_DIR` remains the original project directory;
|
|
125
|
+
the hook event's `cwd` is the active worktree. See the [Claude worktree
|
|
126
|
+
documentation](https://code.claude.com/docs/en/worktrees) and its [hook path
|
|
127
|
+
guidance](https://code.claude.com/docs/en/hooks#reference-scripts-by-path).
|
|
128
|
+
|
|
129
|
+
On hosts without that native capability, create an equivalent manual Git linked
|
|
130
|
+
worktree at an explicit, verified ref. Build each packet from its actual root:
|
|
131
|
+
`workerRoot`, manifest path, source paths, hook binding context, commands,
|
|
132
|
+
receipts, and report paths must resolve there. A coordinator may not substitute
|
|
133
|
+
the shared checkout merely because its sources look equivalent.
|
|
134
|
+
|
|
135
|
+
## Integrate and verify
|
|
136
|
+
|
|
137
|
+
When an implementation worker finishes, the coordinator integrates its proposed
|
|
138
|
+
bytes into the integration tree using the project's normal Git workflow and
|
|
139
|
+
resolves any conflicts there. Run integration checks and prepare review from the
|
|
140
|
+
final integrated bytes. A worker-tree test result is useful evidence, but it
|
|
141
|
+
does not replace checks or review of the integrated result. Do not rerun a broad
|
|
142
|
+
suite merely because a worker tree exists; reserve broad validation for the
|
|
143
|
+
final integrated code when it is needed.
|
|
144
|
+
|
|
145
|
+
A worktree does not establish an independent reviewer context or current review
|
|
146
|
+
evidence. Dispatch a reviewer through the existing separate-context policy, and
|
|
147
|
+
freeze its reviewed inputs while it observes them. A stable source-read-only
|
|
148
|
+
reviewer can use the integrated tree and write its declared reports/receipts
|
|
149
|
+
outside frozen inputs. A reviewer that needs cache-mutating runtime checks must
|
|
150
|
+
use an independent mutable runtime-state arrangement.
|
|
151
|
+
|
|
152
|
+
## Stop, restart, and environment blocks
|
|
153
|
+
|
|
154
|
+
A stopped run needs an ownership-aware teardown report: identify the run,
|
|
155
|
+
captured refs, known trees, leases, locks, and runtime processes; state which
|
|
156
|
+
were released, retained, or could not be identified. Do not automatically abort
|
|
157
|
+
an unknown active merge, remove an unknown tree or lock, stop an unknown
|
|
158
|
+
process, or force local state to equal a remote branch. Preserve ambiguous
|
|
159
|
+
state for diagnosis and hand it to its recorded owner. Restart only from the
|
|
160
|
+
durable journal and an updated plan, with a new coordinator ownership record.
|
|
161
|
+
|
|
162
|
+
When a review is unverified solely because of an identified environment
|
|
163
|
+
condition, repair or provision that condition and request a fresh review. Do
|
|
164
|
+
not send unchanged implementation bytes to a code-fix round. Completion and
|
|
165
|
+
acceptance remain owned by their existing project process.
|
|
166
|
+
|
|
167
|
+
## Retain and release
|
|
168
|
+
|
|
169
|
+
Keep worker trees, leases, logs, and failed-state artifacts until their proposed
|
|
170
|
+
change has been accepted into the integration tree and the required integrated
|
|
171
|
+
review/completion path has accepted it. Preserve failed or blocked trees for
|
|
172
|
+
diagnosis and resumable work. Release a tree and its project-owned leases only
|
|
173
|
+
after that accepted integration, or after an explicit abandonment decision with
|
|
174
|
+
the diagnostic state retained elsewhere.
|