joycraft 1.1.1 → 1.1.2

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 (29) 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-entry/SKILL.md +19 -8
  9. package/payload/.agents/skills/joycraft-session-end/SKILL.md +8 -3
  10. package/payload/.joycraft/assets/artifacts/kit.css +8 -0
  11. package/payload/.joycraft/assets/artifacts/kit.js +163 -21
  12. package/payload/.joycraft/assets/artifacts/transports.js +14 -3
  13. package/payload/.joycraft/references/artifacts.md +21 -2
  14. package/payload/.joycraft/references/cleanup.md +109 -3
  15. package/payload/.joycraft/references/context.md +64 -2
  16. package/payload/.joycraft/references/doc-cleanup-LICENSE.md +23 -0
  17. package/payload/.joycraft/references/knowledge.md +58 -0
  18. package/payload/.joycraft/references/setup.md +128 -138
  19. package/payload/.joycraft/references/update.md +5 -3
  20. package/payload/.joycraft/runtime/artifacts/decisions.mjs +16 -5
  21. package/payload/.joycraft/runtime/artifacts/server.mjs +14 -1
  22. package/payload/.joycraft/runtime/cleanup.mjs +95 -8
  23. package/payload/.joycraft/runtime/config.mjs +5 -3
  24. package/payload/.joycraft/runtime/review-tools.mjs +55 -8
  25. package/payload/.joycraft/runtime/update-check.mjs +38 -8
  26. package/payload/.joycraft/runtime/wiring.mjs +156 -0
  27. package/payload/.joycraft/templates/joycraft.yaml +2 -0
  28. package/payload/.joycraft/templates/project-context.md +6 -1
  29. package/payload/PIN +25 -22
@@ -7,6 +7,13 @@
7
7
  var QUESTION_STATES = new Set(['open', 'assigned', 'clarified', 'settled', 'backlogged', 'discarded']);
8
8
 
9
9
  function fail(message) { throw new Error(message); }
10
+ // A stale-source rejection: the page should reload the source and keep the person's drafts.
11
+ function conflict(message, details) {
12
+ var error = new Error(message);
13
+ error.conflict = true;
14
+ Object.keys(details || {}).forEach(function (key) { error[key] = details[key]; });
15
+ throw error;
16
+ }
10
17
  function nonempty(value) { return typeof value === 'string' && value.trim().length > 0; }
11
18
  function own(object, key) { return Object.prototype.hasOwnProperty.call(object, key); }
12
19
 
@@ -49,7 +56,7 @@
49
56
  if (note !== undefined && typeof note !== 'string') fail('Answer notes must be strings.');
50
57
  if (note !== undefined && note.length > MAX_NOTE_LENGTH) fail('Answer notes cannot exceed 4000 characters.');
51
58
  if (option.requiresNote && !nonempty(note)) fail('This answer requires a note.');
52
- if (mutation && question.status === 'clarified' && (question.answer !== response.answer || (question.note || '') !== (note || ''))) fail('Clarified responses can only be replayed exactly.');
59
+ if (mutation && question.status === 'clarified' && question.answer !== response.answer) fail('Reopen this decision to change its answer. Its note can change at any time.');
53
60
  seen.add(response.id);
54
61
  var answer = { id: response.id, answer: response.answer };
55
62
  if (note !== undefined && note !== '') answer.note = note;
@@ -90,7 +97,7 @@
90
97
  }
91
98
 
92
99
  function responseRevision(model, revision) {
93
- if (revision !== model.source.revision) fail('Source changed. Refresh before saving responses.');
100
+ if (revision !== model.source.revision) conflict('Source changed after this page loaded. Reload it before saving responses.', { revision: model.source.revision });
94
101
  }
95
102
 
96
103
  function requestedAnswers(model, request) {
@@ -128,7 +135,11 @@
128
135
  try { payload = await response.json(); } catch (_) { fail('Local response service returned invalid JSON.'); }
129
136
  if (!response || !response.ok) {
130
137
  var detail = payload && (payload.error || payload.message);
131
- fail(typeof detail === 'string' && detail ? detail : 'Local response service rejected the request' + (response && response.status ? ' (' + response.status + ')' : '') + '.');
138
+ var text = typeof detail === 'string' && detail ? detail : 'Local response service rejected the request' + (response && response.status ? ' (' + response.status + ')' : '') + '.';
139
+ if (payload && payload.conflict) conflict(text, { status: response.status, revision: payload.revision, viewRevision: payload.viewRevision });
140
+ var error = new Error(text);
141
+ if (response && response.status) error.status = response.status;
142
+ throw error;
132
143
  }
133
144
  return payload;
134
145
  }
