joycraft 1.1.0 → 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.
- package/README.md +57 -16
- package/dist/cli.js +50 -9
- package/dist/cli.js.map +1 -1
- package/dist/joycraft-release.json +1 -1
- package/package.json +3 -3
- package/payload/.agents/skills/joycraft-cleanup/SKILL.md +81 -34
- package/payload/.agents/skills/joycraft-context/SKILL.md +30 -4
- package/payload/.agents/skills/joycraft-entry/SKILL.md +19 -8
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +8 -3
- package/payload/.joycraft/assets/artifacts/kit.css +8 -0
- package/payload/.joycraft/assets/artifacts/kit.js +163 -21
- package/payload/.joycraft/assets/artifacts/transports.js +14 -3
- package/payload/.joycraft/references/artifacts.md +21 -2
- package/payload/.joycraft/references/cleanup.md +109 -3
- package/payload/.joycraft/references/context.md +64 -2
- package/payload/.joycraft/references/doc-cleanup-LICENSE.md +23 -0
- package/payload/.joycraft/references/knowledge.md +58 -0
- package/payload/.joycraft/references/setup.md +128 -138
- package/payload/.joycraft/references/update.md +5 -3
- package/payload/.joycraft/runtime/artifacts/decisions.mjs +16 -5
- package/payload/.joycraft/runtime/artifacts/server.mjs +14 -1
- package/payload/.joycraft/runtime/cleanup.mjs +114 -9
- package/payload/.joycraft/runtime/config.mjs +8 -4
- package/payload/.joycraft/runtime/coordinator.mjs +28 -5
- package/payload/.joycraft/runtime/review-tools.mjs +55 -8
- package/payload/.joycraft/runtime/status.mjs +2 -2
- package/payload/.joycraft/runtime/trace.mjs +8 -3
- package/payload/.joycraft/runtime/update-check.mjs +38 -8
- package/payload/.joycraft/runtime/wiring.mjs +156 -0
- package/payload/.joycraft/runtime/worktrees.mjs +9 -7
- package/payload/.joycraft/templates/joycraft.yaml +2 -0
- package/payload/.joycraft/templates/project-context.md +6 -1
- package/payload/PIN +29 -26
|
@@ -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' &&
|
|
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)
|
|
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
|
-
|
|
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.
|
|
23
|
-
|
|
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
|
|
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
|
|
35
|
-
|
|
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
|
|
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
|
|
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.
|