joycraft 1.1.1 → 1.2.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 (49) hide show
  1. package/README.md +57 -16
  2. package/dist/cli.js +50 -9
  3. package/dist/cli.js.map +1 -1
  4. package/dist/joycraft-release.json +1 -1
  5. package/package.json +3 -3
  6. package/payload/.agents/skills/joycraft-cleanup/SKILL.md +81 -34
  7. package/payload/.agents/skills/joycraft-context/SKILL.md +30 -4
  8. package/payload/.agents/skills/joycraft-decompose/SKILL.md +5 -1
  9. package/payload/.agents/skills/joycraft-entry/SKILL.md +35 -8
  10. package/payload/.agents/skills/joycraft-implement/SKILL.md +16 -0
  11. package/payload/.agents/skills/joycraft-session-end/SKILL.md +9 -4
  12. package/payload/.agents/skills/joycraft-testing/SKILL.md +7 -5
  13. package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +4 -3
  14. package/payload/.agents/skills/joycraft-verify/SKILL.md +1 -1
  15. package/payload/.claude/agents/joycraft-reviewer.md +7 -2
  16. package/payload/.joycraft/assets/artifacts/kit.css +8 -0
  17. package/payload/.joycraft/assets/artifacts/kit.js +163 -21
  18. package/payload/.joycraft/assets/artifacts/transports.js +14 -3
  19. package/payload/.joycraft/contracts/types.d.ts +22 -0
  20. package/payload/.joycraft/references/archive.md +4 -2
  21. package/payload/.joycraft/references/artifacts.md +21 -2
  22. package/payload/.joycraft/references/cleanup.md +109 -3
  23. package/payload/.joycraft/references/completion.md +55 -2
  24. package/payload/.joycraft/references/context.md +64 -2
  25. package/payload/.joycraft/references/dispatch.md +12 -0
  26. package/payload/.joycraft/references/doc-cleanup-LICENSE.md +23 -0
  27. package/payload/.joycraft/references/knowledge.md +58 -0
  28. package/payload/.joycraft/references/setup.md +165 -151
  29. package/payload/.joycraft/references/testing.md +14 -7
  30. package/payload/.joycraft/references/update.md +13 -3
  31. package/payload/.joycraft/references/workflow.md +3 -2
  32. package/payload/.joycraft/runtime/archive.mjs +19 -4
  33. package/payload/.joycraft/runtime/artifacts/decisions.mjs +16 -5
  34. package/payload/.joycraft/runtime/artifacts/server.mjs +14 -1
  35. package/payload/.joycraft/runtime/cleanup.mjs +95 -8
  36. package/payload/.joycraft/runtime/completion.mjs +210 -10
  37. package/payload/.joycraft/runtime/config.mjs +5 -3
  38. package/payload/.joycraft/runtime/dispatch-preflight.mjs +16 -3
  39. package/payload/.joycraft/runtime/evidence.mjs +4 -0
  40. package/payload/.joycraft/runtime/identity.mjs +11 -0
  41. package/payload/.joycraft/runtime/review-tools.json +110 -30
  42. package/payload/.joycraft/runtime/review-tools.mjs +702 -131
  43. package/payload/.joycraft/runtime/status.mjs +1 -1
  44. package/payload/.joycraft/runtime/update-check.mjs +38 -8
  45. package/payload/.joycraft/runtime/wiring.mjs +156 -0
  46. package/payload/.joycraft/runtime/worktrees.mjs +1 -1
  47. package/payload/.joycraft/templates/joycraft.yaml +2 -0
  48. package/payload/.joycraft/templates/project-context.md +6 -1
  49. package/payload/PIN +45 -42
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "releaseVersion": "1.1.1",
3
+ "releaseVersion": "1.2.0",
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.1.1",
3
+ "version": "1.2.0",
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.1.1",
17
- "summary": "Fixes from the 1.0.1 and 1.1 re-reviews: cleanup reads code fences correctly, trace reads folders like tests/[slug], prune skips the tree it runs from, and stale locks are taken over safely.",
16
+ "release": "1.2.0",
17
+ "summary": "The review loop uses the tool your project already has: setup finds it per package, recommends one only for a gap and installs on your yes; agreed limits are no longer UNVERIFIED; a per-feature waiver can skip review; a broken tool holds one spec, not the queue.",
18
18
  "autoSafeEligible": false