@@ -14,13 +14,32 @@ artifact CSS, JavaScript, or a second copy of the brief. Keep questions useful:
14
14
  one material choice can be enough. Use the existing product UI slice for a
15
15
  choice that depends on trying the actual product behavior.
16
16
 
17
+ ## Showing a page
18
+
19
+ Every page a person must read or answer (a decision artifact, a setup diff, a
20
+ review) is shown where they are working, and you always say its path:
21
+
22
+ 1. **The host has a viewer.** When your tools include one (the Claude Code
23
+ desktop app's browser pane or artifact tool, an editor preview), open the
24
+ page there. Do not hand it to the system browser.
25
+ 2. **A person at a terminal, no viewer.** Open it in the system browser (`open`,
26
+ `xdg-open` or `start`).
27
+ 3. **No person watching.** In a non-interactive run (`claude -p`, `codex exec`,
28
+ CI), open nothing; print the path. Signals: `CLAUDE_CODE_SESSION_ATTENDED=0`,
29
+ `CODEX_CI=1`, `CI` set, or no terminal. These beat `CLAUDE_CODE_ENTRYPOINT`,
30
+ which a nested run inherits from the app that started it.
31
+
17
32
  ## Decisions and view data
18
33
 
19
34
  A brief decision keeps its existing `id`, `status`, `question`, `answer`,
20
35
  `options`, and `affected` fields. Artifact views also support an optional
21
36
  `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
37
+ short explanation. Every question also offers "Something else" (value `custom`,
38
+ note required), so the person can always answer in their own words; do not
39
+ declare it unless you want different wording. The canonical answer remains an
40
+ option `value`, including `custom`. A saved answer keeps its note box: the
41
+ person can add or change the note and save again without reopening. Changing
42
+ the chosen answer still needs a reopen. Store the human's exact words separately as that
24
43
  decision's note; never replace the canonical answer with free-form text.
25
44
 
26
45
  The view data has this shape:
@@ -10,6 +10,9 @@
10
10
  | `working-link` | `AGENTS.md`, `CLAUDE.md` or a context page linking into `paths.features` or `paths.archive` | Move the fact into the context home and link that |
11
11
  | `broken-link` | A Markdown link to a file that does not exist | Fix or remove the link |
12
12
  | `orphan` | A context page that nothing in `AGENTS.md`, `CLAUDE.md` or the context home mentions | Add a context-map row with a "read when", or merge the page |
13
+ | `missing-path` | A backticked project path in `AGENTS.md`, `CLAUDE.md` or a context page that does not exist | Point it at the current path, or drop the line |
14
+ | `unmapped` | A context page that only other context pages mention; no entry file links or names it | Add a context-map row with a "read when", or merge the page |
15
+ | `entry-size` | `AGENTS.md` or `CLAUDE.md` over `cleanup.entryWords` words (default 1000) | Move detail into context pages; leave a map row for each |
13
16
  | `impact-drift` | A page mapped in `cleanup.impact` whose code changed in commits after the page last changed | Read the change; update the page, or commit it unchanged when still true |
14
17
  | `stale-after` | An OKF `stale_after` date that has passed | Recheck, then move the date or mark the page `deprecated` |
15
18
  | `deprecated-link` | A link to a page marked `status: deprecated` | Link the current page |
@@ -18,7 +21,16 @@
18
21
 
19
22
  Fenced code blocks are ignored. Inline, reference-style and `<angle>` links count.
20
23
  Backticked paths such as `` `docs/context/x.md` `` count as references for
21
- `orphan` and `working-link`; only real Markdown links are checked for existence.
24
+ `orphan`, `unmapped` and `working-link`. `broken-link` checks Markdown links;
25
+ `missing-path` checks backticked spans that read as project paths: they contain a
26
+ `/` and end in `/`, have a file extension, or start with an existing top-level
27
+ folder. It skips spans with spaces, globs (`*`), placeholders (`<slug>`, `[slug]`,
28
+ `{x}`, `$VAR`, `...`), URLs and other `:` forms, and absolute, `~` or `../` paths.
29
+ A path in a context page may be relative to the project root or to the page.
30
+ History pages are exempt from `missing-path`, because they rightly name paths that
31
+ were later removed: a page whose frontmatter has `type: log` or `type: history`,
32
+ and any file named `decision-log.md` or `shipped*.md`. Their links are still
33
+ checked.
22
34
 
23
35
  The impact map lives in `joycraft.yaml`:
24
36
 
@@ -31,5 +43,99 @@ cleanup:
31
43
 
32
44
  `*` matches within a folder and `**` across folders. A page with no commit yet is
33
45
  skipped. Pages may carry OKF frontmatter (`type`, `status`, `stale_after`,
34
- `verified`); cleanup reads `status` and `stale_after` when present. For a fuller
35
- doc audit, such as docaudit, run it from `hooks.afterArchive`.
46
+ `verified`); cleanup reads `status` and `stale_after` when present, and `type`
47
+ for the history exemption above.
48
+
49
+ ## Doc roles
50
+
51
+ Inventory gives every in-scope doc one role:
52
+
53
+ - **entry**: `AGENTS.md` and `CLAUDE.md`, loaded every session.
54
+ - **required**: an entry doc says to read it.
55
+ - **reference**: read when a task needs it; it gets a context-map row.
56
+ - **historical**: kept for lookup, not guidance; it gets no map row.
57
+
58
+ ## The six rot patterns
59
+
60
+ From doc-cleanup. Test every in-scope doc for each; a doc claim is a hypothesis
61
+ and the code is the evidence.
62
+
63
+ 1. **Completed-work logs.** Finished checklists, phase logs, implementation
64
+ narratives, post-mortems and verification transcripts presented as guidance.
65
+ 2. **Executed plans.** A shipped plan still written as intent, with its
66
+ superseded analysis and rejected options.
67
+ 3. **Internal contradictions.** One fact with two values, a stale table corrected
68
+ by a note below it, dated addenda that reverse earlier text.
69
+ 4. **Stale claims.** Renamed symbols, changed constants, wrong line numbers, work
70
+ called unmerged after it landed.
71
+ 5. **Dead paths.** Missing files, old machine paths, moved repositories, removed
72
+ tools.
73
+ 6. **Authority drift.** A "source of truth" that no longer matches the code or a
74
+ later decision.
75
+
76
+ Each phase has an end:
77
+ - **Inventory** ends when every in-scope Markdown file has a role and every entry
78
+ pointer is resolved, dead or external.
79
+ - **Diagnose** ends when every inventoried file has an evidence-backed finding or
80
+ is marked clean. Files `cleanup.mjs` did not flag still get read.
81
+ - **Report** ends when the user can approve, reject or amend each change without
82
+ more investigation.
83
+ - **Execute** ends when each approved finding has a diff or a stated reason for
84
+ none, and each retained claim was re-checked.
85
+
86
+ ## Trimming an entry file
87
+
88
+ `AGENTS.md` and `CLAUDE.md` load into every session. They keep the project's
89
+ identity (a line or two on what it is), its rules, the Joycraft lines and the
90
+ context map. Propose moving the rest into context pages, each with a map row:
91
+
92
+ | In the entry file | Move to |
93
+ |---|---|
94
+ | Key-files or module tables | A codebase reference page, e.g. `docs/context/codebase.md` |
95
+ | Folder trees and architecture maps | The same page, or `docs/context/architecture.md` |
96
+ | Data-flow and code walkthroughs | The same page, beside the files they walk through |
97
+ | Setup, build, test and release workflows | `docs/context/workflow.md`; keep one test-command line in the entry if the rules need it |
98
+ | Gotchas and traps that are not rules | The project's traps page (see knowledge guidance), each as a short imperative |
99
+
100
+ Reuse a page the map already has before creating one, and create a page only
101
+ with the content it receives. Rules never move and are never reworded,
102
+ reordered or reformatted: ALWAYS / ASK FIRST / NEVER lists and any other section
103
+ that says what an agent must or must not do (release rules, holdout or
104
+ confidentiality rules). If a rule is also stale, report it as a finding for the
105
+ user to decide; do not fix it as part of the trim. After a move, the entry file
106
+ names each new page in the map, and `cleanup.mjs` reports no `unmapped` or
107
+ `orphan` page for it.
108
+
109
+ ## Execution playbook
110
+
111
+ Re-check each factual claim against the code immediately before writing it.
112
+
113
+ - **Archive history worth finding again.** Put a verbatim copy, or a clearly
114
+ bounded extract, under `paths.archive` with a source-and-date name, and record
115
+ the source path and Git blob hash in the report. Git history alone is enough
116
+ when nobody will look for it. A finished feature folder is archived only
117
+ through the session-end path (`archive.md`), after its durable facts reach the
118
+ context home.
119
+ - **Rewrite live guidance as current facts**, following
120
+ [knowledge guidance](knowledge.md): rewrite in place, reason to the decision
121
+ log, no addenda. Live pages never link the archive (`working-link`); record
122
+ each archive mapping in the cleanup report and the commit message instead.
123
+ - **Point to authorities.** Name the owning schema, config or source file instead
124
+ of copying values that change.
125
+ - **Condense completed work.** Replace a finished checklist with its outcome;
126
+ keep open items in their original words.
127
+ - **Preserve traps.** Keep each recurring gotcha as a short imperative before
128
+ moving the story of how it was found.
129
+ - **Banner unresolved drift.** When the code and a contract-like doc disagree and
130
+ the repository does not show which governs, add a short banner naming the
131
+ mismatch and the authority in force; do not rewrite the contract.
132
+ - **Repair entry docs.** Fix dead reading pointers and stale claims, apply the
133
+ approved trim, and keep the required-reading set small.
134
+
135
+ ## Verify
136
+
137
+ Every relative link in touched files resolves; archives match their sources
138
+ byte for byte (extracts match their recorded bounds); load-bearing content found
139
+ in diagnosis survives in live guidance, with rules byte-identical; the diff holds
140
+ only approved Markdown changes; no new contradiction appears across touched docs;
141
+ `cleanup.mjs` reports nothing new.
@@ -1,4 +1,11 @@
1
- # Project context ranking
1
+ # Project context
2
+
3
+ ## Contents
4
+
5
+ - [Finding context](#finding-context)
6
+ - [Changing context](#changing-context)
7
+
8
+ ## Finding context
2
9
 
3
10
  From the consumer Git project root:
4
11
 
@@ -81,5 +88,60 @@ advise reading order and never approve intent, authorize work or certify evidenc
81
88
 
82
89
  Treat only the context homes as current authority. `docs/features/` is working
83
90
  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
91
+ history; see [knowledge guidance](knowledge.md) for which home holds what. Joycraft ships no wiki. Skills
85
92
  do not need to be named by the user: pick the step from the request.
93
+
94
+ ## Changing context
95
+
96
+ The same skill writes project knowledge when the user asks: "add this to the
97
+ project context", "remember that ...", "forget that rule", or a meeting note,
98
+ screenshot or pasted text to capture. `knowledge.md` owns the rule (one home per
99
+ fact, current state only, reasons in the decision log, history in the archive);
100
+ these steps apply it to a request.
101
+
102
+ **Read the map and homes.** Start from the context map in `AGENTS.md` (or the
103
+ project's own map). Search the live homes, not `docs/features/` or
104
+ `docs/archive/`, for the subject of each fact: a different wording of the same
105
+ rule counts as the same fact.
106
+
107
+ **Turn input into facts.** A meeting note, screenshot or pasted thread usually
108
+ holds several facts and some noise. Keep each statement that was settled or
109
+ observed: a decision and its reason, a trap and how to avoid it, a reference, a
110
+ production fact. Leave out action items, open questions, ideas nobody decided
111
+ on, attendance and opinions; name them in the proposal as left out, so the user
112
+ can correct the cut. For a screenshot, read the facts from what it shows and
113
+ say which ones you could not read. Do not copy the raw note into the project,
114
+ and do not keep a link to it as a source: the homes state the facts themselves.
115
+
116
+ **Add.** Route each fact by the table in `knowledge.md` to the home the map
117
+ already names for that kind. When the map has no home for it, create a focused
118
+ page under the context folder with the fact and add a map row whose "read when"
119
+ names the work that needs it, not the page's title. Write a decision's current
120
+ choice in the home that owns its area and its reason and rejected options as a
121
+ decision-log entry. A widened home keeps a "read when" that covers its new
122
+ content.
123
+
124
+ **Change.** Rewrite the existing statement in place. Add a decision-log entry
125
+ that names the old choice, the new one and why. Leave no dated addendum,
126
+ "previously" note or struck-through text in the live home.
127
+
128
+ **Remove.** Delete the statement from every live home that holds it, including
129
+ copies in `AGENTS.md`. Add a decision-log entry headed with what was removed,
130
+ with the user's reason; when the user gives none, ask, and in a pre-approved
131
+ non-interactive run write that it was removed at the user's request. An older
132
+ decision-log entry that chose the rule stays as history; the new entry records
133
+ that it no longer applies. When the page that held it has no facts left, delete
134
+ the page, its map row and every link or backticked mention of it. Do not leave
135
+ an empty page, a row to a missing file or a "removed" note in a live home.
136
+
137
+ **Approve, then write.** Before writing, show each affected file and the change
138
+ as a unified diff (or the new file in full), the home chosen for each fact, and
139
+ anything left out. Write only after the user says yes, and only what they
140
+ approved. A prompt that already approves the change, as in a scripted run, is
141
+ that yes; still show what you wrote afterwards.
142
+
143
+ **Check the map.** Run `node .joycraft/runtime/cleanup.mjs`. The change must not
144
+ add a `missing-path`, `unmapped`, `orphan`, `broken-link` or `working-link`
145
+ finding; fix any it did. Report findings that were already there without fixing
146
+ them unless the user asks. Every page you created or edited must be reachable
147
+ from the map.
@@ -0,0 +1,23 @@
1
+ License for the doc-cleanup method adapted in joycraft-cleanup, from https://github.com/aka-luan/doc-cleanup (commit 69dcb95):
2
+
3
+ MIT License
4
+
5
+ Copyright (c) 2026 aka-luan
6
+
7
+ Permission is hereby granted, free of charge, to any person obtaining a copy
8
+ of this software and associated documentation files (the "Software"), to deal
9
+ in the Software without restriction, including without limitation the rights
10
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11
+ copies of the Software, and to permit persons to whom the Software is
12
+ furnished to do so, subject to the following conditions:
13
+
14
+ The above copyright notice and this permission notice shall be included in all
15
+ copies or substantial portions of the Software.
16
+
17
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23
+ SOFTWARE.
@@ -0,0 +1,58 @@
1
+ # Project knowledge stays current
2
+
3
+ The context map in `AGENTS.md` (or the project's own map) is the index of project
4
+ memory. Each row points to one home for one kind of knowledge and says when to
5
+ read it. An agent that starts fresh, after a compaction or in a new session,
6
+ reads the homes as the current state of the project. It must never have to replay
7
+ a chain of past decisions to learn how things are today.
8
+
9
+ ## The rule
10
+
11
+ - **One home per fact.** Other pages link to it; they do not copy it.
12
+ - **Homes state what is true now.** When a fact changes, rewrite the statement in
13
+ place. Do not add a dated addendum, a "superseded by" or "previously" note,
14
+ struck-through text, or a footnote that corrects a stale table.
15
+ - **Why goes to the decision log.** The reason and the rejected options go in an
16
+ entry in the decision log (default `docs/context/decision-log.md`). A changed
17
+ decision gets a new entry that names the choice it replaces. The live home
18
+ carries only the current statement.
19
+ - **History stays out of live homes.** The old value of a changed fact lives in
20
+ its decision-log entry and in Git. Finished features go to the archive at
21
+ session end (`archive.md`); they stay there for regression checks and are never
22
+ read as current truth.
23
+ - **Check before you restore.** Do not copy a statement from the archive or from
24
+ an old decision-log entry back into a live home until you have checked it
25
+ against the code.
26
+ - Record what the work established or observed. Keep proposals and guesses out.
27
+
28
+ ## Routing a fact at session end
29
+
30
+ A reusable fact is one a later session needs and cannot cheaply get from the
31
+ code. Use the home the map already names for that kind. Use the default only when
32
+ the map has no home for it.
33
+
34
+ | Fact | Home |
35
+ |---|---|
36
+ | What the project is (purpose, users, owners, constraints), and the areas setup has not mapped yet | `docs/context/project.md` (from `.joycraft/templates/project-context.md`) |
37
+ | Navigation across code boundaries (where a flow lives) | A focused reference page linked by the map, e.g. `docs/context/architecture.md` |
38
+ | Decision | Current choice in the home that owns that area; reason and rejected options in the decision log |
39
+ | Trap (something that misleads or breaks, and how to avoid it) | The project's troubleshooting or gotchas page, default `docs/context/traps.md` |
40
+ | Reference (where something lives, how to run or look it up) | A focused reference page linked by the map |
41
+ | Production fact (deploy, environments, data, external services) | The production page, default `docs/context/production.md` |
42
+ | Feature intent and product choices for live work | The feature brief; do not copy them into a context home |
43
+
44
+ For each fact:
45
+
46
+ 1. Find its home through the map. If the home already states it, rewrite that
47
+ statement in place.
48
+ 2. If no home holds that kind of fact, create the page with the fact and add a
49
+ map row with a "read when". Do not create empty pages.
50
+ 3. If a change widens or narrows what a home covers, edit its row so the "read
51
+ when" stays true.
52
+
53
+ Then check that every page you created or edited is reachable from the map, that
54
+ no link points into `docs/features/` or `docs/archive/`, and that no live home
55
+ holds a dated addendum or "superseded" note (`node .joycraft/runtime/cleanup.mjs`
56
+ reports unmapped pages and broken or working-material links).
57
+
58
+ A session with nothing reusable changes no context file.