joycraft 1.2.2 → 1.4.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 CHANGED
@@ -30,11 +30,11 @@ Install Joycraft in this project.
30
30
  Do not commit, publish, or ask me for API keys.
31
31
  ```
32
32
 
33
- **Upgrading from 0.7?** Nothing changes until you choose. On a 0.7 project,
34
- `npx joycraft@latest update .` shows the migration plan and stops. Read
35
- [Migrating from 0.7](docs/migrating-from-0.7.md), or paste the
36
- [upgrade prompt](docs/prompts.md#upgrade-from-07). To stay on 0.7:
37
- `npx joycraft@0.7.17 update`.
33
+ **Upgrading from 0.7?** Nothing changes until you choose. Paste the
34
+ [upgrade prompt](docs/prompts.md#upgrade-from-07): your agent shows you the migration
35
+ plan and waits for your yes. To stay on 0.7, paste the
36
+ [stay on 0.7 prompt](docs/prompts.md#stay-on-07). More:
37
+ [Migrating from 0.7](docs/migrating-from-0.7.md).
38
38
 
39
39
  ## How to use it
40
40
 
@@ -104,57 +104,55 @@ agent both views: the whole project and the detail of the current step.
104
104
  (`.joycraft-spec-queue.json`) is the status of record, not the text.
105
105
  - **`docs/archive/` is history.** Finished features move there.
106
106
 
107
- Joycraft does not ship a wiki. If you keep one, link it from the context map, and
108
- treat `docs/features/` and `docs/archive/` as non-authoritative in your doc audits.
109
-
110
- ### Settings: `joycraft.yaml`
111
-
112
- Joycraft works with no settings. To change its folders, run a command after a
113
- feature is archived, or tell cleanup which code each context page describes, add a
114
- `joycraft.yaml` at the project root (template: `.joycraft/templates/joycraft.yaml`):
115
-
116
- ```yaml
117
- paths:
118
- features: working/features # default docs/features
119
- archive: working/archive # default docs/archive
120
- hooks:
121
- afterArchive: node scripts/wiki-sync.mjs
122
- cleanup:
123
- impact:
124
- - source: src/auction/**
125
- docs: [docs/context/auction-rules.md]
107
+ **Your wiki.** Joycraft works with the wiki you already keep. Tell your agent where
108
+ it is: the agent links it from the context map and can update it each time a
109
+ feature is archived. In doc audits, `docs/features/` and `docs/archive/` are
110
+ working material and history, not current knowledge. A built-in wiki is under
111
+ consideration ([decision D6](docs/context/decision-log.md)).
112
+
113
+ ```text
114
+ We keep a wiki in <where>. Link it from the context map, and keep it up to date
115
+ each time a feature is archived.
126
116
  ```
127
117
 
128
- The file is yours: Joycraft reads it and never rewrites it. Run
129
- `node .joycraft/runtime/config.mjs` to see the settings in effect.
118
+ ### Settings
119
+
120
+ Joycraft works with no settings. To change one, say what you want:
121
+
122
+ ```text
123
+ Keep Joycraft's briefs and specs in working/features.
124
+ Whenever a feature is archived, run our wiki sync script.
125
+ The page docs/context/auction-rules.md describes src/auction. Flag it when that code changes.
126
+ ```
130
127
 
131
- The `afterArchive` command gets `JOYCRAFT_FEATURE`, `JOYCRAFT_ARCHIVE_PATH` and
132
- `JOYCRAFT_SOURCE_PATH` in its environment. Use it to update a wiki or run a doc
133
- audit. If the command fails, the archive stays done and the archive CLI exits 3.
128
+ The agent writes the change to `joycraft.yaml` at the project root, shows it to you
129
+ first, and checks it. Ask "What are my Joycraft settings?" to see what is in effect.
130
+ The file is yours: Joycraft changes it only when you ask. If a command run after an
131
+ archive fails, the archive still counts as done.
134
132
 
135
133
  ### Keeping the workspace clean
136
134
 
137
- At the end of a session the agent runs these checks for you:
138
-
139
- - `node .joycraft/runtime/status.mjs` finds specs whose text disagrees with the queue,
140
- and features that are finished but not archived.
141
- - `node .joycraft/runtime/worktrees.mjs prune` removes the agent's worker worktrees
142
- once their spec is done and merged. It keeps anything unfinished, unmerged or not
143
- made by Joycraft, and says why. `worktrees.mjs list` shows what is left and its size.
144
- - `node .joycraft/runtime/coordinator.mjs` keeps one coordinating session per queue,
145
- so a second session's instructions do not reach the first session's workers.
146
- - `node .joycraft/runtime/cleanup.mjs` reports stale or unreachable project
147
- knowledge: finished features not archived, context pages that link to working
148
- material, broken, missing or unmapped pages, an AGENTS.md over its word budget,
149
- and pages whose code changed.
135
+ At the end of a session the agent checks the workspace for you. You do not run
136
+ anything:
137
+
138
+ - **Status.** It runs the gate check (below). The check finds specs marked done with
139
+ no accepted review and specs whose text disagrees with the queue. It also finds
140
+ features that are finished but not archived.
141
+ - **Worktrees.** It removes its worker worktrees once their spec is done and merged.
142
+ It keeps anything unfinished, unmerged or not made by Joycraft, and says why.
143
+ - **One coordinator.** One session coordinates each queue, so a second session's
144
+ instructions do not reach the first session's workers.
145
+ - **Stale knowledge.** It reports finished features not archived, context pages that
146
+ link to working material, broken, missing or unmapped pages, an AGENTS.md over its
147
+ word budget, and pages whose code changed.
150
148
  - The doc audit, based on [doc-cleanup](https://github.com/aka-luan/doc-cleanup),
151
149
  runs at every session end without being asked. It covers AGENTS.md, CLAUDE.md, the
152
150
  docs the session changed and the pages they link; after a feature is archived, the
153
151
  whole project. It checks each claim against the code, keeps your rules and traps,
154
152
  puts its findings on the session-end page, and changes nothing until you approve.
155
153
  Ask your agent to "clean up the docs" for a full audit at any time.
156
- - `node .joycraft/runtime/wiring.mjs` reports whether AGENTS.md has the Joycraft
157
- lines and a real context map, and whether CLAUDE.md imports it.
154
+ - **Wiring.** It checks that AGENTS.md has the Joycraft lines and a real context map,
155
+ and that CLAUDE.md imports it.
158
156
 
159
157
  Tests name the acceptance criterion they check, `[AC:<criterion-id>]`, so the
160
158
  reviewing agent can see which criteria have a test. A criterion with no test is a
@@ -193,6 +191,69 @@ counts as evidence; your project keeps its own tools.
193
191
  After an update, the agent checks the review loop again and asks only about what
194
192
  changed.
195
193
 
194
+ ### The gates: no spec is done without an accepted review
195
+
196
+ Joycraft's rule is that only an accepted review completes a spec. Without the
197
+ gates, this rule is an instruction in a skill. An agent can forget the rule or skip
198
+ it, for example late in a long session. The gates make the rule a check.
199
+
200
+ **What the gate stops.** The gate check finds three problems:
201
+
202
+ - A spec is marked done with no accepted review, no acceptance from you and no waiver.
203
+ - A spec has one status in the queue and a different status in the spec file.
204
+ - Joycraft cannot read a queue file or a spec file.
205
+
206
+ It sends the agent back with the spec or file name and the next step. A spec that waits at
207
+ `in-review` is not a problem.
208
+
209
+ **Why you want it.** Use the gates for long sessions and for sessions that you do
210
+ not watch. A prompt tells the agent what to do, but a prompt is not a guarantee.
211
+ With the gates on, Claude Code runs the check each time the agent tries to stop. The
212
+ agent cannot stop until the problem is gone.
213
+
214
+ **Before you turn them on.** An older project can have specs marked done with no
215
+ accepted review. The check sends each one back for a review. To see them first, say:
216
+
217
+ ```text
218
+ Run Joycraft's gate check with `node .joycraft/runtime/gate.mjs check` and show me
219
+ what it names. Change nothing yet.
220
+ ```
221
+
222
+ Do this also after you update an older project to 1.4.1, because session end now
223
+ runs the same check.
224
+
225
+ **Turn them on.** Say:
226
+
227
+ ```text
228
+ Turn on Joycraft's gates.
229
+ ```
230
+
231
+ The agent shows you the change to `.claude/settings.json` on a page. It writes the
232
+ change only on your yes. The change adds one Stop hook and no other line. Setup
233
+ also offers the gates one time.
234
+
235
+ **Turn them off.** Say:
236
+
237
+ ```text
238
+ Turn off Joycraft's gates.
239
+ ```
240
+
241
+ The agent removes Joycraft's hook. Your own hooks stay. If you remove Joycraft from
242
+ the project, the agent removes this hook first.
243
+
244
+ **What the gates do not do.**
245
+
246
+ - The hook is for Claude Code only for now. On the other agents, the session-end
247
+ skill runs the check. That step is an instruction, so the agent can still skip it.
248
+ - There is no CI check. Joycraft does not check your pull requests.
249
+ - The hook is not a sandbox. A shell command can still change the queue file. The
250
+ check finds the result at the next stop.
251
+
252
+ **A fourth review is refused.** On every agent, one spec gets at most three
253
+ reviews. A round is one set of reviewed inputs, so a new review of the same code
254
+ does not count again. Reviewer startup prints the round and refuses a fourth
255
+ review. The agent then records `## Decision needed` in the spec and asks you.
256
+
196
257
  ## Answering questions: the decision page
197
258
 
198
259
  When the agent needs you to choose between options, it asks in your question
@@ -235,8 +296,9 @@ project:
235
296
 
236
297
  All of it lives in your repository. Joycraft collects no data and does not call an AI
237
298
  model itself. Its only network use is the version check below. Joycraft adds no
238
- agent hooks and changes no agent settings. The `afterArchive` command above runs only
239
- if you set it.
299
+ agent hooks and changes no agent settings, except the gate hook that you turn on
300
+ ([The gates](#the-gates-no-spec-is-done-without-an-accepted-review)). A command
301
+ after an archive runs only if you asked for one.
240
302
 
241
303
  ## Updates
242
304
 
@@ -270,20 +332,24 @@ Check for a Joycraft update.
270
332
  "Tested" means: we installed Joycraft in a test project, one agent built a spec, and
271
333
  a second, separate agent checked it and passed it.
272
334
 
273
- ## Commands
335
+ ## Everything else: ask your agent
274
336
 
275
- Your agent runs these for you. They are here if you want them:
337
+ You never need to run a Joycraft command yourself. Each of these is a short prompt
338
+ in [Prompts](docs/prompts.md):
276
339
 
277
- ```bash
278
- npx joycraft@latest init . --harness claude,codex --yes # install
279
- npx joycraft@latest update . --yes # update (backs up files you edited first)
280
- npx joycraft@latest doctor . # check the install
281
- npx joycraft@latest update . --migrate --archive-custom --yes # move a 0.7 project to 1.0
282
- npx joycraft@latest rollback --yes # undo the move to 1.0
283
- ```
340
+ | You want to | Say |
341
+ |---|---|
342
+ | Update Joycraft | "Check for a Joycraft update." |
343
+ | Check the install | "Check my Joycraft install." |
344
+ | Change a setting | "Keep Joycraft's specs in working/features." |
345
+ | Connect your wiki | "Link our wiki and keep it up to date." |
346
+ | Clean up | "Clean up the docs and the workspace." |
347
+ | Turn the gates on | "Turn on Joycraft's gates." |
348
+ | Turn the gates off | "Turn off Joycraft's gates." |
349
+ | Undo the 1.0 upgrade | "Undo this project's upgrade to Joycraft 1.0." |
350
+ | Remove Joycraft | "Remove Joycraft from this project." |
284
351
 
285
- Add `--plan --json` to see the changes without making them. Without `--yes`, and
286
- outside a terminal, a command shows its plan and stops. It never waits for input.
352
+ The CLI commands behind them are in the [install guide](docs/install.md#cli-reference).
287
353
 
288
354
  More: [Install guide](docs/install.md) · [Migrating from 0.7](docs/migrating-from-0.7.md) ·
289
355
  [Prompts](docs/prompts.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md) ·
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "releaseVersion": "1.2.2",
3
+ "releaseVersion": "1.4.1",
4
4
  "manifestSchemas": [
5
5
  1
6
6
  ],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "joycraft",
3
- "version": "1.2.2",
3
+ "version": "1.4.1",
4
4
  "description": "Install and update Joycraft, a skill bundle and runtime for agent-led software work, in any project",
5
5
  "type": "module",
6
6
  "bin": {
@@ -13,8 +13,8 @@
13
13
  "payload"
14
14
  ],
15
15
  "joycraft": {
16
- "release": "1.2.2",
17
- "summary": "The README describes the 1.2 review loop, the install prompt shows what setup found, and an update names what is new and offers the question style.",
16
+ "release": "1.4.1",
17
+ "summary": "Gates: say \"Turn on Joycraft's gates\" and Claude Code cannot stop while a spec is done without an accepted review; session end runs the same check on every agent, and a fourth review is refused.",
18
18
  "autoSafeEligible": false
19
19
  },
20
20
  "scripts": {
@@ -20,16 +20,15 @@ node .joycraft/runtime/context/cli.mjs --query "<current request>"
20
20
  Narrow discovery with `--paths docs/context src/relevant-area` when the relevant
21
21
  area is known. Retrieval excludes `docs/archive/` unless historical material is
22
22
  specifically needed; add `--history` to inspect it as reading context, never as
23
- current authority. An optional model ranker orders the results when it is
24
- installed; otherwise they come in local-search order. Read `.joycraft/references/context.md` for output
23
+ current authority. Results come in local-search order. Read `.joycraft/references/context.md` for output
25
24
  and failure details.
26
25
 
27
- Read useful ranked source files and follow their relevant links. Scores guide
28
- reading order; low scores do not remove files or define task scope. Check omitted,
29
- unreadable and unranked reasons; a provider failure still leaves local references.
26
+ Read useful source files and follow their relevant links. Local scores guide
27
+ reading order; low scores do not remove files or define task scope. Check omitted
28
+ and unreadable reasons.
30
29
  Refine the query or paths when local keyword matching misses a known dependency.
31
30
  When the requested change has an unclear state, data, or responsibility seam,
32
- trace the actual counterpart sources beyond the ranked list: for example, the
31
+ trace the actual counterpart sources beyond the result list: for example, the
33
32
  owner alongside its callers, readers, writers, or persistence boundary. Add
34
33
  discovered sources to the work's declared inputs and report any unresolved
35
34
  coverage. Read `.joycraft/references/architecture.md` only for that
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: joycraft-entry
3
- description: Start any Joycraft work. After Joycraft is installed, or when asked to "set up Joycraft" or "check the context map", read the project, interview the user and build the context map in AGENTS.md; then turn a repair, feature, or mixed request into a context-backed brief and the next useful action.
4
- compatibility: Setup and routing helpers require Node.js 22+ and the installed .joycraft runtime only when used; ordinary brief and context navigation has no project-stack prerequisite.
3
+ description: Start any Joycraft work. After Joycraft is installed, when asked to "set up Joycraft", "check the context map", change Joycraft settings or remove Joycraft, read the project, interview the user and build the context map in AGENTS.md; then turn a repair, feature, or mixed request into a context-backed brief and the next useful action.
4
+ compatibility: Setup helpers require Node.js 22+ and the installed .joycraft runtime only when used; ordinary brief and context navigation has no project-stack prerequisite.
5
5
  ---
6
6
 
7
7
  Run `node .joycraft/runtime/update-check.mjs check` first, once per session. If it
@@ -24,7 +24,7 @@ alone does not start a full setup.
24
24
 
25
25
  Read existing project instructions first. During an upgrade, inspect the installed
26
26
  manifest’s `legacyConflicts` and reconcile competing old skill discovery before
27
- using routing advice; preserved custom content is not a completed migration.
27
+ choosing skills; preserved custom content is not a completed migration.
28
28
  On a bare project, offer the
29
29
  [kickoff](../../../.joycraft/references/setup.md#kickoff-for-a-new-project)
30
30
  in one line before any brief or scaffold, and run it when the user asks for it on
@@ -49,7 +49,7 @@ scope or a consequential choice.
49
49
 
50
50
  When an unclear state, data, or responsibility boundary could change the work,
51
51
  do focused discovery before splitting it: inspect the actual owner and its
52
- callers, readers, writers, or other coupled counterpart. Ranking can point to
52
+ callers, readers, writers, or other coupled counterpart. Search can point to
53
53
  sources, but does not replace that trace. Keep settled product behavior in the
54
54
  brief; record only durable, source-backed navigation in the project's existing
55
55
  context homes. Read `.joycraft/references/architecture.md` for this
@@ -103,6 +103,15 @@ with no options.
103
103
  `node .joycraft/runtime/config.mjs` and use its `paths` wherever Joycraft guidance
104
104
  says `docs/features`, `docs/archive` or `docs/context`.
105
105
 
106
+ **Change settings when asked.** When the user asks to move Joycraft's folders, run
107
+ something after a feature is archived (such as a wiki sync), map code to a context
108
+ page, connect their wiki, see their settings or remove Joycraft, follow
109
+ [settings](../../../.joycraft/references/settings.md). The user never edits
110
+ `joycraft.yaml` or runs a Joycraft command by hand.
111
+
112
+ **Gates by request.** When the user asks to turn Joycraft's gates on or off, or
113
+ what they do, follow [gates](../../../.joycraft/references/gates.md).
114
+
106
115
  **Show documents as pages.** A brief, plan, spec set or review that the user must
107
116
  read or approve is also rendered, never left as Markdown in chat: the decision
108
117
  artifact for a brief, an HTML page for anything else. Show it as
@@ -126,20 +135,6 @@ existing direct path when it fits the request. Do not turn routine data entry
126
135
  into a code-spec factory or create per-record plans when an approved batch tool
127
136
  already owns the operation. Preserve its validation, approval and readback rules.
128
137
 
129
- When a native hook adds routing advice to the prompt, use it to select relevant
130
- skills. Keep all expressed goals even when a classifier misses a signal. Do not
131
- repeat a live routing call when the hook already provided current advice.
132
- Routing does not approve scope, answer a decision, or establish evidence.
133
-
134
138
  Use `joycraft-context` when you need to find relevant project files beyond the
135
- context map. Its deterministic search (and optional ranking) provides pointers; read the
136
- selected source before relying on it. For hook status, blocked edits or provider
137
- failures, read `.joycraft/references/hooks-runtime.md`. Treat unavailable
138
- checks as unavailable, never as approval. For a denial, compare its cited scope
139
- with the current task and the actual human question/answer. Repair missing
140
- source delivery once through the documented binding flow, then resume understood
141
- authorized work. Do not ask for the same permission again, move a chat answer to
142
- a different document as an enforcement workaround, weaken a gate, or wrap a
143
- denied command. Ask the host for the legitimate correction when needed.
144
- If native hooks are absent and routing is materially uncertain, the explicit adapter in `.joycraft/references/routing.md` remains available.
145
- When requested setup includes native hooks, use [Codex hook installation](../../../.joycraft/references/hooks-install.md) or [Claude Code hook installation](../../../.joycraft/references/hooks-claude.md) for the active host. Installation and project setup do not establish host trust or execution.
139
+ context map. Its deterministic search provides pointers; read the selected
140
+ source before relying on it.
@@ -30,10 +30,7 @@ For normal native execution, the host launches the selected worker first. The
30
30
  child bootstraps from its actual root, then runs `dispatch-start.mjs --role
31
31
  implementer` with its actual native identity before any tasked edit or mutation.
32
32
  The coordinator runs that start itself only when it is the implementer actor.
33
- Use the returned packet only when `ready` is true. A hooks-disabled/manual
34
- workflow can be ready; unavailable hook status is not a new permission gate for
35
- all work. When startup returns unenforced, hold only that claimed enforced task,
36
- report why, and continue unrelated authorized or manual/disabled workflow.
33
+ Use the returned packet only when `ready` is true.
37
34
 
38
35
  If existing independent reports reveal a possible recurring failure, follow [recurring failure guidance](../../../.joycraft/references/recurring-failures.md) before carrying it forward: inspect the current scoped sources and actual counterpart path or journey, then provide any proposed lesson as exact inputs through the existing dispatch flow. A verified repair may establish its local project fact; a broader method benefit remains pending later reuse.
39
36
 
@@ -77,9 +74,9 @@ It needs actual host session/agent identity and available current authority
77
74
  as described in [dispatch guidance](../../../.joycraft/references/dispatch.md).
78
75
  Write its packet or subject beneath a confirmed Git-ignored project-local
79
76
  directory, not among reviewed sources.
80
- If it returns unenforced, or a separate review context/capability is unavailable,
81
- leave the spec `in-review`; do not invent an ID or prompt to continue. This holds
82
- the claimed review, not unrelated authorized or hooks-disabled/manual work.
77
+ If a separate review context/capability is unavailable, leave the spec
78
+ `in-review`; do not invent an ID to continue. This holds the claimed review,
79
+ not unrelated authorized work.
83
80
 
84
81
  When a recorded tool breaks during a run (the dev server does not start, a
85
82
  port is taken, the browser or simulator crashes), repair it with what the user
@@ -101,9 +98,10 @@ Only the guarded completion path can move an `in-review` spec to `done`. Use its
101
98
 
102
99
  When a current independent review is `FAIL` or `UNVERIFIED`, first fix
103
100
  straightforward failures within the existing authorization and obtain a fresh
104
- review. A spec gets at most three reviews; state the real round number in each
105
- fix brief. Settled briefs and checked specs should make this rare. If a second FAIL
106
- on the same criterion or a "decision needed" finding still occurs, send no
101
+ review. A spec gets at most three reviews: reviewer startup prints
102
+ `reviewRound` and refuses a fourth. Settled briefs and checked specs should make
103
+ this rare. If startup refuses a review, or a second FAIL on the same criterion
104
+ or a "decision needed" finding still occurs, send no
107
105
  further fix and never amend acceptance yourself: note it under `## Decision
108
106
  needed` in the spec, leave it `in-review`, and continue independent ready work. An owner can explicitly accept the
109
107
  current findings and their stated limits through `accept-owner`; that is a
@@ -8,11 +8,6 @@ compatibility: Requires Node.js 22+ and the installed .joycraft runtime for the
8
8
 
9
9
  Use this skill when pausing or finishing an authorized queue session.
10
10
 
11
- On Claude `SessionEnd`, write only the local session summary and deduplicate the
12
- transition record. Do not call an API or archive from that hook. On other hosts,
13
- use their metrics/manual or portable summary path when available; never infer a
14
- Claude lifecycle event from a generic session boundary.
15
-
16
11
  Read each touched queue and report the real state of every affected spec: `todo`, `in-review`, or `done`. `done` must have either an accepted PASS report receipt or a completion-helper owner-acceptance record bound to a current failed or unverified report; a commit, PASS command, or implementer assertion is not acceptance. Keep blocked or failed dependency branches explicit while identifying independent ready work that can continue next.
17
12
 
18
13
  If the session stops or restarts a concurrent run, report its recorded
@@ -20,8 +15,7 @@ coordinator ownership, captured refs, known worker trees, leases, locks, and
20
15
  runtime processes. Release only resources demonstrably owned by that run;
21
16
  retain ambiguous merges, locks, processes, and trees for diagnosis. Do not
22
17
  force local state to a remote tip. Start a replacement only from the durable
23
- run journal and a newly printed dispatch plan. This guidance describes the
24
- project/native runtime boundary; it does not enforce lifecycle behavior.
18
+ run journal and a newly printed dispatch plan.
25
19
 
26
20
  For each completed spec, report the implementation revision, independent reviewer session ID, report and receipt paths, actual commands and outcomes, visual inspection status where required, and known limitations. For owner-accepted work, also report the owner-acceptance record and its inherited limits as `done, owner-accepted with <limits>`; preserve the original `FAIL` or `UNVERIFIED` report rather than calling it PASS or verified. List each spec completed under a feature waiver as `done, waived by the user: "<instruction>"`, with any report's real verdict; never call it reviewed or verified.
27
21
 
@@ -29,12 +23,13 @@ If a completion operation failed or was interrupted, do not declare success or h
29
23
 
30
24
  Leave enough project-relative paths and next actions for another session to resume the autonomous ready authorized queue without recreating settled context or decisions.
31
25
 
32
- Before ending the session, run `node .joycraft/runtime/status.mjs`. Repair
33
- lagging frontmatter of accepted specs with `--fix`; report any other drift and
34
- any feature listed as ready to archive. Then preview
35
- `node .joycraft/runtime/worktrees.mjs prune` and apply it with `--apply`: it
36
- removes only clean, integrated trees of done specs and keeps failed, blocked or
37
- unknown trees with their reason. Report kept trees and their size from `list`.
26
+ Before ending, run `node .joycraft/runtime/status.mjs --fix` (repairs lagging
27
+ frontmatter of accepted specs, lists features ready to archive) and
28
+ `node .joycraft/runtime/gate.mjs check`. Do the step each gate message names,
29
+ such as a completing command. Tell the user each message you could not clear.
30
+ Then preview `node .joycraft/runtime/worktrees.mjs prune` and apply it with
31
+ `--apply`: it removes only clean, integrated trees of done specs and keeps the
32
+ rest with their reason. Report kept trees and their size from `list`.
38
33
  When this session coordinated a queue and no work on it remains, release the
39
34
  lease with `node .joycraft/runtime/coordinator.mjs release --queue <queue> --session <your-session-id>`. See [worker isolation](../../../.joycraft/references/worktrees.md)
40
35
  when the session used parallel mutable workers.
@@ -6,12 +6,6 @@ compatibility: The optional shared evidence validator requires Node.js 22+ and t
6
6
 
7
7
  # Useful testing evidence
8
8
 
9
- Use any post-edit hook findings as candidate gaps to inspect against the active
10
- requirements and relevant tests. A flag is not proof of a defect, and no flag is
11
- not proof of coverage. Keep valid gaps visible until a useful assertion or
12
- observed interaction resolves them; missing tests during intermediate edits do
13
- not require stopping understood implementation.
14
-
15
9
  Read the active requirements and relevant existing tests. Choose the smallest
16
10
  boundary that can establish each claim: real function inputs for arithmetic,
17
11
  composed transitions for stateful behavior, rendered interaction for UI behavior.
@@ -29,10 +29,9 @@ prepare a source packet for a manual boundary, but it must not bind the child
29
29
  using the parent's identity. After launch, the reviewer child bootstraps at its
30
30
  actual root and runs `dispatch-start.mjs --role reviewer` with its own actual
31
31
  native identity, which captures the subject, preflights delivery, writes the
32
- bounded packet, and binds it. If the real ID, available authority, or a separate
33
- reviewer context is unavailable, leave the spec `in-review`; do not manufacture
34
- any of them. A hooks-disabled/manual workflow can still be ready; an unenforced
35
- result holds only the claimed review, not unrelated work.
32
+ bounded packet. If the real ID or a separate reviewer context is unavailable,
33
+ leave the spec `in-review`; do not manufacture either. This holds only the
34
+ claimed review, not unrelated work.
36
35
  Reviewer startup output also carries `trace`, the spec's criteria with the tests
37
36
  tagged `[AC:<criterion-id>]` (`node .joycraft/runtime/trace.mjs --queue <queue> --spec <id>`
38
37
  produces the same). Report untraced criteria as findings; a missing tag alone is
@@ -44,10 +43,8 @@ Dispatch `collaboration.spawn_agent` with `fork_turns: "none"` and the packet's
44
43
 
45
44
  When already dispatched as the independent reviewer, perform the review directly; do not recursively dispatch another reviewer. Read the parent brief, spec, queue entry, declared criteria and exact verification inputs. Use the supplied subject, set independence truthfully, and do not self-certify implementation from your own context.
46
45
 
47
- Inspect any hook rule/test-gap findings alongside the actual changes and
48
- requirements. Resolve supported concerns with observed evidence; a classifier
49
- score or clean hook receipt cannot establish acceptance. Check changed tests for
50
- weakened assertions that could hide the requested behavior.
46
+ Check changed tests for weakened assertions that could hide the requested
47
+ behavior.
51
48
 
52
49
  Review scope as well as behavior: determine whether the listed inputs and criteria cover the requested work, including relevant newly changed files. For a cross-boundary change, inspect the combined observable behavior across the relevant producer, consumer, state or storage boundary; separate green helpers, snapshots, or assertion counts do not establish that behavior. If a material counterpart or owning decision/context source was omitted, report the scope gap and require its exact path to be added before a fresh current review subject is prepared. Preserve the snapshot's implementation revision as provenance while checking its current bound inputs. A changed, missing, or renamed input makes the subject stale; do not substitute a newer HEAD as its identity.
53
50
 
@@ -79,10 +79,8 @@ subject or provide the reviewer with an intended verdict or implementer reasonin
79
79
  Update only affected accepted facts in their owning reference, reconciling them
80
80
  at session end before any eligible archival. Active choices remain in their
81
81
  brief; rationale links to that choice; proposals stay marked as proposals.
82
- References describe and navigate the project. They neither grant permission nor
83
- become global Jev constraints. Do not add them to global hook rule paths or make
84
- extra live classification calls merely to maintain a map. Retrieval scores and
85
- this procedure do not certify exhaustive discovery.
82
+ References describe and navigate the project. They do not grant permission.
83
+ Retrieval scores and this procedure do not certify exhaustive discovery.
86
84
 
87
85
  Keep task context bounded to relevant sources. When evaluating the change,
88
86
  record newly delivered input bytes, repeated reads/provider calls, human
@@ -43,19 +43,17 @@ and a snippet of at most 1,800 UTF-8 bytes around the first matching line.
43
43
  Snippets include source line numbers and whether they are partial. Large files
44
44
  are never described as searched or ranked. Read those separately when needed.
45
45
 
46
- Every selected candidate is retained, including a zero-scored file. Jev scores
47
- all selected candidates in batches of at most 20; there is no candidate cap or
48
- score cutoff. Encoded states over 60,000 bytes split into smaller batches, leaving
49
- room for the shared question rubric. Narrow the query or paths before calling when a large area would
50
- create unnecessary calls. A keyword search can miss paraphrases or dependencies;
51
- this result never claims exhaustive context. Refine and follow relevant links.
52
-
53
- The JSON `references` are sorted by Jev relevance, then local score/path. Each
54
- reference identifies `provenance`, `relevance` (or `null`), and its scoring batch.
55
- `batches` records candidate IDs, returned model, usage and elapsed time for each
56
- successful call. `omitted`, `unreadable`, and `unranked` explain files that were
57
- not scored. Hashes bind the result to the bytes read, not future edits. Open the
46
+ Every selected candidate is retained, including a zero-scored file; there is no
47
+ candidate cap or score cutoff. A keyword search can miss paraphrases or
48
+ dependencies; this result never claims exhaustive context. Refine and follow
49
+ relevant links.
50
+
51
+ The JSON `references` come in local-search order: local score, then path.
52
+ `status` is `local-search-only`, and `unranked` lists each candidate with the
53
+ reason `scoring-disabled`. `omitted` and `unreadable` explain files that were
54
+ not read. Hashes bind the result to the bytes read, not future edits. Open the
58
55
  current source before relying on it; a bounded snippet is not the full file.
56
+ Invalid inputs or an unavailable Git inventory exit nonzero.
59
57
 
60
58
  For an unclear state, data, or responsibility boundary, use the result as a
61
59
  starting point and inspect the actual coupled sources as well: the owner and its
@@ -63,28 +61,7 @@ callers, readers, writers, or persistence boundary as applicable. Add discovered
63
61
  paths to the brief/spec verification inputs before dispatch, and state any
64
62
  unresolved coverage. Read `architecture.md` for focused examples. This expands
65
63
  source discovery only when the seam matters; it does not make the context map a
66
- second source of product decisions or a Jev-enforced prohibition.
67
-
68
- Live scoring is the default. `.joycraft/hooks-config.json` supplies
69
- `enabled`, `timeoutMs`, and Keychain service `JEV_API_KEY`; `--keychain-service` overrides it. The
70
- shared `.joycraft/runtime/hooks/judge.mjs` primitive uses an existing
71
- environment credential first, then the configured macOS Keychain service.
72
- Credentials are never saved in the config, command arguments, result or project.
73
- No dotenv file, transcript, or whole-project model dump is used.
74
- The shared redactor removes recognizable credential patterns from outgoing
75
- query/snippet strings before the Jev call; content hashes still identify the
76
- original local bytes. Pattern redaction cannot identify arbitrary secret text.
77
- Setting `enabled: false` selects explicit `local-search-only` output without
78
- credential lookup; each candidate is marked unranked with `scoring-disabled`.
79
-
80
- Missing credentials, malformed provider output or an outage stop further model
81
- calls for that invocation. All selected references remain available in local
82
- order where unranked; previously successful scores retain their provenance.
83
- `status: incomplete-provider-ranking`, `provenance: local-search-fallback` and
84
- `fallbackReason` make this explicit. Exit success means a usable result exists,
85
- not that every candidate was scored; inspect `status` and `scoredCount`.
86
- Invalid inputs or an unavailable Git inventory exit nonzero. Provider scores
87
- advise reading order and never approve intent, authorize work or certify evidence.
64
+ second source of product decisions or a prohibition.
88
65
 
89
66
  Treat only the context homes as current authority. `docs/features/` is working
90
67
  material that can be stale until its feature is archived, and `docs/archive/` is