joycraft 0.7.17 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +148 -140
- package/dist/cli.js +1593 -373
- package/dist/cli.js.map +1 -1
- package/dist/joycraft-release.json +1 -1
- package/package.json +9 -3
- package/payload/.agents/skills/joycraft-context/SKILL.md +36 -0
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +68 -0
- package/payload/.agents/skills/joycraft-entry/SKILL.md +109 -0
- package/payload/.agents/skills/joycraft-implement/SKILL.md +118 -0
- package/payload/.agents/skills/joycraft-retro/SKILL.md +54 -0
- package/payload/.agents/skills/joycraft-retro/agents/openai.yaml +5 -0
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +82 -0
- package/payload/.agents/skills/joycraft-testing/SKILL.md +60 -0
- package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +59 -0
- package/payload/.agents/skills/joycraft-ui-slice/scripts/serve.mjs +97 -0
- package/payload/.agents/skills/joycraft-verify/SKILL.md +103 -0
- package/payload/.claude/agents/joycraft-implementer.md +36 -0
- package/payload/.claude/agents/joycraft-reviewer.md +35 -0
- package/payload/.joycraft/assets/artifacts/kit.css +102 -0
- package/payload/.joycraft/assets/artifacts/kit.js +301 -0
- package/payload/.joycraft/assets/artifacts/transports.js +236 -0
- package/payload/.joycraft/contracts/types.d.ts +185 -0
- package/payload/.joycraft/references/architecture.md +90 -0
- package/payload/.joycraft/references/archive.md +211 -0
- package/payload/.joycraft/references/artifacts.md +176 -0
- package/payload/.joycraft/references/completion.md +109 -0
- package/payload/.joycraft/references/context.md +85 -0
- package/payload/.joycraft/references/delivery.md +32 -0
- package/payload/.joycraft/references/dispatch.md +231 -0
- package/payload/.joycraft/references/recurring-failures.md +33 -0
- package/payload/.joycraft/references/retro.md +94 -0
- package/payload/.joycraft/references/setup.md +295 -0
- package/payload/.joycraft/references/testing.md +120 -0
- package/payload/.joycraft/references/update.md +44 -0
- package/payload/.joycraft/references/workflow.md +113 -0
- package/payload/.joycraft/references/worktrees.md +174 -0
- package/payload/.joycraft/runtime/archive.mjs +463 -0
- package/payload/.joycraft/runtime/artifacts/cli.mjs +61 -0
- package/payload/.joycraft/runtime/artifacts/decisions.mjs +214 -0
- package/payload/.joycraft/runtime/artifacts/model.mjs +161 -0
- package/payload/.joycraft/runtime/artifacts/preferences.mjs +127 -0
- package/payload/.joycraft/runtime/artifacts/render.mjs +21 -0
- package/payload/.joycraft/runtime/artifacts/server.mjs +40 -0
- package/payload/.joycraft/runtime/completion.mjs +300 -0
- package/payload/.joycraft/runtime/context/cli.mjs +75 -0
- package/payload/.joycraft/runtime/context/index.mjs +29 -0
- package/payload/.joycraft/runtime/context/search.mjs +149 -0
- package/payload/.joycraft/runtime/coordinator.mjs +169 -0
- package/payload/.joycraft/runtime/delivery.mjs +142 -0
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +535 -0
- package/payload/.joycraft/runtime/dispatch-start.mjs +106 -0
- package/payload/.joycraft/runtime/evidence.mjs +137 -0
- package/payload/.joycraft/runtime/identity.mjs +486 -0
- package/payload/.joycraft/runtime/kickoff.mjs +174 -0
- package/payload/.joycraft/runtime/redact.mjs +9 -0
- package/payload/.joycraft/runtime/retro.mjs +151 -0
- package/payload/.joycraft/runtime/review-tools.json +34 -0
- package/payload/.joycraft/runtime/review-tools.mjs +331 -0
- package/payload/.joycraft/runtime/scope.mjs +129 -0
- package/payload/.joycraft/runtime/status.mjs +96 -0
- package/payload/.joycraft/runtime/update-check.mjs +142 -0
- package/payload/.joycraft/runtime/worktrees.mjs +201 -0
- package/payload/.joycraft/templates/README.md +7 -0
- package/payload/.joycraft/templates/artifact.json +33 -0
- package/payload/.joycraft/templates/brief.md +35 -0
- package/payload/.joycraft/templates/decisions.md +13 -0
- package/payload/.joycraft/templates/project-context.md +36 -0
- package/payload/.joycraft/templates/queue.json +27 -0
- package/payload/.joycraft/templates/spec.md +39 -0
- package/payload/.joycraft/templates/ui-slice.html +71 -0
- package/payload/PIN +77 -0
- package/payload/scripts/export.mjs +301 -0
- package/payload/scripts/hook-paths.mjs +35 -0
- package/payload/scripts/legacy-hooks.mjs +128 -0
- package/payload/scripts/legacy-inventory.json +117 -0
- package/dist/chunk-35RQLGKM.js +0 -2167
- package/dist/chunk-35RQLGKM.js.map +0 -1
- package/dist/chunk-7BPB2IKY.js +0 -255
- package/dist/chunk-7BPB2IKY.js.map +0 -1
- package/dist/chunk-B73DPYYC.js +0 -377
- package/dist/chunk-B73DPYYC.js.map +0 -1
- package/dist/chunk-K4AI6FKB.js +0 -417
- package/dist/chunk-K4AI6FKB.js.map +0 -1
- package/dist/chunk-KKDKC4FM.js +0 -115
- package/dist/chunk-KKDKC4FM.js.map +0 -1
- package/dist/chunk-OMFGDJW4.js +0 -97
- package/dist/chunk-OMFGDJW4.js.map +0 -1
- package/dist/chunk-YLWBDXF4.js +0 -3999
- package/dist/chunk-YLWBDXF4.js.map +0 -1
- package/dist/chunk-Z5JFEGWG.js +0 -563
- package/dist/chunk-Z5JFEGWG.js.map +0 -1
- package/dist/init-O2QC5X57.js +0 -60
- package/dist/init-O2QC5X57.js.map +0 -1
- package/dist/init-autofix-2DMBO4QN.js +0 -122
- package/dist/init-autofix-2DMBO4QN.js.map +0 -1
- package/dist/install-manifest-EQHT4474.js +0 -37
- package/dist/install-manifest-EQHT4474.js.map +0 -1
- package/dist/release-artifact-4TL5L2ZY.js +0 -14
- package/dist/release-artifact-4TL5L2ZY.js.map +0 -1
- package/dist/release-resolver-P2H46QTU.js +0 -293
- package/dist/release-resolver-P2H46QTU.js.map +0 -1
- package/dist/telemetry-store-IBO5GRTA.js +0 -14
- package/dist/telemetry-store-IBO5GRTA.js.map +0 -1
- package/dist/update-LYHS4FBH.js +0 -21
- package/dist/update-LYHS4FBH.js.map +0 -1
- package/dist/update-check-YT765NE7.js +0 -36
- package/dist/update-check-YT765NE7.js.map +0 -1
- package/dist/upgrade-GMP6JQ52.js +0 -28
- package/dist/upgrade-GMP6JQ52.js.map +0 -1
|
@@ -0,0 +1,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,85 @@
|
|
|
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.
|
|
81
|
+
|
|
82
|
+
Treat only the context homes as current authority. `docs/features/` is working
|
|
83
|
+
material that can be stale until its feature is archived, and `docs/archive/` is
|
|
84
|
+
history; see the knowledge-home table in `setup.md`. Joycraft ships no wiki. Skills
|
|
85
|
+
do not need to be named by the user: pick the step from the request.
|
|
@@ -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.
|