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.
Files changed (109) hide show
  1. package/README.md +148 -140
  2. package/dist/cli.js +1593 -373
  3. package/dist/cli.js.map +1 -1
  4. package/dist/joycraft-release.json +1 -1
  5. package/package.json +9 -3
  6. package/payload/.agents/skills/joycraft-context/SKILL.md +36 -0
  7. package/payload/.agents/skills/joycraft-decompose/SKILL.md +68 -0
  8. package/payload/.agents/skills/joycraft-entry/SKILL.md +109 -0
  9. package/payload/.agents/skills/joycraft-implement/SKILL.md +118 -0
  10. package/payload/.agents/skills/joycraft-retro/SKILL.md +54 -0
  11. package/payload/.agents/skills/joycraft-retro/agents/openai.yaml +5 -0
  12. package/payload/.agents/skills/joycraft-session-end/SKILL.md +82 -0
  13. package/payload/.agents/skills/joycraft-testing/SKILL.md +60 -0
  14. package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +59 -0
  15. package/payload/.agents/skills/joycraft-ui-slice/scripts/serve.mjs +97 -0
  16. package/payload/.agents/skills/joycraft-verify/SKILL.md +103 -0
  17. package/payload/.claude/agents/joycraft-implementer.md +36 -0
  18. package/payload/.claude/agents/joycraft-reviewer.md +35 -0
  19. package/payload/.joycraft/assets/artifacts/kit.css +102 -0
  20. package/payload/.joycraft/assets/artifacts/kit.js +301 -0
  21. package/payload/.joycraft/assets/artifacts/transports.js +236 -0
  22. package/payload/.joycraft/contracts/types.d.ts +185 -0
  23. package/payload/.joycraft/references/architecture.md +90 -0
  24. package/payload/.joycraft/references/archive.md +211 -0
  25. package/payload/.joycraft/references/artifacts.md +176 -0
  26. package/payload/.joycraft/references/completion.md +109 -0
  27. package/payload/.joycraft/references/context.md +85 -0
  28. package/payload/.joycraft/references/delivery.md +32 -0
  29. package/payload/.joycraft/references/dispatch.md +231 -0
  30. package/payload/.joycraft/references/recurring-failures.md +33 -0
  31. package/payload/.joycraft/references/retro.md +94 -0
  32. package/payload/.joycraft/references/setup.md +295 -0
  33. package/payload/.joycraft/references/testing.md +120 -0
  34. package/payload/.joycraft/references/update.md +44 -0
  35. package/payload/.joycraft/references/workflow.md +113 -0
  36. package/payload/.joycraft/references/worktrees.md +174 -0
  37. package/payload/.joycraft/runtime/archive.mjs +463 -0
  38. package/payload/.joycraft/runtime/artifacts/cli.mjs +61 -0
  39. package/payload/.joycraft/runtime/artifacts/decisions.mjs +214 -0
  40. package/payload/.joycraft/runtime/artifacts/model.mjs +161 -0
  41. package/payload/.joycraft/runtime/artifacts/preferences.mjs +127 -0
  42. package/payload/.joycraft/runtime/artifacts/render.mjs +21 -0
  43. package/payload/.joycraft/runtime/artifacts/server.mjs +40 -0
  44. package/payload/.joycraft/runtime/completion.mjs +300 -0
  45. package/payload/.joycraft/runtime/context/cli.mjs +75 -0
  46. package/payload/.joycraft/runtime/context/index.mjs +29 -0
  47. package/payload/.joycraft/runtime/context/search.mjs +149 -0
  48. package/payload/.joycraft/runtime/coordinator.mjs +169 -0
  49. package/payload/.joycraft/runtime/delivery.mjs +142 -0
  50. package/payload/.joycraft/runtime/dispatch-preflight.mjs +535 -0
  51. package/payload/.joycraft/runtime/dispatch-start.mjs +106 -0
  52. package/payload/.joycraft/runtime/evidence.mjs +137 -0
  53. package/payload/.joycraft/runtime/identity.mjs +486 -0
  54. package/payload/.joycraft/runtime/kickoff.mjs +174 -0
  55. package/payload/.joycraft/runtime/redact.mjs +9 -0
  56. package/payload/.joycraft/runtime/retro.mjs +151 -0
  57. package/payload/.joycraft/runtime/review-tools.json +34 -0
  58. package/payload/.joycraft/runtime/review-tools.mjs +331 -0
  59. package/payload/.joycraft/runtime/scope.mjs +129 -0
  60. package/payload/.joycraft/runtime/status.mjs +96 -0
  61. package/payload/.joycraft/runtime/update-check.mjs +142 -0
  62. package/payload/.joycraft/runtime/worktrees.mjs +201 -0
  63. package/payload/.joycraft/templates/README.md +7 -0
  64. package/payload/.joycraft/templates/artifact.json +33 -0
  65. package/payload/.joycraft/templates/brief.md +35 -0
  66. package/payload/.joycraft/templates/decisions.md +13 -0
  67. package/payload/.joycraft/templates/project-context.md +36 -0
  68. package/payload/.joycraft/templates/queue.json +27 -0
  69. package/payload/.joycraft/templates/spec.md +39 -0
  70. package/payload/.joycraft/templates/ui-slice.html +71 -0
  71. package/payload/PIN +77 -0
  72. package/payload/scripts/export.mjs +301 -0
  73. package/payload/scripts/hook-paths.mjs +35 -0
  74. package/payload/scripts/legacy-hooks.mjs +128 -0
  75. package/payload/scripts/legacy-inventory.json +117 -0
  76. package/dist/chunk-35RQLGKM.js +0 -2167
  77. package/dist/chunk-35RQLGKM.js.map +0 -1
  78. package/dist/chunk-7BPB2IKY.js +0 -255
  79. package/dist/chunk-7BPB2IKY.js.map +0 -1
  80. package/dist/chunk-B73DPYYC.js +0 -377
  81. package/dist/chunk-B73DPYYC.js.map +0 -1
  82. package/dist/chunk-K4AI6FKB.js +0 -417
  83. package/dist/chunk-K4AI6FKB.js.map +0 -1
  84. package/dist/chunk-KKDKC4FM.js +0 -115
  85. package/dist/chunk-KKDKC4FM.js.map +0 -1
  86. package/dist/chunk-OMFGDJW4.js +0 -97
  87. package/dist/chunk-OMFGDJW4.js.map +0 -1
  88. package/dist/chunk-YLWBDXF4.js +0 -3999
  89. package/dist/chunk-YLWBDXF4.js.map +0 -1
  90. package/dist/chunk-Z5JFEGWG.js +0 -563
  91. package/dist/chunk-Z5JFEGWG.js.map +0 -1
  92. package/dist/init-O2QC5X57.js +0 -60
  93. package/dist/init-O2QC5X57.js.map +0 -1
  94. package/dist/init-autofix-2DMBO4QN.js +0 -122
  95. package/dist/init-autofix-2DMBO4QN.js.map +0 -1
  96. package/dist/install-manifest-EQHT4474.js +0 -37
  97. package/dist/install-manifest-EQHT4474.js.map +0 -1
  98. package/dist/release-artifact-4TL5L2ZY.js +0 -14
  99. package/dist/release-artifact-4TL5L2ZY.js.map +0 -1
  100. package/dist/release-resolver-P2H46QTU.js +0 -293
  101. package/dist/release-resolver-P2H46QTU.js.map +0 -1
  102. package/dist/telemetry-store-IBO5GRTA.js +0 -14
  103. package/dist/telemetry-store-IBO5GRTA.js.map +0 -1
  104. package/dist/update-LYHS4FBH.js +0 -21
  105. package/dist/update-LYHS4FBH.js.map +0 -1
  106. package/dist/update-check-YT765NE7.js +0 -36
  107. package/dist/update-check-YT765NE7.js.map +0 -1
  108. package/dist/upgrade-GMP6JQ52.js +0 -28
  109. 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.