joycraft 0.7.16 → 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 (109) 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/index.d.ts +4 -0
  5. package/dist/index.js +3 -0
  6. package/dist/index.js.map +1 -1
  7. package/dist/joycraft-release.json +1 -1
  8. package/package.json +9 -3
  9. package/payload/.agents/skills/joycraft-context/SKILL.md +36 -0
  10. package/payload/.agents/skills/joycraft-decompose/SKILL.md +68 -0
  11. package/payload/.agents/skills/joycraft-entry/SKILL.md +103 -0
  12. package/payload/.agents/skills/joycraft-implement/SKILL.md +106 -0
  13. package/payload/.agents/skills/joycraft-retro/SKILL.md +54 -0
  14. package/payload/.agents/skills/joycraft-retro/agents/openai.yaml +5 -0
  15. package/payload/.agents/skills/joycraft-session-end/SKILL.md +78 -0
  16. package/payload/.agents/skills/joycraft-testing/SKILL.md +60 -0
  17. package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +59 -0
  18. package/payload/.agents/skills/joycraft-ui-slice/scripts/serve.mjs +97 -0
  19. package/payload/.agents/skills/joycraft-verify/SKILL.md +103 -0
  20. package/payload/.claude/agents/joycraft-implementer.md +31 -0
  21. package/payload/.claude/agents/joycraft-reviewer.md +30 -0
  22. package/payload/.joycraft/assets/artifacts/kit.css +102 -0
  23. package/payload/.joycraft/assets/artifacts/kit.js +301 -0
  24. package/payload/.joycraft/assets/artifacts/transports.js +236 -0
  25. package/payload/.joycraft/contracts/types.d.ts +185 -0
  26. package/payload/.joycraft/references/architecture.md +90 -0
  27. package/payload/.joycraft/references/archive.md +211 -0
  28. package/payload/.joycraft/references/artifacts.md +176 -0
  29. package/payload/.joycraft/references/completion.md +109 -0
  30. package/payload/.joycraft/references/context.md +80 -0
  31. package/payload/.joycraft/references/delivery.md +32 -0
  32. package/payload/.joycraft/references/dispatch.md +226 -0
  33. package/payload/.joycraft/references/recurring-failures.md +33 -0
  34. package/payload/.joycraft/references/retro.md +94 -0
  35. package/payload/.joycraft/references/setup.md +279 -0
  36. package/payload/.joycraft/references/testing.md +120 -0
  37. package/payload/.joycraft/references/update.md +44 -0
  38. package/payload/.joycraft/references/workflow.md +113 -0
  39. package/payload/.joycraft/references/worktrees.md +148 -0
  40. package/payload/.joycraft/runtime/archive.mjs +463 -0
  41. package/payload/.joycraft/runtime/artifacts/cli.mjs +61 -0
  42. package/payload/.joycraft/runtime/artifacts/decisions.mjs +214 -0
  43. package/payload/.joycraft/runtime/artifacts/model.mjs +161 -0
  44. package/payload/.joycraft/runtime/artifacts/preferences.mjs +127 -0
  45. package/payload/.joycraft/runtime/artifacts/render.mjs +21 -0
  46. package/payload/.joycraft/runtime/artifacts/server.mjs +40 -0
  47. package/payload/.joycraft/runtime/completion.mjs +300 -0
  48. package/payload/.joycraft/runtime/context/cli.mjs +75 -0
  49. package/payload/.joycraft/runtime/context/index.mjs +29 -0
  50. package/payload/.joycraft/runtime/context/search.mjs +149 -0
  51. package/payload/.joycraft/runtime/delivery.mjs +142 -0
  52. package/payload/.joycraft/runtime/dispatch-preflight.mjs +535 -0
  53. package/payload/.joycraft/runtime/dispatch-start.mjs +98 -0
  54. package/payload/.joycraft/runtime/evidence.mjs +137 -0
  55. package/payload/.joycraft/runtime/identity.mjs +486 -0
  56. package/payload/.joycraft/runtime/kickoff.mjs +174 -0
  57. package/payload/.joycraft/runtime/redact.mjs +9 -0
  58. package/payload/.joycraft/runtime/retro.mjs +151 -0
  59. package/payload/.joycraft/runtime/review-tools.json +34 -0
  60. package/payload/.joycraft/runtime/review-tools.mjs +331 -0
  61. package/payload/.joycraft/runtime/scope.mjs +129 -0
  62. package/payload/.joycraft/runtime/update-check.mjs +142 -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 +74 -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-GTP7Z52K.js +0 -3942
  83. package/dist/chunk-GTP7Z52K.js.map +0 -1
  84. package/dist/chunk-K4AI6FKB.js +0 -417
  85. package/dist/chunk-K4AI6FKB.js.map +0 -1
  86. package/dist/chunk-KKDKC4FM.js +0 -115
  87. package/dist/chunk-KKDKC4FM.js.map +0 -1
  88. package/dist/chunk-OMFGDJW4.js +0 -97
  89. package/dist/chunk-OMFGDJW4.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-MUB5CC6L.js +0 -60
  93. package/dist/init-MUB5CC6L.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-LFLQTPUA.js +0 -19
  105. package/dist/update-LFLQTPUA.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-L5WERK4X.js +0 -28
  109. package/dist/upgrade-L5WERK4X.js.map +0 -1