19
19
  },
20
20
  "scripts": {
@@ -1,41 +1,88 @@
1
1
  ---
2
2
  name: joycraft-cleanup
3
- description: Find stale or unreachable project knowledge (finished features left in the working folder, context pages that link to working material, broken or orphaned pages, pages whose code changed, leftover worktrees) and fix what the user approves.
3
+ description: Audit project docs and the AGENTS.md context map for rot (stale claims, finished plans and logs, contradictions, dead paths, drifted authorities, unreachable pages), check each claim against the code, propose trimming an AGENTS.md that is too long, and change only what the user approves. Runs at every session end (scoped to what the session touched) and after a feature is archived (whole project); also use for "clean up the docs", "audit the docs", "what in our docs is stale", "AGENTS.md is too long", or when cleanup.mjs reports findings.
4
4
  compatibility: Requires Node.js 22+ and the installed .joycraft runtime. Git improves the code-drift and worktree checks.
5
5
  ---
6
6
 
7
7
  # Joycraft Cleanup
8
8
 
9
- Use when the user asks to clean up docs, remove stale material or check that
10
- project knowledge is current, and at session end when `status.mjs` or the
11
- archive step leaves loose ends. It keeps the context home trustworthy; it does
12
- not change product decisions.
13
-
14
- Run the report from the project root:
15
-
16
- ```sh
17
- node .joycraft/runtime/cleanup.mjs
18
- ```
19
-
20
- Exit 0 means no findings; exit 2 means findings. The script reads
21
- `joycraft.yaml` for `paths` and the `cleanup.impact` map (code globs → context
22
- pages) and never edits a file. Read `.joycraft/references/cleanup.md` for each
23
- check and its usual fix.
24
-
25
- Then, for each finding:
26
-
27
- 1. Read the files it names before proposing anything. For `impact-drift`,
28
- read the listed commits' changes and the page; the page may still be true.
29
- 2. Propose one concrete fix per finding: the exact link, page, section or
30
- command. Group findings by fix, not by check.
31
- 3. Show the proposals to the user as a rendered page (the decision artifact for
32
- choices, or an HTML page), never only as Markdown in chat. Ask once.
33
- 4. Apply only what the user approves. Move durable facts into the context home
34
- before an archive. Archive only through the session-end archive path. Remove
35
- an unknown worktree only after checking it for unmerged work and with the
36
- user's approval.
37
- 5. Run the report again and give the remaining findings with their reasons.
38
-
39
- Never delete a context page to clear a finding; merge or redirect it. Do not
40
- invent facts to refresh a stale page: when the code does not settle it, record
41
- the question in the owning brief.
9
+ Keep project docs true and the context map lean. Treat every doc claim as a
10
+ hypothesis and the repository as the evidence. The homes the map points to must
11
+ state the current truth; see [knowledge guidance](../../../.joycraft/references/knowledge.md)
12
+ for that rule. This method is adapted from doc-cleanup by aka-luan
13
+ ([MIT](../../../.joycraft/references/doc-cleanup-LICENSE.md)), brought in by David Moshal.
14
+
15
+ Work in two passes: diagnose and report without editing, then execute only what
16
+ the user approves. Approval to edit is not approval to commit. Read
17
+ [cleanup reference](../../../.joycraft/references/cleanup.md) for the doc roles,
18
+ the checks, the AGENTS.md trim and the execution playbook.
19
+
20
+ When setup calls this skill, run steps 1–2 only and hand the findings back to
21
+ setup: no report page and no stop. Setup asks about them in its interview and
22
+ shows the agreed fixes on its one diff page.
23
+
24
+ When session end calls this skill, the scope is AGENTS.md, CLAUDE.md, the docs the
25
+ session changed and the context pages they link (the whole project after an
26
+ archive). Run steps 1–3, but the report goes on the session-end page instead of a
27
+ page of its own; run step 4 only for the fixes the user approves there.
28
+
29
+ ## 1. Inventory
30
+
31
+ List every in-scope Markdown file (skip generated, dependency, VCS, installed
32
+ skill and runtime files, and paths the user excludes) with its line count and
33
+ [role](../../../.joycraft/references/cleanup.md#doc-roles): entry, required,
34
+ reference or historical. Follow every reading pointer in the entry docs and mark it
35
+ resolved, dead or external. Rot costs more the more often a file is read. In a
36
+ large repo, do the entry docs and their pointers first, then area by area, and say
37
+ what you have not read.
38
+
39
+ ## 2. Diagnose without editing
40
+
41
+ Run `node .joycraft/runtime/cleanup.mjs` first: exit 2 means findings, and each
42
+ is evidence to confirm, not a verdict. Then read each doc for the six rot
43
+ patterns: completed-work logs, executed plans, internal contradictions, stale
44
+ claims, dead paths, and authority drift. Check every suspected hit against the
45
+ repository (file lookup, search, config, tests, Git history) and record its
46
+ location, the claim, the evidence, your confidence and the smallest disposition:
47
+ keep, correct, condense, move, archive or banner. Code proves what is
48
+ implemented, not what was intended; when a doc may define the contract, report
49
+ the mismatch as unresolved authority drift.
50
+
51
+ Mark the load-bearing content that must survive: hard rules, active decisions,
52
+ recurring traps, do-not-do lines and domain vocabulary.
53
+
54
+ An entry file loads every session, so it holds the project's identity, its rules
55
+ and the context map. When it carries file tables, folder trees, workflow or
56
+ command sections, code or data-flow walkthroughs, or gotcha lists, propose moving
57
+ each into a linked context page with a map row that says when to read it. Never
58
+ propose moving, rewording or reformatting rules: ALWAYS / ASK FIRST / NEVER lists
59
+ and any other must or never section stay exactly as they are. A gotcha that is a
60
+ rule ("Never reference absolute paths") is a rule: it stays.
61
+
62
+ ## 3. Report and stop
63
+
64
+ Order findings by reading frequency × how badly they would mislead. For each,
65
+ give the claim, the evidence, the consequence and the proposed change. Then give
66
+ a per-file plan, list unresolved decisions separately, and name the load-bearing
67
+ content that will remain. Show it as a rendered page (the decision artifact for
68
+ choices, otherwise an HTML page), not only as Markdown in chat.
69
+
70
+ Stop for approval. Until the user approves, change no file in the project: no
71
+ edits, no new pages, no "safe" fixes.
72
+
73
+ ## 4. Execute the approved plan
74
+
75
+ Apply only approved changes, re-checking each fact against the code just before
76
+ writing it, with the playbook in the cleanup reference. Never delete a context
77
+ page to clear a finding; merge or redirect it. When the code does not settle a
78
+ fact, record the question in the owning brief rather than inventing an answer.
79
+ Remove an unknown worktree only after checking it for unmerged work.
80
+
81
+ ## 5. Verify and hand off
82
+
83
+ Run `cleanup.mjs` again. Check that every link in touched files resolves, that
84
+ archives match their sources, that the load-bearing content survives (rules
85
+ byte-identical), that only approved Markdown changed, and that no new
86
+ contradiction appeared. Report the changed files, archive mappings, remaining
87
+ findings with reasons and unresolved decisions. Offer a docs-only commit with a
88
+ specific message; commit only when the user says yes.
@@ -1,14 +1,17 @@
1
1
  ---
2
2
  name: joycraft-context
3
- description: Find and rank relevant project decisions, references and implementation files when a request needs context beyond the current files.
4
- compatibility: Requires Node.js 22+ and the installed .joycraft runtime for retrieval. Git improves tracked-file discovery, with local search fallback.
3
+ description: Find, add, change or remove project context. Use when a request needs decisions, references or files beyond the current ones ("what does the map say about billing?"), when the user says "add this to the project context", "remember that ...", "that's no longer true", "forget/remove that rule", or hands over meeting notes, a screenshot or pasted text whose facts the project should keep.
4
+ compatibility: Requires Node.js 22+ and the installed .joycraft runtime for retrieval and the map check. Git improves tracked-file discovery, with local search fallback.
5
5
  ---
6
6
 
7
7
  Read the project's boundaries and context map first. If these are missing during
8
8
  authorized setup or implementation, use the first-use procedure in
9
9
  [first-use setup](../../../.joycraft/references/setup.md); retrieval alone does not create project
10
- knowledge. Keep read-only research read-only. Use a concrete request to
11
- find local candidates and their bounded snippets:
10
+ knowledge. Keep read-only research read-only.
11
+
12
+ ## Find context
13
+
14
+ Use a concrete request to find local candidates and their bounded snippets:
12
15
 
13
16
  ```sh
14
17
  node .joycraft/runtime/context/cli.mjs --query "<current request>"
@@ -34,3 +37,26 @@ conditional discovery; it is navigation, not a decision authority or constraint.
34
37
  Do not dump entire files, secrets or transcripts into a scoring request. Reuse
35
38
  settled decisions, and surface contradictions affecting scope or consequential
36
39
  choices while continuing understood authorized work.
40
+
41
+ ## Add, change or remove context
42
+
43
+ When the user asks to record, correct or drop project knowledge, or gives you
44
+ notes, a screenshot or pasted text to capture, follow
45
+ [knowledge guidance](../../../.joycraft/references/knowledge.md) and the
46
+ "Changing context" steps in `.joycraft/references/context.md`. In short:
47
+
48
+ 1. Split the input into separate facts. From notes keep only what was settled or
49
+ observed; list action items, open questions and ideas as left out.
50
+ 2. Search the live homes for each subject first. A fact already stated is
51
+ rewritten in place, never stated twice.
52
+ 3. Add: write the fact in its one home. A kind of fact the map has no home for
53
+ gets a new page and a map row with a real "read when".
54
+ 4. Change: rewrite the statement in place; the reason and the replaced choice go
55
+ in a new decision-log entry.
56
+ 5. Remove: delete the live statement wherever it appears and add a decision-log
57
+ entry that names what was removed and why. A page left with no facts is
58
+ deleted together with its map row and any links to it.
59
+ 6. Show the proposed changes as a diff and write only on the user's yes. A
60
+ request that already says to apply the change counts as the yes.
61
+ 7. Run `node .joycraft/runtime/cleanup.mjs` and fix any `missing-path`,
62
+ `unmapped`, `orphan` or `broken-link` finding the change caused.
@@ -18,7 +18,11 @@ decision status or ask for approval again when the session already supplies it.
18
18
  Use `.joycraft/templates/spec.md` and `queue.json` as small starting
19
19
  points. Keep each spec independently testable and put requirement text in stable
20
20
  brief/spec anchors. Each queued criterion points to its source and declares the
21
- needed runtime, visual or structural evidence. A check that only a deployed
21
+ needed runtime, visual or structural evidence. Write each criterion so the
22
+ package's recorded review tools (the `Review loop` section of `AGENTS.md`) can
23
+ check it within their `canShow`. A main claim those tools cannot show at all
24
+ goes back to the brief as a tooling-change question, asked once in the
25
+ interview and recorded; it does not enter the queue. A check that only a deployed
22
26
  environment can show is not a criterion; list it under the spec's "Deferred until
23
27
  deploy" section instead. Include the brief, spec and exact
24
28
  relevant code, test/configuration and fixture paths as verification inputs. Plan
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: joycraft-entry
3
- description: Set up missing project guidance on first use, then turn a repair, feature, or mixed request into a context-backed brief and the next useful action.
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
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.
5
5
  ---
6
6
 
@@ -8,12 +8,23 @@ Run `node .joycraft/runtime/update-check.mjs check` first, once per session. If
8
8
  prints nothing, say nothing. If it prints JSON, follow
9
9
  [updates](../../../.joycraft/references/update.md).
10
10
 
11
+ Then run `node .joycraft/runtime/wiring.mjs --root .`. The CLI cannot write
12
+ the project's context map, because it knows nothing about the project; you
13
+ build it. When the check exits 2, or right after an install, or when the user
14
+ asks to set up Joycraft or check the context map, say in one line that you are
15
+ setting up Joycraft's context map first, follow
16
+ [setup](../../../.joycraft/references/setup.md), then continue the original
17
+ request. A read-only request gets the findings reported, not written.
18
+
19
+ The check's `advice` lists `unmapped-areas`: the areas setup has not read yet,
20
+ kept under `## Not yet mapped` in the project context page. When a request
21
+ touches a listed area, map that area first: read it, propose its map rows and
22
+ homes, write them on the user's yes, and remove the area from the list. Advice
23
+ alone does not start a full setup.
24
+
11
25
  Read existing project instructions first. During an upgrade, inspect the installed
12
26
  manifest’s `legacyConflicts` and reconcile competing old skill discovery before
13
- using routing advice; preserved custom content is not a completed migration. On first use, explicit setup/init, or
14
- when shared guidance or its context pointers are missing, follow
15
- [first-use setup](../../../.joycraft/references/setup.md). Establish the missing knowledge homes
16
- from the current request and repository facts, preserving existing guidance.
27
+ using routing advice; preserved custom content is not a completed migration.
17
28
  On a bare project, offer the
18
29
  [kickoff](../../../.joycraft/references/setup.md#kickoff-for-a-new-project)
19
30
  in one line before any brief or scaffold, and run it when the user asks for it on
@@ -21,8 +32,7 @@ any project. On first entry, setup and upgrade, also run the review-loop plan in
21
32
  [review loop tools](../../../.joycraft/references/setup.md#review-loop-tools);
22
33
  install nothing without the user's yes.
23
34
  Continue the user's work after setup; setup alone does not require a feature
24
- brief, spec queue, app scaffold, or a new interview. A read-only request stays
25
- read-only; report missing setup without writing it.
35
+ brief, spec queue or app scaffold.
26
36
 
27
37
  Before assigning work, read `.joycraft/preferences.json` when it exists. Reuse
28
38
  its explicit model, effort, role, concurrency, and verification choices, then
@@ -60,6 +70,22 @@ Settle each goal's "Done when" with the user while writing the brief; if it
60
70
  cannot be filled yet, record it as an open decision so dependent specs wait for
61
71
  the answer instead of a reviewer discovering it.
62
72
 
73
+ **Review defaults stay strict.** Every feature starts with the review loop on
74
+ and its tools required. Record a waiver only from the user's own words in that
75
+ feature's interview: put them in the note of a settled brief decision and write
76
+ the feature's `waiver.json` naming that decision, before any review runs
77
+ (`.joycraft/references/completion.md`). A `no-review` waiver blocks reviewer
78
+ dispatch for the feature. Never propose or ask about one, and never carry it
79
+ into the next feature.
80
+
81
+ **Feature sessions stay quiet about the review loop.** A feature interview
82
+ asks nothing about review tools: read the recorded `## Review loop` and write
83
+ criteria its tools can check. Ask once, before any spec, only when the
84
+ feature's main claim needs something the recorded tools cannot show (a drag on a
85
+ screenshots-only tool). That is a tooling change: follow
86
+ [change a tool](../../../.joycraft/references/setup.md#review-loop-tools) and
87
+ record the answer, so it is not asked again.
88
+
63
89
  **Ask answerable questions in an artifact.** When the user must choose between
64
90
  options, record each choice as a brief decision and render the open decisions
65
91
  with the decision artifact (`.joycraft/references/artifacts.md`). Do not list
@@ -74,7 +100,8 @@ says `docs/features`, `docs/archive` or `docs/context`.
74
100
 
75
101
  **Show documents as pages.** A brief, plan, spec set or review that the user must
76
102
  read or approve is also rendered, never left as Markdown in chat: the decision
77
- artifact for a brief, an HTML page for anything else. Open it and say where it is.
103
+ artifact for a brief, an HTML page for anything else. Show it as
104
+ [showing a page](../../../.joycraft/references/artifacts.md#showing-a-page) says and give its path.
78
105
  If the project's `AGENTS.md` lacks this rule or its context-map row for
79
106
  `.joycraft/references/artifacts.md`, add them as `setup.md` describes.
80
107
 
@@ -81,6 +81,22 @@ If it returns unenforced, or a separate review context/capability is unavailable
81
81
  leave the spec `in-review`; do not invent an ID or prompt to continue. This holds
82
82
  the claimed review, not unrelated authorized or hooks-disabled/manual work.
83
83
 
84
+ When a recorded tool breaks during a run (the dev server does not start, a
85
+ port is taken, the browser or simulator crashes), repair it with what the user
86
+ already agreed to: restart the dev server, free the port, relaunch the browser
87
+ or simulator, then retry once. A repair never installs, upgrades or
88
+ reconfigures anything; that needs the user's yes. If the repair fails, record an
89
+ `UNVERIFIED` observation with `cause: 'tool-break'` and the reason, leave that
90
+ spec `in-review`, and continue with the specs that do not depend on it. At the
91
+ first hold, tell the user in the conversation while workers run: the spec, the
92
+ tool, the cause and the repair tried. The session-end summary lists every held
93
+ spec again.
94
+
95
+ A tool break stops the whole queue only when the project will not build or
96
+ install, the worktree or repository is broken, or the next step would touch data
97
+ or systems outside the project (a shared database, a deploy). Every other tool
98
+ break is repair, then hold.
99
+
84
100
  Only the guarded completion path can move an `in-review` spec to `done`. Use its manual snapshot/complete commands only at an explicit non-native boundary; read [completion guidance](../../../.joycraft/references/completion.md) before doing so.
85
101
 
86
102
  When a current independent review is `FAIL` or `UNVERIFIED`, first fix
@@ -23,7 +23,7 @@ force local state to a remote tip. Start a replacement only from the durable
23
23
  run journal and a newly printed dispatch plan. This guidance describes the
24
24
  project/native runtime boundary; it does not enforce lifecycle behavior.
25
25
 
26
- 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.
26
+ 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
27
 
28
28
  If a completion operation failed or was interrupted, do not declare success or hand-edit statuses. Retain the helper's error and journal/recovery information, then use the bounded local recovery process in [completion guidance](../../../.joycraft/references/completion.md). It only restores the two status surfaces and accepted-report receipt captured by the journal; it does not retry unrelated work.
29
29
 
@@ -35,8 +35,6 @@ any feature listed as ready to archive. Then preview
35
35
  `node .joycraft/runtime/worktrees.mjs prune` and apply it with `--apply`: it
36
36
  removes only clean, integrated trees of done specs and keeps failed, blocked or
37
37
  unknown trees with their reason. Report kept trees and their size from `list`.
38
- Then run `node .joycraft/runtime/cleanup.mjs` and report its findings; offer
39
- `joycraft-cleanup` when any remain.
40
38
  When this session coordinated a queue and no work on it remains, release the
41
39
  lease with `node .joycraft/runtime/coordinator.mjs release --queue <queue> --session <your-session-id>`. See [worker isolation](../../../.joycraft/references/worktrees.md)
42
40
  when the session used parallel mutable workers.
@@ -46,7 +44,14 @@ that condition and arrange a fresh review after it is corrected. Do not create
46
44
  an unchanged-code fix round. The existing completion process remains the sole
47
45
  owner of acceptance and status changes.
48
46
 
49
- Before archival, update the existing owning context reference and its pointers only when accepted work established reusable project knowledge: record the affected boundary, current coupled sources, observable check, and known limit. Keep accepted observations distinct from proposals, and leave product choices in the brief's decision authority rather than copying them into a competing context record. Do not create a global map or rewrite unrelated context for a local change.
47
+ Before ending, and before any archival, route each reusable fact the session established (a decision with its reason, a trap, a reference, a production fact) to its one home per [knowledge guidance](../../../.joycraft/references/knowledge.md). Rewrite a changed fact in place and put its reason in the decision log; add a context-map row for a new home; keep each touched row's "read when" true. Leave feature intent in the brief. A session with nothing reusable changes no context file.
48
+
49
+ Then audit the docs without being asked: run `joycraft-cleanup` in its
50
+ session-end mode. Its scope is AGENTS.md, CLAUDE.md, every doc this session
51
+ changed and the context pages they link; after a feature is archived, the whole
52
+ project. Put its findings on the session-end page with the rest of the report and
53
+ apply only the fixes the user approves there. With no findings, say so in one
54
+ line.
50
55
 
51
56
  When independent reports suggest a reusable failure lesson, use the compact, conditional process in [recurring failure guidance](../../../.joycraft/references/recurring-failures.md): keep only a source-linked shortlist in active task material, inspect current sources before relying on history, and route any proposed lesson as exact next-worker inputs through the existing dispatch path.
52
57
 
@@ -25,11 +25,13 @@ remain valid; only assertions intended to detect the new behavior need meaningfu
25
25
  red/green. If a red check was not run, say so. Do not weaken assertions to obtain
26
26
  green or alter unrelated tests to manufacture universal failure.
27
27
 
28
- For UI requirements, use the tools and commands in the `Review loop` section of
29
- `AGENTS.md` (also in the worker packet as `reviewLoop`); a tool it marks skipped
30
- or missing leaves that UI claim UNVERIFIED.
31
- Render and inspect the relevant route, state and viewport.
32
- Perform the interactions the claim needs and observe their outcomes. Fix observed
28
+ For UI requirements, use the package's recorded tool and commands from the
29
+ worker packet's `reviewLoop` (the `Review loop` section of `AGENTS.md`, plus
30
+ `local` host tools), within its `canShow`. A claim beyond `canShow`, or in a
31
+ package the user skipped, is an agreed limit, not UNVERIFIED: check what the
32
+ tool can show and say how you checked. Render and inspect the relevant route,
33
+ state and viewport. When the tool can interact, perform the interactions the
34
+ claim needs and observe their outcomes. Fix observed
33
35
  problems within scope, then rerender and reinspect affected states. A saved
34
36
  screenshot, DOM check or browser launch alone is not visual inspection. Preserve
35
37
  tool access boundaries: if a check is blocked or unavailable, record UNVERIFIED
@@ -19,9 +19,10 @@ current render cannot answer them. Otherwise build or modify the smallest runnab
19
19
  slice in the project's actual stack. Show the consequential state and a useful
20
20
  interaction when interaction matters. One viewport is a useful starting size, not
21
21
  a rule for all products. Put explanatory detail behind disclosure. The slice is
22
- exploration, not production approval. Render and inspect it early with permitted
23
- browser tools; record the route, state, viewport, interactions and observed
24
- outcomes. If blocked, record UNVERIFIED and the reason; respect denials without
22
+ exploration, not production approval. Render and inspect it early with the
23
+ package's recorded review tool (`Review loop` in `AGENTS.md`) or the host's
24
+ permitted tools; record the route, state, viewport, interactions the tool can
25
+ perform and observed outcomes. If blocked, record UNVERIFIED and the reason; respect denials without
25
26
  alternate access routes.
26
27
 
27
28
  The optional local helper below needs the installed shared runtime. If it is
@@ -51,7 +51,7 @@ weakened assertions that could hide the requested behavior.
51
51
 
52
52
  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
53
 
54
- Create a schema-v1 verification report tied to that subject, using the shared fields in [.joycraft/contracts/types.d.ts](../../../.joycraft/contracts/types.d.ts). For every declared criterion, provide PASS observations for its required evidence kinds. Keep unfiltered command output and its real exit status in hashed, project-relative receipts. A source scan supports only structural observations. Visual observations require a reviewer-inspected render plus route, state, viewport, interactions, and outcomes; take the render with the tools and start command in the packet's `reviewLoop` (the `Review loop` section of `AGENTS.md`), and mark a claim whose tool is skipped or missing `UNVERIFIED`. Mark unavailable inspection, a failing result, or an unresolved concern as `UNVERIFIED` or `FAIL` truthfully.
54
+ Create a schema-v1 verification report tied to that subject, using the shared fields in [.joycraft/contracts/types.d.ts](../../../.joycraft/contracts/types.d.ts). For every declared criterion, provide PASS observations for its required evidence kinds. Keep unfiltered command output and its real exit status in hashed, project-relative receipts. A source scan supports only structural observations. Visual observations require a reviewer-inspected render plus route, state, viewport, interactions, and outcomes. Take evidence with the package's recorded tool, start command and evidence command from the packet's `reviewLoop` (`section`: the `Review loop` section of `AGENTS.md`; `local`: this machine's host tools), within that tool's `canShow`. A claim beyond `canShow`, or in a package the user skipped, is an agreed limit, not `UNVERIFIED`: check what the agreed tool can show, say in plain words how you checked, and leave what is left to the parent agent. A picture-only tool gives `interactions: []`. `UNVERIFIED` means a check that should have run and did not: the tool broke, the app did not start, or a render was saved but not inspected. On a tool break, first repair with what the user agreed to: restart the dev server, free the port, relaunch the browser or simulator, retry once. A repair never installs, upgrades or reconfigures anything. If it still fails, record `UNVERIFIED` with `cause: 'tool-break'` and the reason. Mark a failing result or an unresolved concern as `FAIL` or `UNVERIFIED` truthfully.
55
55
 
56
56
  Run each test command once in single-run mode with `CI=1` and a 300000 ms
57
57
  timeout; follow [running tests](../../../.joycraft/references/testing.md#running-tests)
@@ -34,6 +34,11 @@ criterion by what you observe.
34
34
  Report every finding with a severity and the criterion it touches. Only a failing
35
35
  stated criterion, or a reproducible defect or regression in the changed code with
36
36
  file:line or a receipt, blocks. A case the spec does not decide is "decision
37
- needed", not FAIL. Do not repeat an earlier round's finding as new. Record only
38
- what you observed; mark anything unobserved UNVERIFIED. Keep the final message
37
+ needed", not FAIL. Do not repeat an earlier round's finding as new.
38
+
39
+ Take evidence with each package's recorded tool from the packet's `reviewLoop`,
40
+ within its `canShow`, and say in plain words how you checked. A limit the user
41
+ agreed to (a claim beyond `canShow`, or a package the user skipped) is not
42
+ UNVERIFIED; the parent agent judges what is left. UNVERIFIED is a check that
43
+ should have run and did not. Record only what you observed. Keep the final message
39
44
  short: verdict, blocking findings, decision-needed items, report path.
@@ -61,6 +61,14 @@ html[data-jca-theme] body { margin: 0; background: var(--canvas); color: var(--i
61
61
  .jca-message-success { border-color: var(--accent); background: var(--accent-soft); }
62
62
  .jca-message-quiet { color: var(--muted); }
63
63
  .jca-actions { display: flex; flex-wrap: wrap; gap: .55rem; margin: .8rem 0 1rem; }
64
+ .jca-source-notice { margin: 1.2rem 0; padding: .8rem 1rem; border: 1px solid var(--accent); border-left-width: 4px; border-radius: 8px; background: var(--accent-soft); font-size: .92rem; }
65
+ .jca-source-notice h2 { margin: 0 0 .45rem; font-size: 1rem; }
66
+ .jca-source-notice p, .jca-source-notice ul { margin: .4rem 0; }
67
+ .jca-source-notice a { color: var(--accent); }
68
+ .jca-source-notice-error { border-color: var(--error); background: var(--error-bg); }
69
+ .jca-source-notice-error h2, .jca-source-notice-error > p:first-of-type { color: var(--error); }
70
+ .jca-changed { margin: 0 0 1rem; color: var(--error); font-size: .9rem; font-weight: 650; }
71
+ .jca-visually-hidden { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }
64
72
  .joycraft-artifact button { appearance: none; border: 1px solid var(--control-line); border-radius: 8px; padding: .56rem .82rem; color: var(--accent); background: var(--paper); font: inherit; font-size: .88rem; font-weight: 600; cursor: pointer; }
65
73
  .joycraft-artifact button:hover { border-color: var(--accent); background: var(--accent-soft); }
66
74
  .joycraft-artifact .jca-save-one, .joycraft-artifact [data-jca-save-all] { color: var(--accent-text); background: var(--accent); border-color: var(--accent); }