joycraft 0.7.17 → 1.0.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.
Files changed (106) hide show
  1. package/README.md +137 -156
  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 +103 -0
  9. package/payload/.agents/skills/joycraft-implement/SKILL.md +106 -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 +78 -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 +31 -0
  18. package/payload/.claude/agents/joycraft-reviewer.md +30 -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 +80 -0
  28. package/payload/.joycraft/references/delivery.md +32 -0
  29. package/payload/.joycraft/references/dispatch.md +226 -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 +279 -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 +148 -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/delivery.mjs +142 -0
  49. package/payload/.joycraft/runtime/dispatch-preflight.mjs +535 -0
  50. package/payload/.joycraft/runtime/dispatch-start.mjs +98 -0
  51. package/payload/.joycraft/runtime/evidence.mjs +137 -0
  52. package/payload/.joycraft/runtime/identity.mjs +486 -0
  53. package/payload/.joycraft/runtime/kickoff.mjs +174 -0
  54. package/payload/.joycraft/runtime/redact.mjs +9 -0
  55. package/payload/.joycraft/runtime/retro.mjs +151 -0
  56. package/payload/.joycraft/runtime/review-tools.json +34 -0
  57. package/payload/.joycraft/runtime/review-tools.mjs +331 -0
  58. package/payload/.joycraft/runtime/scope.mjs +129 -0
  59. package/payload/.joycraft/runtime/update-check.mjs +142 -0
  60. package/payload/.joycraft/templates/README.md +7 -0
  61. package/payload/.joycraft/templates/artifact.json +33 -0
  62. package/payload/.joycraft/templates/brief.md +35 -0
  63. package/payload/.joycraft/templates/decisions.md +13 -0
  64. package/payload/.joycraft/templates/project-context.md +36 -0
  65. package/payload/.joycraft/templates/queue.json +27 -0
  66. package/payload/.joycraft/templates/spec.md +39 -0
  67. package/payload/.joycraft/templates/ui-slice.html +71 -0
  68. package/payload/PIN +74 -0
  69. package/payload/scripts/export.mjs +301 -0
  70. package/payload/scripts/hook-paths.mjs +35 -0
  71. package/payload/scripts/legacy-hooks.mjs +128 -0
  72. package/payload/scripts/legacy-inventory.json +117 -0
  73. package/dist/chunk-35RQLGKM.js +0 -2167
  74. package/dist/chunk-35RQLGKM.js.map +0 -1
  75. package/dist/chunk-7BPB2IKY.js +0 -255
  76. package/dist/chunk-7BPB2IKY.js.map +0 -1
  77. package/dist/chunk-B73DPYYC.js +0 -377
  78. package/dist/chunk-B73DPYYC.js.map +0 -1
  79. package/dist/chunk-K4AI6FKB.js +0 -417
  80. package/dist/chunk-K4AI6FKB.js.map +0 -1
  81. package/dist/chunk-KKDKC4FM.js +0 -115
  82. package/dist/chunk-KKDKC4FM.js.map +0 -1
  83. package/dist/chunk-OMFGDJW4.js +0 -97
  84. package/dist/chunk-OMFGDJW4.js.map +0 -1
  85. package/dist/chunk-YLWBDXF4.js +0 -3999
  86. package/dist/chunk-YLWBDXF4.js.map +0 -1
  87. package/dist/chunk-Z5JFEGWG.js +0 -563
  88. package/dist/chunk-Z5JFEGWG.js.map +0 -1
  89. package/dist/init-O2QC5X57.js +0 -60
  90. package/dist/init-O2QC5X57.js.map +0 -1
  91. package/dist/init-autofix-2DMBO4QN.js +0 -122
  92. package/dist/init-autofix-2DMBO4QN.js.map +0 -1
  93. package/dist/install-manifest-EQHT4474.js +0 -37
  94. package/dist/install-manifest-EQHT4474.js.map +0 -1
  95. package/dist/release-artifact-4TL5L2ZY.js +0 -14
  96. package/dist/release-artifact-4TL5L2ZY.js.map +0 -1
  97. package/dist/release-resolver-P2H46QTU.js +0 -293
  98. package/dist/release-resolver-P2H46QTU.js.map +0 -1
  99. package/dist/telemetry-store-IBO5GRTA.js +0 -14
  100. package/dist/telemetry-store-IBO5GRTA.js.map +0 -1
  101. package/dist/update-LYHS4FBH.js +0 -21
  102. package/dist/update-LYHS4FBH.js.map +0 -1
  103. package/dist/update-check-YT765NE7.js +0 -36
  104. package/dist/update-check-YT765NE7.js.map +0 -1
  105. package/dist/upgrade-GMP6JQ52.js +0 -28
  106. 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,148 @@
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
+ ## Workspace input and project setup
49
+
50
+ Dispatch accepts an optional runtime workspace input:
51
+
52
+ ```js
53
+ { coordinatorRoot, parallel?: boolean, access: 'mutating' | 'read-only', baseRevision?: '<full-commit-SHA>' }
54
+ ```
55
+
56
+ For a known parallel mutator, `access` is `mutating` and the runtime derives and
57
+ attests real paths, Git topology, and the actual `workerRoot` in the packet. A
58
+ read-only reviewer may use the coordinator root while its inputs remain stable,
59
+ and write only its declared report/receipt outputs outside those inputs. It must
60
+ not write governing inputs or run cache-mutating runtime work there. The host
61
+ must not claim a planned path as the actual root.
62
+
63
+ Record project-specific bootstrap, ignored-file, disk, and resource requirements
64
+ in `docs/context/worktrees.md` when that is the project's context home, or in
65
+ the existing context-map destination. Do not require a new record when no such
66
+ facts are needed. The worker's first action after its tree exists is to run the
67
+ documented bootstrap before edits, stateful runtime work, or packet preparation.
68
+ If the project lockfile changed since a tree was bootstrapped, complete its
69
+ documented dependency bootstrap again before its runtime or data commands. A
70
+ project-owned data lease remains serial across every tree when its project
71
+ defines one.
72
+
73
+ For initial mutable dispatch, supply the captured commit as `baseRevision`
74
+ (`prepare --base-revision <full-SHA>`). Preflight checks the actual Git root and
75
+ requires its `HEAD` to equal that commit, catching a tree created at a stale
76
+ base. Re-capture deliberately after integration instead of reusing an old
77
+ startup expectation. Omitting this optional field retains legacy topology-only
78
+ attestation; it does not prove the intended starting revision.
79
+
80
+ ## Create and dispatch
81
+
82
+ Create each worker tree from the coordinator's captured base revision before
83
+ work starts. Do not copy untracked caches, credentials, or mutable state from
84
+ another worker. If bootstrap fails, preserve the tree and its failure output for
85
+ diagnosis; do not reuse it for another worker.
86
+
87
+ With [Claude Code worktrees](https://code.claude.com/docs/en/worktrees), use a
88
+ native agent's `isolation: "worktree"` capability when it is actually available,
89
+ or a custom-agent frontmatter worktree isolation setting. Claude's default
90
+ subagent base is the default branch, so select the captured current revision with
91
+ `worktree.baseRef: "head"` or an explicit manual ref and verify it. A native
92
+ auto-created path is unknown until the child launches: the child bootstraps, then
93
+ prepares or checks its packet from its real root before mutation. The coordinator
94
+ must not prepare a packet against an invented path.
95
+
96
+ `.worktreeinclude` is Claude-native only and applies to matching Git-ignored
97
+ files. A `WorktreeCreate` hook replaces creation and disables that automatic
98
+ include behavior. `CLAUDE_PROJECT_DIR` remains the original project directory;
99
+ the hook event's `cwd` is the active worktree. See the [Claude worktree
100
+ documentation](https://code.claude.com/docs/en/worktrees) and its [hook path
101
+ guidance](https://code.claude.com/docs/en/hooks#reference-scripts-by-path).
102
+
103
+ On hosts without that native capability, create an equivalent manual Git linked
104
+ worktree at an explicit, verified ref. Build each packet from its actual root:
105
+ `workerRoot`, manifest path, source paths, hook binding context, commands,
106
+ receipts, and report paths must resolve there. A coordinator may not substitute
107
+ the shared checkout merely because its sources look equivalent.
108
+
109
+ ## Integrate and verify
110
+
111
+ When an implementation worker finishes, the coordinator integrates its proposed
112
+ bytes into the integration tree using the project's normal Git workflow and
113
+ resolves any conflicts there. Run integration checks and prepare review from the
114
+ final integrated bytes. A worker-tree test result is useful evidence, but it
115
+ does not replace checks or review of the integrated result. Do not rerun a broad
116
+ suite merely because a worker tree exists; reserve broad validation for the
117
+ final integrated code when it is needed.
118
+
119
+ A worktree does not establish an independent reviewer context or current review
120
+ evidence. Dispatch a reviewer through the existing separate-context policy, and
121
+ freeze its reviewed inputs while it observes them. A stable source-read-only
122
+ reviewer can use the integrated tree and write its declared reports/receipts
123
+ outside frozen inputs. A reviewer that needs cache-mutating runtime checks must
124
+ use an independent mutable runtime-state arrangement.
125
+
126
+ ## Stop, restart, and environment blocks
127
+
128
+ A stopped run needs an ownership-aware teardown report: identify the run,
129
+ captured refs, known trees, leases, locks, and runtime processes; state which
130
+ were released, retained, or could not be identified. Do not automatically abort
131
+ an unknown active merge, remove an unknown tree or lock, stop an unknown
132
+ process, or force local state to equal a remote branch. Preserve ambiguous
133
+ state for diagnosis and hand it to its recorded owner. Restart only from the
134
+ durable journal and an updated plan, with a new coordinator ownership record.
135
+
136
+ When a review is unverified solely because of an identified environment
137
+ condition, repair or provision that condition and request a fresh review. Do
138
+ not send unchanged implementation bytes to a code-fix round. Completion and
139
+ acceptance remain owned by their existing project process.
140
+
141
+ ## Retain and release
142
+
143
+ Keep worker trees, leases, logs, and failed-state artifacts until their proposed
144
+ change has been accepted into the integration tree and the required integrated
145
+ review/completion path has accepted it. Preserve failed or blocked trees for
146
+ diagnosis and resumable work. Release a tree and its project-owned leases only
147
+ after that accepted integration, or after an explicit abandonment decision with
148
+ the diagnostic state retained elsewhere.