@@ -0,0 +1,211 @@
1
+ # Session-end feature archive
2
+
3
+ `archive.mjs` preserves a completed feature as historical regression evidence.
4
+ It runs only from a host-asserted `session-end` boundary. A queue transition,
5
+ review, hook event, or ordinary verification must never invoke it.
6
+
7
+ Prepare a project-relative attestation file:
8
+
9
+ ```json
10
+ {
11
+ "schemaVersion": 1,
12
+ "phase": "session-end",
13
+ "host": {
14
+ "sessionId": "host-session-id",
15
+ "quiescent": true,
16
+ "activeWorkers": [],
17
+ "dependentWork": []
18
+ },
19
+ "durableContext": {
20
+ "carried": true,
21
+ "references": ["docs/context/decision-log.md"]
22
+ }
23
+ }
24
+ ```
25
+
26
+ `quiescent` attests that no active worker and no unfinished work requiring the
27
+ feature's live paths remains. It does not ask for a new human permission. The
28
+ current Markdown context references must already exist outside `docs/features/` and
29
+ `docs/archive/`; they demonstrate that constraints worth retaining were carried
30
+ into current documentation. Reuse the project's existing home, including
31
+ `AGENTS.md` or a custom context map. This attestation is an operational statement, not
32
+ another decision or approval authority.
33
+
34
+ The preview validates the complete queue before any write: the canonical queue
35
+ must be the only queue anywhere in the feature tree, all specs must be
36
+ `done`, and each spec must have exactly one of an accepted PASS report or an
37
+ explicit `ownerAcceptance` receipt. A normal accepted report must retain its
38
+ PASS evidence. An owner-acceptance record is historical exception metadata:
39
+ it binds the queue/spec/subject identity to a hashed independent review whose
40
+ verdict remains `FAIL` or `UNVERIFIED`, carries nonempty limitations, and is
41
+ not evidence that the review passed. The runtime validates the decision, review,
42
+ subject bindings, receipts and historical requirement invariants, then preserves
43
+ the decision, review, verdict and limitations in the replay manifest. Its
44
+ shape cannot authenticate that a human issued it. Each report's independent-review shape must hold,
45
+ each report must describe its own archived queue/spec and original requirements,
46
+ and every referenced receipt must still have its recorded bytes. A pending
47
+ completion journal, a malformed/corrupt/FAIL report, unfinished work, missing
48
+ durable context, symlinks, traversal, or archive collision stops the operation.
49
+
50
+ The runtime deliberately does not rerun historic suites or compare their code
51
+ input hashes with current live code. Later work may supersede those hashes. For
52
+ a v1-bound report it still checks the selected queue/dependencies and selected
53
+ governing requirement or decision records, while independent queue records and
54
+ unselected decisions may change. Older reports retain their original whole-file
55
+ archive checks. The archive records that this evidence is historical and does
56
+ not renew current acceptance.
57
+
58
+ When a checked requirement has changed since acceptance, the helper can recover
59
+ its accepted version from Git. Run at the Git worktree root. The current file
60
+ must have no staged or unstaged changes and its raw bytes must match HEAD. The
61
+ newest matching path commit reachable from HEAD must reproduce the accepted
62
+ hash using the original `none` or `requirement-scope` normalization. A missing
63
+ selector in a newer version is a mismatch, not permission to skip the check.
64
+ The preview's `requirementHistory` lists the original path, normalization/scope,
65
+ accepted hash, accepted commit, restored raw hash and subsequent path commits.
66
+ The queue and every declared spec remain strict by default; the explicit
67
+ reconciliation path below is the archive-only exception. Reports and receipts
68
+ must always retain their recorded bytes. No committed match means no archive.
69
+
70
+ For the feature's own brief, also write
71
+ `docs/features/<slug>/brief-amendments.json` from actual recorded owner decisions:
72
+
73
+ ```json
74
+ {
75
+ "schemaVersion": 1,
76
+ "kind": "joycraft-brief-amendments",
77
+ "brief": "docs/features/<slug>/brief.md",
78
+ "amendments": [
79
+ {
80
+ "commit": "<full Git commit ID>",
81
+ "fromSha256": "<raw brief hash at commit^>",
82
+ "toSha256": "<raw brief hash at commit>",
83
+ "decisions": ["D18"],
84
+ "summary": "Describe the owner-directed change."
85
+ }
86
+ ]
87
+ }
88
+ ```
89
+
90
+ Every subsequent brief path commit needs exactly one entry, including commits
91
+ that record the questions before their answers. Git's first parent (`commit^`)
92
+ defines the before hash, including for merges. Each named decision must occur
93
+ exactly once in the current brief's frontmatter JSON `decisions` array, have
94
+ status `clarified` or `assigned`, and a nonempty answer. Do not manufacture an
95
+ answer to unblock archival. The preview includes the validated amendments.
96
+ These records explain historical changes; they do not prove a fresh review of
97
+ the amended feature. Archival therefore does not require one report matching
98
+ today's brief: a single report could cover only one scope and would not renew
99
+ acceptance for the whole feature anyway.
100
+
101
+ Apply restores each accepted raw version under
102
+ `evidence/requirements/<proof-hash>/<original-path>` in the archive. Different
103
+ accepted versions or scopes remain distinct. Replay entries use
104
+ `operation: "restored-from-git"` and retain the proof in `requirement`; subsequent
105
+ runs verify both the stored raw bytes and their accepted projection without
106
+ needing live Git history. The current brief and its amendment ledger move with
107
+ the feature, alongside the separately restored older brief versions.
108
+
109
+ ## Archive reconciliation for a changed acceptance record
110
+
111
+ If a completed feature is blocked because a queue entry or spec was edited after
112
+ acceptance, investigate the exact change before proposing a new review. Several
113
+ valid historical reports can bind different versions of one queue. Rolling the
114
+ queue back may invalidate later reports; rewriting report hashes or accepting an
115
+ already-done spec again is not an archival repair.
116
+
117
+ Under an owner-authorized resolution, use this separate archive-only override:
118
+
119
+ 1. Identify each affected report/input and the commit that introduced the drift.
120
+ Record the cause and settle the intended current brief/spec description in its
121
+ owning home. A real unresolved product change stays in active work; do not
122
+ claim that archival verifies it. Avoid editing done queue entries merely to
123
+ follow renamed files.
124
+ 2. Preserve all original reports and receipts. Commit current queue/spec files.
125
+ Their accepted normalized bytes must also exist in reachable Git history.
126
+ Brief changes still require the answered decision amendment ledger above.
127
+ 3. Write `docs/features/<slug>/archive-reconciliation.json` with the existing
128
+ owner instruction, the chosen resolution, explicit limitations, and one entry
129
+ for each changed report/input pair. An authorization already present in the
130
+ task is enough; do not ask again just to record it. Never invent an instruction.
131
+ 4. Preview with `--reconciliation <record-path>`, inspect the restored versions
132
+ and the recorded resolution, then apply at the ordinary quiescent session-end
133
+ boundary. The same flag is required for the first apply.
134
+
135
+ ```json
136
+ {
137
+ "schemaVersion": 1,
138
+ "kind": "joycraft-archive-reconciliation",
139
+ "feature": "<slug>",
140
+ "createdAt": "2026-10-22T00:00:00Z",
141
+ "instruction": "Record the owner's actual archive-reconciliation authorization.",
142
+ "reason": "A later rename rewrote a done spec's queue entry.",
143
+ "resolution": "Keep today's description and preserve each accepted queue version.",
144
+ "limitations": ["Historical archival only; no renewed acceptance of current requirements."],
145
+ "entries": [
146
+ {
147
+ "report": {"path": "<accepted report path>", "sha256": "<report raw SHA-256>"},
148
+ "path": "docs/features/<slug>/specs/.joycraft-spec-queue.json",
149
+ "normalization": "queue-scope",
150
+ "acceptedSha256": "<queue input hash from that report>",
151
+ "currentSha256": "<current raw queue-file hash>",
152
+ "reason": "Name the introducing commit and the specific edit.",
153
+ "resolution": "Explain how the discrepancy is resolved for archival."
154
+ }
155
+ ]
156
+ }
157
+ ```
158
+
159
+ `queue-scope`, legacy `queue-status`, and `spec-status` cover changed acceptance
160
+ records. For an ordinary `none` or `requirement-scope` requirement whose accepted
161
+ version survives outside HEAD history (for example after a squash merge), an
162
+ entry may also name `acceptedCommit` as a full Git commit ID. The blob at that
163
+ exact commit must reproduce the original accepted hash; the helper never waives
164
+ missing bytes. The current external requirement is copied into the archive too,
165
+ so the recorded current hash remains verifiable. `laterCommits` means the path
166
+ commits in the Git range `acceptedCommit..HEAD`; for a branched history this is
167
+ not a claim that all those commits were chronologically later. `acceptedSha256` is copied from the original report's input;
168
+ `currentSha256` pins raw current bytes, including acceptance metadata. One queue
169
+ edit may therefore need many entries, one for each report whose dependency
170
+ projection changed. Unchanged later reports need no entry. Duplicate, unused,
171
+ uncovered or stale entries fail closed. A ledger's presence alone never enables
172
+ the override, and its shape does not authenticate a human. The ledger itself may
173
+ be uncommitted: preview pins its raw hash, apply rechecks it, and archival retains
174
+ it byte-for-byte as part of the paper trail. Commit the resulting archive through
175
+ the normal project delivery process. A renamed own spec or changed report subject
176
+ path still fails; this override reconciles contents, not acceptance identities.
177
+
178
+ ```sh
179
+ node .joycraft/runtime/archive.mjs archive --feature <slug> --phase session-end --attestation <attestation.json> --reconciliation docs/features/<slug>/archive-reconciliation.json
180
+ # Inspect the preview; add --apply to perform the same reconciled plan.
181
+ ```
182
+
183
+ The helper checks each original review against its restored queue projection and
184
+ criteria, restores the exact accepted raw queue/spec bytes alongside the current
185
+ files, and includes the ledger and its hash in preview/replay. The manifest says
186
+ `historical.acceptanceRecordsReconciled: true` and still says
187
+ `currentAcceptanceRenewed: false`. Report it as **archived with reconciliation**,
188
+ including the limitations, rather than a new verification PASS. Replay verifies
189
+ the stored ledger, its connection to the restored evidence, raw hashes and
190
+ normalized hashes without requiring live Git history. The helper does not edit
191
+ briefs/specs/queues, statuses, report identities or review verdicts to make them
192
+ agree. Missing/corrupt receipts, invalid reviews, unfinished work, an active host
193
+ or a pending completion journal cannot be overridden.
194
+
195
+ The default command is read-only. `--apply` restages and rechecks all inputs,
196
+ then atomically moves `docs/features/<slug>` to
197
+ `docs/archive/<slug>/feature`. Code, tests, and shared receipts outside the
198
+ feature stay live. Reports and receipts outside the feature are copied under
199
+ the archive record's `evidence/` directory. `archive-replay.json` maps each
200
+ original path to its moved, copied or restored byte-identical record. Historical links in
201
+ the moved files retain their original text; consumers must treat them as history.
202
+
203
+ The staging directory receives `archive-recovery.json` before any copy or move,
204
+ and the marker remains in the final archive as immutable move provenance. If an
205
+ interruption prevents the final rename, the runtime tries to restore the source
206
+ directory. If that restore cannot prove the source is back and staging no longer
207
+ holds the feature, it retains the staged directory and its recovery manifest for
208
+ manual recovery. A collision or changed byte fails without accepting new
209
+ completion. A repeat is idempotent only when the existing replay manifest names
210
+ the feature and every archived mapped byte still matches; otherwise it requires
211
+ manual reconciliation.
@@ -0,0 +1,176 @@
1
+ # Decision artifacts
2
+
3
+ Use an artifact for every question that asks the user to choose between
4
+ options: record the choices as brief decisions, then render them. Also use one
5
+ for an editorial comparison of existing screenshots or a review summary. Plain
6
+ chat is only for one quick yes/no or an open question with no options. It renders a selected view of the brief; the brief and queue remain
7
+ the source of truth. Do not use one for a routine native question, a product UI
8
+ slice whose real interaction must be explored, or a long questionnaire.
9
+
10
+ The renderer is deterministic. Agents author a short view-data file, such as
11
+ [`templates/artifact.json`](../templates/artifact.json), and link existing
12
+ brief decisions, comparison images, and review reports. They do not write
13
+ artifact CSS, JavaScript, or a second copy of the brief. Keep questions useful:
14
+ one material choice can be enough. Use the existing product UI slice for a
15
+ choice that depends on trying the actual product behavior.
16
+
17
+ ## Decisions and view data
18
+
19
+ A brief decision keeps its existing `id`, `status`, `question`, `answer`,
20
+ `options`, and `affected` fields. Artifact views also support an optional
21
+ `description` on an option and `requiresNote: true` when that option needs a
22
+ short explanation. The canonical answer remains the declared option `value`,
23
+ including a `custom` value. Store the human's exact words separately as that
24
+ decision's note; never replace the canonical answer with free-form text.
25
+
26
+ The view data has this shape:
27
+
28
+ ```json
29
+ {
30
+ "schemaVersion": 1,
31
+ "artifactId": "feature-review",
32
+ "title": "Feature review",
33
+ "summary": "Optional context for the reviewer.",
34
+ "decisionIds": ["presentation"],
35
+ "comparisons": [{
36
+ "title": "Current and proposed",
37
+ "decisionId": "presentation",
38
+ "images": [{
39
+ "path": "docs/features/example/screens/current.png",
40
+ "label": "Current",
41
+ "alt": "Current collection screen",
42
+ "caption": "The existing compact list."
43
+ }]
44
+ }],
45
+ "reviews": [{
46
+ "path": "docs/features/example/specs/review-1.report.json",
47
+ "title": "Independent review"
48
+ }]
49
+ }
50
+ ```
51
+
52
+ All paths are exact, existing project-relative files. Image bytes are embedded
53
+ in the rendered artifact. A review card derives its declared verdict and labels
54
+ it as recorded and unvalidated; it neither supplies verification nor changes a
55
+ queue status. Small editorial assets are appropriate for decision context,
56
+ screenshot comparisons, and review summaries. Keep their content in the
57
+ referenced files rather than copying it into view data.
58
+
59
+ ## Theme
60
+
61
+ Artifacts support `light` and `dark` themes. For each render, the CLI `--theme`
62
+ choice wins over the view's optional `theme`, then `.joycraft/preferences.json` at
63
+ `artifacts.theme`; the fallback is `light`. Use `--theme` for one render without
64
+ changing the project preference. A request to use dark or light from now on is a
65
+ per-project preference, set with:
66
+
67
+ ```sh
68
+ node .joycraft/runtime/artifacts/cli.mjs theme --set dark
69
+ ```
70
+
71
+ That command preserves other project preferences and changes only
72
+ `artifacts.theme`.
73
+
74
+ ## Colors
75
+
76
+ A project can replace the kit's colors, for example with its design system. Read
77
+ the project's existing color tokens (CSS variables, Tailwind theme, design-token
78
+ files) or take the user's colors, and map them to the kit's names in a JSON file:
79
+
80
+ ```json
81
+ {
82
+ "light": { "accent": "#0b5d3b", "accent-hover": "#084a2f" },
83
+ "dark": { "accent": "#9fe0bf" }
84
+ }
85
+ ```
86
+
87
+ The names are `canvas`, `paper`, `surface`, `ink`, `muted`, `line`,
88
+ `control-line`, `accent`, `accent-hover`, `accent-text`, `accent-soft`, `focus`,
89
+ `error`, `error-bg`, `caution` and `input`. Values are `#rrggbb`. Set only the
90
+ colors you change; the rest keep the kit's values. Then record them:
91
+
92
+ ```sh
93
+ node .joycraft/runtime/artifacts/cli.mjs colors --set <colors.json>
94
+ node .joycraft/runtime/artifacts/cli.mjs colors --reset
95
+ ```
96
+
97
+ `--set` refuses a palette whose text or controls would be hard to read and names
98
+ each failing pair; adjust those colors and try again. `--reset` restores the kit
99
+ colors. Colors are cosmetic like the theme. Add one link to the existing context map for the preference
100
+ file when recording a durable preference, if it is not already linked; do not
101
+ copy the selected value into the map. Theme is cosmetic: it does not change
102
+ brief answers, source or view binding, or Claude answer storage.
103
+
104
+ The renderer binds the resulting model to `source.path`, the current brief
105
+ `source.revision`, and `source.viewRevision`. The view revision hashes the
106
+ theme-independent view data together with every selected image and review-report
107
+ byte. Local save and import check both revisions, so a changed screenshot,
108
+ report, or selected view requires a refresh alongside a changed brief. The
109
+ resulting model supplies
110
+ selected brief decisions as questions, embedded image `src` data, and derived
111
+ review results. Its response transport is separate from those canonical
112
+ decisions: responses are drafts until the local save succeeds or a previewed
113
+ import is explicitly applied. A runtime may identify its storage as brief,
114
+ Claude, or memory; only brief persistence changes repository state.
115
+
116
+ ## Render and save
117
+
118
+ The shared command accepts the brief and, optionally, a selected view:
119
+
120
+ ```sh
121
+ node .joycraft/runtime/artifacts/cli.mjs serve \
122
+ --brief docs/features/<slug>/brief.md \
123
+ [--view docs/features/<slug>/artifact.json] [--theme light|dark]
124
+
125
+ node .joycraft/runtime/artifacts/cli.mjs build \
126
+ --brief docs/features/<slug>/brief.md \
127
+ [--view docs/features/<slug>/artifact.json] \
128
+ --out .joycraft/local/artifacts/<slug>.html \
129
+ --mode claude|portable [--theme light|dark]
130
+ ```
131
+
132
+ `serve` saves an accepted local answer directly to the current brief. The UI
133
+ keeps per-question Save and Save all actions, shows saved state only after a
134
+ successful write, and allows optional notes where required. It validates the
135
+ source path and revision, decision IDs, and option values before saving.
136
+
137
+ `build` creates a self-contained HTML file suitable for a native Claude cloud
138
+ artifact (`--mode claude`) or a portable download (`--mode portable`). It does
139
+ not create, publish, share, or update a cloud artifact. It refuses to overwrite
140
+ an existing output, so choose a fresh filename for another build. Keep generated
141
+ files in the project-local artifact home; they are render outputs, not brief
142
+ authority.
143
+
144
+ For a detached artifact, export the responses and import them deliberately:
145
+
146
+ ```sh
147
+ node .joycraft/runtime/artifacts/cli.mjs import \
148
+ --brief docs/features/<slug>/brief.md \
149
+ [--view docs/features/<slug>/artifact.json] \
150
+ --responses responses.json
151
+
152
+ node .joycraft/runtime/artifacts/cli.mjs import \
153
+ --brief docs/features/<slug>/brief.md \
154
+ [--view docs/features/<slug>/artifact.json] \
155
+ --responses responses.json --apply
156
+ ```
157
+
158
+ The first command is a read-only preview. `--apply` is the explicit write. An
159
+ import needs host-observed human answers and verifies the current brief path,
160
+ revision, selected decision IDs, and declared option values before it persists
161
+ them. Preserve supplied notes verbatim. Bring cloud answers back through an
162
+ authorized host tool or exported JSON; do not invent a provider endpoint.
163
+
164
+ Native Claude's currently observed `window.claude.use('db')` bridge can store
165
+ scoped answer transport when that capability is present, but it is not a public
166
+ SDK contract and may change. Claude transport uses a separate document for each
167
+ decision, so answers to different questions do not overwrite each other. Two
168
+ writers for the same decision are last-write-wins in that transport; importing
169
+ still refuses to replace an already clarified canonical answer, except for an
170
+ exact replay. Capability absence, sign-out, or unsupported hosts must leave the
171
+ form usable with copy/download export and a visible memory-only state. Never
172
+ claim an answer is cloud-saved, repository-synced, or persisted until the
173
+ relevant observed write succeeds. Cloud storage never autosyncs the repository.
174
+
175
+ Reload the source before affected implementation. A saved answer informs work
176
+ only within the existing authorization and does not mark specifications done.
@@ -0,0 +1,109 @@
1
+ # Guarded completion
2
+
3
+ Use this reference when snapshotting a verification subject, submitting an independent review report, or responding to a completion failure.
4
+
5
+ ## Stable local interface
6
+
7
+ Run these commands from the consumer project root. Paths are project-relative.
8
+
9
+ ```sh
10
+ node .joycraft/runtime/completion.mjs scope --queue <queue-path> --spec <id>
11
+ node .joycraft/runtime/completion.mjs snapshot --queue <queue-path> --spec <id> --out <subject.json>
12
+ node .joycraft/runtime/completion.mjs finalize-review --queue <queue-path> --spec <id> --report <report.json>
13
+ node .joycraft/runtime/completion.mjs accept-owner --queue <queue-path> --spec <id> --decision <owner-acceptance.json>
14
+ node .joycraft/runtime/completion.mjs recover --queue <queue-path>
15
+ ```
16
+
17
+ `scope` checks a queue's declared change scope without writing a subject. `snapshot` does the same check first, then exclusively creates a new `--out` subject file without changing a status. It binds the implementation revision, queue/spec identity, criteria, and SHA-256 values for exact relevant inputs. The shared record shapes are defined in [.joycraft/contracts/types.d.ts](../contracts/types.d.ts). New subjects carry `binding.version: 1`: their queue projection contains the reviewed spec and its transitive dependencies, with completion metadata (`status`, `acceptedReport`, and `ownerAcceptance`) removed from those records. An unrelated queue record can change without staling that subject; a selected spec's other metadata and dependency edges remain bound. A spec binding preserves raw bytes except for its top-level `status:` value.
18
+
19
+ An optional `verification.changeScope` records an explicit full Git commit SHA in `baseRevision`; a branch name, `origin/main`, or inferred base is rejected. Changed verification inputs are captured from NUL-delimited Git status records, including staged, unstaged, rename, and deletion topology. Any changed path outside the verification inputs must be named exactly in `exclusions` with its reason. Store temporary packets and subjects in the project's ignored local-artifact home when it has one; otherwise add each exact untracked snapshot packet output to `exclusions`. `complete` filters only its exact report, receipt, owner-decision, and pending-journal paths while rechecking scope. A deliberate deletion needs a non-requirement verification input with `state: "absent"`; requirement inputs cannot be absent. A rename needs the new present input and the old non-requirement input declared absent.
20
+
21
+ A requirement input may optionally declare exact `scope.anchors` or `scope.decisionIds`. Anchors bind complete named heading subtrees together with their ancestor context and non-decision document context; decision IDs bind complete stable JSON decision records. They may be combined for a canonical brief whose frontmatter contains a `decisions:` JSON array. A criterion may name such a record as `frontmatter.decisions.<id>`; an explicit `decisionIds` selector must include that ID. Heading-only scopes keep all frontmatter decisions governing. Pure JSON decision records support `decisionIds` only, so unsupported JSON heading anchors fail instead of being ignored. Anchor selection supports ATX (`#`) headings outside fenced code blocks; setext and linked headings are not selectors. A required criterion anchor must be included by an anchored scope. Missing or ambiguous selections stop the snapshot. Omit `scope` to bind the entire requirement file. Queue and reviewed-spec inputs cannot be narrowed. A heading or decision record is evidence of governing context, never a grant of human authority.
22
+
23
+ Older reports without `subject.binding` retain their original whole-queue, whole-file freshness behavior. The helper does not relabel or migrate them. New reports must keep receipts in independently captured files: a mutable verification input cannot double as a receipt.
24
+
25
+ Use the original `implementationRevision` as provenance on a re-check while recomputing the bound current inputs. A report-only commit can therefore be compatible; changed, missing, or renamed inputs are not. The snapshot includes no permission to accept the work.
26
+
27
+ ## Independent report and guarded acceptance
28
+
29
+ The report must use the shared schema and bind its subject identity. It records the actual implementer/reviewer native identities, `independent: true` only when a separate reviewer context actually reviewed the work, scope review, flow evidence, receipts, limits, unresolved items, and a PASS/FAIL/UNVERIFIED verdict.
30
+
31
+ A native child can share its parent session. Supply `implementerActor` and `reviewer.actor` together, each with the observed `host`, `sessionId`, and the actual `agentId` when the host issued a child invocation ID. Preserve the matching legacy session fields. A root actor may omit `agentId`; a same-session child review needs its real distinct actor identity. Do not substitute a task name, worktree path, random UUID, or invented ID. Legacy reports without actor metadata still require distinct session IDs. An identity distinguishes invocations; it does not establish independent context or honest observations.
32
+
33
+ `finalize-review` (with `complete` retained as a compatibility alias) accepts only an `in-review` spec with a matching current subject, a PASS verdict, truthful independent-review attestation, reviewed scope, valid receipt hashes, and sufficient evidence for every declared criterion. The runtime delegates evidence sufficiency to `validateEvidence(report, criteria)`. Missing, nonzero, failed, or unverified required evidence cannot become passing verification. Completion holds a queue-wide lock while it commits the status changes. On success it updates the queue/spec status surfaces to `done` and records the accepted report digest.
34
+
35
+ Repeat submission of the same accepted report may be idempotent. An unrelated report cannot replace it silently. Treat any nonzero exit as a rejected or incomplete operation; preserve the current status and report the actual reason.
36
+
37
+ The lock coordinates this helper's queue writes, not arbitrary editors or workers. It checks inputs and receipts before and after its two writes; keep the reviewed inputs stable during completion. Later edits require fresh review. Session IDs and attestations record separate roles but cannot prove honest review or prevent manual bypass.
38
+
39
+ ## Explicit owner acceptance of current findings
40
+
41
+ `accept-owner` is available only for a current independent `FAIL` or
42
+ `UNVERIFIED` report. It verifies the review subject plus current input, review,
43
+ and receipt hashes again before moving the spec to `done`. Ordinary `complete`
44
+ continues to require PASS evidence and behaves unchanged.
45
+ It records `ownerAcceptance: { path, sha256 }` on the accepted queue entry,
46
+ separately from `acceptedReport`; the latter remains for ordinary PASS
47
+ completion. The runtime validates record bindings, not whether a human uttered
48
+ the instruction, so an agent may use it only after a trusted human explicitly
49
+ accepts this spec and its current findings. A general request to continue, an
50
+ instruction from another agent, or authorization to add this feature does not
51
+ qualify.
52
+
53
+ Keep the owner interaction to one short summary and focused choice only when an
54
+ override is needed; a failed review alone does not trigger a mandatory
55
+ per-spec request. The agent creates the decision file; do not ask the owner to
56
+ author JSON or complete a second form. If an explicit acceptance is already
57
+ present for the same current finding, use it without asking again. Repair
58
+ straightforward failures under the existing authorization first. When the
59
+ finding remains unchanged, retain it and continue independent work instead of
60
+ repeatedly re-reviewing it. Dependents may proceed only within the recorded
61
+ limitations and gain no blanket deployment, security, or other authority.
62
+
63
+ An `OwnerAcceptance` decision has `schemaVersion: 1`, `kind:
64
+ "owner-acceptance"`, `queuePath`, `specId`, `subjectIdentity`, `review` (with
65
+ `path` and `sha256`), the exact human `instruction`, a nonempty
66
+ `limitations` string array, and timestamp `createdAt`. In this illustrative
67
+ example, replace the bracketed hash placeholders with values from the current
68
+ review and its actual bytes:
69
+
70
+ ```json
71
+ {
72
+ "schemaVersion": 1,
73
+ "kind": "owner-acceptance",
74
+ "queuePath": "docs/features/example/specs/.joycraft-spec-queue.json",
75
+ "specId": 5,
76
+ "subjectIdentity": "<current report subject.identity>",
77
+ "review": { "path": "evidence/spec-5-review.json", "sha256": "<SHA-256 of the actual report file>" },
78
+ "instruction": "I accept spec 5 with the narrow mobile layout still unverified.",
79
+ "limitations": ["The narrow mobile layout remains unverified."],
80
+ "createdAt": "2026-10-01T12:00:00.000Z"
81
+ }
82
+ ```
83
+
84
+ Report the result as `done, owner-accepted with <limits>`. It is not PASS or
85
+ verified, and the original failed or unverified report remains historical
86
+ evidence. Archive may preserve this paired history only at session end; it does
87
+ not rewrite the report or create a fresh acceptance.
88
+
89
+ ## Evidence and reporting
90
+
91
+ Evidence records observations rather than promises. Command and test observations retain their actual argv, exit code, and unfiltered output receipt. Source review supports structural claims only. A required visual claim needs an inspected render, route, state, viewport, interactions, and observed outcomes. Record unavailable work as `UNVERIFIED`, failures as `FAIL`, and limits explicitly.
92
+
93
+ Report the command result, reviewer identity, receipt paths, actual observations, and limitations. A green suite or an implementation commit alone is not accepted completion.
94
+
95
+ ## Interrupted writes and recovery
96
+
97
+ The helper uses `.joycraft-completion.pending.json` in the queue directory as a bounded local journal for the queue status, spec frontmatter status, and accepted-report receipt. If it detects an interrupted or conflicting write, it stops and prints recovery information. A normal caught failure rolls back when safe but retains the journal for inspection. Do not hand-edit the files to force completion.
98
+
99
+ Inspect the journal and affected project-relative files first. Then run:
100
+
101
+ ```sh
102
+ node .joycraft/runtime/completion.mjs recover --queue <queue-path>
103
+ ```
104
+
105
+ Recovery preflights both captured files before changing either: each current file must match the journal's before or after hash. It restores only the recorded before bytes, leaves conflicts untouched, and removes the journal only after a successful restore. Replaying recovery is safe until that journal is removed. Preserve the journal and rejected report for diagnosis. Retry `complete` or `accept-owner` only while its original review and any owner instruction remain current; otherwise obtain fresh evidence and authorization appropriate to the changed scope. If recovery reports a conflict or invalid journal, stop and report the local recovery blocker.
106
+
107
+ Host names compare without letter-case differences; session and agent IDs stay
108
+ opaque and case-exact. IDs must be nonempty, bounded, trim-stable and free of
109
+ control characters. This validates representation, not host authenticity.
@@ -0,0 +1,80 @@
1
+ # Project context ranking
2
+
3
+ From the consumer Git project root:
4
+
5
+ ```sh
6
+ node .joycraft/runtime/context/cli.mjs --query "Fix CSV export encoding and reuse the existing format decision"
7
+ node .joycraft/runtime/context/cli.mjs --query "CSV export format" --paths docs/context src/export
8
+ node .joycraft/runtime/context/cli.mjs --query "CSV export format" --history
9
+ ```
10
+
11
+ Add `--out docs/context-rank.json` to save the entire report and print only its
12
+ status and counts. The destination must be a new project-relative file in an
13
+ existing plain directory; existing files are never overwritten. Without `--out`,
14
+ stdout contains the complete JSON, including all exclusion records.
15
+
16
+ The command inventories Git-tracked and untracked nonignored files, then selects
17
+ UTF-8 text using deterministic keyword/path matches. Ordinary retrieval excludes
18
+ `docs/archive/` before files are read or scored and records each exclusion as
19
+ `archived-context`. Use `--history` only when historical material is relevant;
20
+ it remains reading context and never current authority. Programmatic callers use
21
+ `includeArchive: true` for the same opt-in. Explicit `--paths` accepts
22
+ project-relative files or directory prefixes and selects their safe text files
23
+ even without a keyword match. It never follows symlinks. Known secret/credential
24
+ paths, environment files, private keys, dependency directories, Git internals,
25
+ and transcript/session paths are excluded before reading. Ignored untracked
26
+ files are not in the inventory. This path filter cannot recognize every secret
27
+ placed in an ordinary source file; keep credentials in excluded private files.
28
+ The scanner rejects observed symlinks and checks opened-file identity before
29
+ reading. Like the rest of this local runtime, it is not a filesystem sandbox
30
+ against a hostile process concurrently replacing project ancestors.
31
+
32
+ Files over 512 KiB, binary/non-UTF-8 files, and nonregular entries are omitted
33
+ with reasons. The query is limited to 4,000 UTF-8 bytes. Each selected file keeps
34
+ its project-relative path, SHA-256 of the complete bytes read, local match score,
35
+ and a snippet of at most 1,800 UTF-8 bytes around the first matching line.
36
+ Snippets include source line numbers and whether they are partial. Large files
37
+ are never described as searched or ranked. Read those separately when needed.
38
+
39
+ Every selected candidate is retained, including a zero-scored file. Jev scores
40
+ all selected candidates in batches of at most 20; there is no candidate cap or
41
+ score cutoff. Encoded states over 60,000 bytes split into smaller batches, leaving
42
+ room for the shared question rubric. Narrow the query or paths before calling when a large area would
43
+ create unnecessary calls. A keyword search can miss paraphrases or dependencies;
44
+ this result never claims exhaustive context. Refine and follow relevant links.
45
+
46
+ The JSON `references` are sorted by Jev relevance, then local score/path. Each
47
+ reference identifies `provenance`, `relevance` (or `null`), and its scoring batch.
48
+ `batches` records candidate IDs, returned model, usage and elapsed time for each
49
+ successful call. `omitted`, `unreadable`, and `unranked` explain files that were
50
+ not scored. Hashes bind the result to the bytes read, not future edits. Open the
51
+ current source before relying on it; a bounded snippet is not the full file.
52
+
53
+ For an unclear state, data, or responsibility boundary, use the result as a
54
+ starting point and inspect the actual coupled sources as well: the owner and its
55
+ callers, readers, writers, or persistence boundary as applicable. Add discovered
56
+ paths to the brief/spec verification inputs before dispatch, and state any
57
+ unresolved coverage. Read `architecture.md` for focused examples. This expands
58
+ source discovery only when the seam matters; it does not make the context map a
59
+ second source of product decisions or a Jev-enforced prohibition.
60
+
61
+ Live scoring is the default. `.joycraft/hooks-config.json` supplies
62
+ `enabled`, `timeoutMs`, and Keychain service `JEV_API_KEY`; `--keychain-service` overrides it. The
63
+ shared `.joycraft/runtime/hooks/judge.mjs` primitive uses an existing
64
+ environment credential first, then the configured macOS Keychain service.
65
+ Credentials are never saved in the config, command arguments, result or project.
66
+ No dotenv file, transcript, or whole-project model dump is used.
67
+ The shared redactor removes recognizable credential patterns from outgoing
68
+ query/snippet strings before the Jev call; content hashes still identify the
69
+ original local bytes. Pattern redaction cannot identify arbitrary secret text.
70
+ Setting `enabled: false` selects explicit `local-search-only` output without
71
+ credential lookup; each candidate is marked unranked with `scoring-disabled`.
72
+
73
+ Missing credentials, malformed provider output or an outage stop further model
74
+ calls for that invocation. All selected references remain available in local
75
+ order where unranked; previously successful scores retain their provenance.
76
+ `status: incomplete-provider-ranking`, `provenance: local-search-fallback` and
77
+ `fallbackReason` make this explicit. Exit success means a usable result exists,
78
+ not that every candidate was scored; inspect `status` and `scoredCount`.
79
+ Invalid inputs or an unavailable Git inventory exit nonzero. Provider scores
80
+ advise reading order and never approve intent, authorize work or certify evidence.
@@ -0,0 +1,32 @@
1
+ # Optional delivery guard
2
+
3
+ `runtime/delivery.mjs` is an optional, local last-mile helper for a repository
4
+ whose author has already chosen a remote and branch. It only pushes an existing
5
+ commit and never fetches, merges, commits, forces, or infers a destination.
6
+
7
+ ```sh
8
+ node .joycraft/runtime/delivery.mjs check --root . --base <reviewed-base>
9
+ node .joycraft/runtime/delivery.mjs push --root . --base <reviewed-base> --remote origin --branch feature/example -- ./verify.sh
10
+ ```
11
+
12
+ The base is immediately resolved to a commit SHA and must be an ancestor of the
13
+ captured `HEAD` (the same commit is valid). The check observes the
14
+ committed `base..HEAD` range, rejects newly added conflict-marker lines, and parses
15
+ only changed, nondeleted `.json` and `.jsonl` files from `HEAD`. It also rejects
16
+ an unresolved index or active merge/cherry-pick/rebase state. Output is one JSON
17
+ receipt with paths and SHAs; successful push receipts also contain verifier exit
18
+ status and byte-count/digest metadata. Verifier output itself is drained without
19
+ being retained or printed.
20
+
21
+ For `push`, the helper holds a cooperative lock keyed by the chosen remote and
22
+ branch in Git's common directory. An existing lock is refused for manual
23
+ diagnosis; it is never broken automatically. It requires a clean tracked/index
24
+ state, captures `HEAD`, the semantic index tree and tracked-file hashes, runs
25
+ the explicit verifier argv without a shell, and rejects a nonzero result. It
26
+ then proves those captured sources are unchanged before pushing the captured SHA
27
+ with ordinary Git non-force semantics. A harmless Git index cache refresh, such
28
+ as one caused by `git status`, does not change the semantic index binding.
29
+
30
+ An exit-zero verifier is only an observed command result, not an independent
31
+ PASS or review. This helper is not a sandbox and cannot guarantee that external
32
+ writers cooperate. It does not implement private-school pnpm/CI/storage policy.