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
@@ -10,7 +10,7 @@ export const configFile = 'joycraft.yaml';
10
10
  export const defaults = Object.freeze({
11
11
  paths: Object.freeze({ features: 'docs/features', archive: 'docs/archive', context: 'docs/context' }),
12
12
  hooks: Object.freeze({}),
13
- cleanup: Object.freeze({ impact: Object.freeze([]) }),
13
+ cleanup: Object.freeze({ impact: Object.freeze([]), entryWords: 1000 }),
14
14
  });
15
15
 
16
16
  function scalar(text, line) {
@@ -117,7 +117,7 @@ export function parseYaml(text) {
117
117
  return result;
118
118
  }
119
119
 
120
- const known = { paths: ['features', 'archive', 'context'], hooks: ['afterArchive'], cleanup: ['impact'] };
120
+ const known = { paths: ['features', 'archive', 'context'], hooks: ['afterArchive'], cleanup: ['impact', 'entryWords'] };
121
121
 
122
122
  /** Read joycraft.yaml (or return defaults) and validate every known field. */
123
123
  export function readConfig(root = process.cwd()) {
@@ -153,7 +153,9 @@ export function readConfig(root = process.cwd()) {
153
153
  `${configFile}: cleanup.impact item ${index + 1} needs source (a glob) and docs (a list of files)`);
154
154
  checkGlob(entry.source, `cleanup.impact item ${index + 1} source`);
155
155
  }
156
- return { source: configFile, paths, hooks, cleanup: { impact: impact.map(entry => ({ source: entry.source, docs: entry.docs.map(relativePath) })) } };
156
+ const entryWords = parsed.cleanup?.entryWords ?? defaults.cleanup.entryWords;
157
+ requireValue(Number.isInteger(entryWords) && entryWords > 0, `${configFile}: cleanup.entryWords must be a positive whole number of words`);
158
+ return { source: configFile, paths, hooks, cleanup: { impact: impact.map(entry => ({ source: entry.source, docs: entry.docs.map(relativePath) })), entryWords } };
157
159
  }
158
160
 
159
161
  /** Project-relative work folders for a project. */
@@ -34,6 +34,40 @@ function workspaceDirs(root) {
34
34
  return [...new Set(dirs)];
35
35
  }
36
36
 
37
+ const manifestFile = /(^|\/)(package\.json|pubspec\.yaml|Package\.swift|build\.gradle(\.kts)?|pyproject\.toml|requirements\.txt|setup\.py|Cargo\.toml|go\.mod)$/;
38
+ const skipDir = name => name.startsWith('.') || ['node_modules', 'vendor', 'Pods', 'dist', 'build', 'target'].includes(name);
39
+
40
+ /** Project files below the root: git's view when it has one (so .gitignore holds), else a bounded walk. */
41
+ function projectFiles(root) {
42
+ try {
43
+ const out = execFileSync('git', ['-C', root, 'ls-files', '--cached', '--others', '--exclude-standard'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
44
+ return out.split('\n').filter(Boolean);
45
+ } catch {
46
+ const files = [];
47
+ const walk = (rel, depth) => {
48
+ for (const name of listDir(path.join(root, rel))) {
49
+ const file = rel ? `${rel}/${name}` : name;
50
+ if (isDir(path.join(root, file))) { if (depth < 6 && !skipDir(name)) walk(file, depth + 1); } else files.push(file);
51
+ }
52
+ };
53
+ walk('', 0);
54
+ return files;
55
+ }
56
+ }
57
+
58
+ /** Folders holding a manifest when no workspaces are declared. The shallowest wins; an Android `app/` belongs to its parent. */
59
+ function nestedPackageDirs(root) {
60
+ const dirs = new Set();
61
+ for (const file of projectFiles(root)) {
62
+ if (!manifestFile.test(file) || file.split('/').some(skipDir)) continue;
63
+ let dir = path.posix.dirname(file);
64
+ if (/build\.gradle/.test(file) && path.posix.basename(dir) === 'app') dir = path.posix.dirname(dir);
65
+ if (dir !== '.') dirs.add(dir);
66
+ }
67
+ const sorted = [...dirs].sort();
68
+ return sorted.filter(dir => !sorted.some(other => other !== dir && dir.startsWith(`${other}/`)));
69
+ }
70
+
37
71
  /** Categories for one package directory, from its manifests and project files only. */
38
72
  export function classifyPackage(dir) {
39
73
  const found = new Set();
@@ -65,11 +99,19 @@ export function classifyPackage(dir) {
65
99
  return [...found];
66
100
  }
67
101
 
68
- /** Each package of a project with its categories. A workspace root without its own app is not a package. */
69
- export function detectProjects(root) {
70
- const packages = workspaceDirs(root).map(dir => ({ path: dir, categories: classifyPackage(path.join(root, dir)) }))
71
- .filter(entry => entry.categories.length);
102
+ /**
103
+ * Each package of a project with its categories. A workspace root without its own app is not a package.
104
+ * `packages` names the folders outright; with no workspaces and no root manifest, nested manifests are scanned.
105
+ */
106
+ export function detectProjects(root, { packages: named = null } = {}) {
107
+ const outside = (named ?? []).find(dir => path.isAbsolute(dir) || dir.split(/[\\/]/).includes('..'));
108
+ if (outside) throw new Error(`--packages takes folders inside the project; ${outside} is not`);
72
109
  const own = classifyPackage(root);
110
+ const declared = named ?? workspaceDirs(root);
111
+ const dirs = named || declared.length || own.length ? declared : nestedPackageDirs(root);
112
+ const packages = dirs.map(dir => ({ path: dir, categories: classifyPackage(path.join(root, dir)) }))
113
+ .filter(entry => entry.categories.length);
114
+ if (named) return packages;
73
115
  const workspaceOnly = packages.length && own.every(category => category === 'cli-library');
74
116
  return [...(workspaceOnly || !own.length ? [] : [{ path: '.', categories: own }]), ...packages];
75
117
  }
@@ -163,8 +205,8 @@ function startCommand(dir, root, categories) {
163
205
  }
164
206
 
165
207
  /** The Review loop plan: each package, each tool it needs, and that tool's status. Probes only. */
166
- export function reviewLoopPlan(root, { run = defaultRun, hostTools = [], env = process.env, home = homedir() } = {}) {
167
- const packages = detectProjects(root).map(entry => {
208
+ export function reviewLoopPlan(root, { run = defaultRun, hostTools = [], env = process.env, home = homedir(), packages: named = null } = {}) {
209
+ const packages = detectProjects(root, { packages: named }).map(entry => {
168
210
  const dir = path.join(root, entry.path);
169
211
  const tools = toolsFor(entry.categories, dir).map(id => {
170
212
  const spec = catalog.tools[id];
@@ -191,6 +233,10 @@ const statusText = tool => tool.status === 'present' ? `present${tool.version ?
191
233
 
192
234
  /** One table and at most one question, decision first. */
193
235
  export function renderPlan(plan, changes = null) {
236
+ if (!plan.packages.length) {
237
+ return ['Review loop plan', '', 'No packages found: no workspaces are declared and no project manifest was found below the root.',
238
+ '', 'Which folders hold the apps? Name them with `--packages <dir,dir>` on plan, install and record.'].join('\n');
239
+ }
194
240
  const lines = ['Review loop plan', '', '| Package | Kind | Tool | Status | To install |', '|---|---|---|---|---|'];
195
241
  for (const entry of plan.packages) for (const tool of entry.tools) {
196
242
  const install = tool.install?.commands ? `\`${tool.install.commands.map(command => command.join(' ')).join(' && ')}\` (${tool.install.size})`
@@ -259,6 +305,7 @@ export function planForSetup(root, options) {
259
305
 
260
306
  /** Write the chosen setup to AGENTS.md under `## Review loop`, replacing only that section. */
261
307
  export function recordReviewLoop(root, plan, { skipped = [] } = {}) {
308
+ if (!plan.packages.length) throw new Error('No packages found, so there is nothing to record; name them with --packages <dir,dir>');
262
309
  const rows = ['| Package | Tool | Start the app | Take the evidence |', '|---|---|---|---|'];
263
310
  const unverified = [];
264
311
  for (const entry of plan.packages) {
@@ -307,7 +354,7 @@ export async function main(argv = process.argv.slice(2)) {
307
354
  }
308
355
  const root = path.resolve(flags['--root'] ?? '.');
309
356
  const list = value => (value ? value.split(',').filter(Boolean) : []);
310
- const options = { hostTools: list(flags['--host-tools']) };
357
+ const options = { hostTools: list(flags['--host-tools']), packages: flags['--packages'] ? list(flags['--packages']) : null };
311
358
  if (command === 'plan') {
312
359
  const { text, ask } = planForSetup(root, options);
313
360
  process.stdout.write(`${text}\n`);
@@ -323,7 +370,7 @@ export async function main(argv = process.argv.slice(2)) {
323
370
  process.stdout.write(`${JSON.stringify(result)}\n`);
324
371
  return result;
325
372
  }
326
- throw new Error('Usage: review-tools.mjs plan|install|record --root <project> [--host-tools browser,simulator] [--tools playwright --yes] [--skip playwright]');
373
+ throw new Error('Usage: review-tools.mjs plan|install|record --root <project> [--packages apps/web,apps/api] [--host-tools browser,simulator] [--tools playwright --yes] [--skip playwright]');
327
374
  }
328
375
 
329
376
  if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
@@ -1,11 +1,14 @@
1
1
  #!/usr/bin/env node
2
2
  // Daily check for a newer Joycraft. Prints nothing unless there is something to say,
3
- // and never fails a session. The request is the package metadata only.
3
+ // and never fails a session. The one request reads the public package document
4
+ // (every version's metadata, about 25 KB compressed), never project data.
4
5
  import { lstatSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
5
6
  import { join, resolve } from 'node:path';
6
7
  import { pathToFileURL } from 'node:url';
7
8
 
8
- const registry = 'https://registry.npmjs.org/joycraft/latest';
9
+ const registry = 'https://registry.npmjs.org/joycraft';
10
+ const changelog = 'https://github.com/maksutovic/joycraft/blob/main/CHANGELOG.md';
11
+ const listed = 5;
9
12
  const day = 24 * 60 * 60 * 1000;
10
13
  const retryAfter = 60 * 60 * 1000;
11
14
  const snoozeFor = 7 * day;
@@ -51,7 +54,11 @@ export function isNewer(candidate, installed) {
51
54
  return false;
52
55
  }
53
56
 
54
- const updateKind = (latest, installed) => latest.split('.')[0] === installed.split('.')[0] ? 'patch' : 'migration';
57
+ export function updateKind(latest, installed) {
58
+ const [major, minor] = latest.split('.'), [fromMajor, fromMinor] = installed.split('.');
59
+ if (BigInt(major) !== BigInt(fromMajor)) return 'migration';
60
+ return BigInt(minor) === BigInt(fromMinor) ? 'patch' : 'minor';
61
+ }
55
62
  const oneLine = value => typeof value === 'string' ? value.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 300) : '';
56
63
 
57
64
  function holdLock(root) {
@@ -74,10 +81,17 @@ async function latestRelease(root, { fetcher, now }) {
74
81
  try {
75
82
  const response = await fetcher(registry, { signal: AbortSignal.timeout(deadline), headers: { accept: 'application/json' } });
76
83
  if (!response.ok) throw new Error(`registry ${response.status}`);
77
- const metadata = await response.json();
78
- if (typeof metadata?.version !== 'string' || !stable.test(metadata.version)) throw new Error('not a stable release');
79
- const notes = metadata.joycraft?.release === metadata.version ? metadata.joycraft : {};
80
- const fresh = { fetchedAt: now, version: metadata.version, summary: oneLine(notes.summary), autoSafeEligible: notes.autoSafeEligible === true };
84
+ const packument = await response.json();
85
+ const version = packument?.['dist-tags']?.latest;
86
+ const versions = packument?.versions;
87
+ if (typeof version !== 'string' || !stable.test(version) || !versions || typeof versions !== 'object' || !versions[version]) throw new Error('not a stable release');
88
+ const notesOf = key => versions[key]?.joycraft?.release === key ? versions[key].joycraft : {};
89
+ const releases = Object.keys(versions)
90
+ .filter(key => stable.test(key) && !isNewer(key, version))
91
+ .sort((a, b) => isNewer(a, b) ? 1 : isNewer(b, a) ? -1 : 0)
92
+ .map(key => ({ version: key, summary: oneLine(notesOf(key).summary) }));
93
+ const notes = notesOf(version);
94
+ const fresh = { fetchedAt: now, version, summary: oneLine(notes.summary), autoSafeEligible: notes.autoSafeEligible === true, releases };
81
95
  writeLocal(root, 'update-check.json', fresh);
82
96
  return fresh;
83
97
  } catch {
@@ -99,8 +113,24 @@ export async function check(root, { fetcher = fetch, now = Date.now() } = {}) {
99
113
  const kind = updateKind(latest, installed);
100
114
  const summary = cache.summary || 'See the changelog for what changed.';
101
115
  if (update.pin === true) return { action: 'note', installed, latest, kind, message: `Joycraft ${latest} is available. This project stays on ${installed} by choice.` };
116
+ const releases = sinceInstalled(cache, installed, latest);
102
117
  const action = policy === 'auto-safe' && kind === 'patch' && cache.autoSafeEligible === true ? 'apply' : 'ask';
103
- return { action, installed, latest, kind, summary, message: `Joycraft ${latest} is available (you have ${installed}; ${kind}). ${summary}` };
118
+ return { action, installed, latest, kind, summary, releases, changelog, message: `Joycraft ${latest} is available (you have ${installed}; ${kind}). ${describe(releases)} Changelog: ${changelog}` };
119
+ }
120
+
121
+ /** Releases after the installed one up to latest, newest first. A cache from before release lists holds only latest. */
122
+ function sinceInstalled(cache, installed, latest) {
123
+ const known = Array.isArray(cache.releases) ? cache.releases : [{ version: latest, summary: cache.summary }];
124
+ return known
125
+ .filter(entry => typeof entry?.version === 'string' && stable.test(entry.version) && isNewer(entry.version, installed) && !isNewer(entry.version, latest))
126
+ .map(entry => ({ version: entry.version, summary: oneLine(entry.summary) }))
127
+ .reverse();
128
+ }
129
+
130
+ function describe(releases) {
131
+ const shown = releases.slice(0, listed).map(entry => `${entry.version}: ${entry.summary || 'no summary.'}`.replace(/([^.!?])$/, '$1.'));
132
+ const more = releases.length - shown.length;
133
+ return `${shown.join(' ')}${more > 0 ? ` and ${more} more.` : ''}`;
104
134
  }
105
135
 
106
136
  function savePreference(root, change) {
@@ -0,0 +1,156 @@
1
+ import { readFileSync, realpathSync } from 'node:fs';
2
+ import path from 'node:path';
3
+ import { pathToFileURL } from 'node:url';
4
+ import { workPaths } from './config.mjs';
5
+
6
+ // A report-only check that the project's entry files carry Joycraft: the
7
+ // update-check line, a context map with at least one project row, and (when
8
+ // Claude Code is installed) a CLAUDE.md that imports AGENTS.md, unless AGENTS.md
9
+ // itself imports CLAUDE.md. It never edits a file; the agent writes the missing
10
+ // pieces after talking with the person. `findings` decide the exit code;
11
+ // `advice` (areas setup has not mapped yet) never does.
12
+ const read = (root, file) => { try { return readFileSync(path.join(root, file), 'utf8'); } catch { return null; } };
13
+
14
+ function claudeInstalled(root, hosts) {
15
+ if (Array.isArray(hosts)) return hosts.includes('claude');
16
+ const text = read(root, '.joycraft/installation.json');
17
+ if (text === null) return false;
18
+ try {
19
+ const manifest = JSON.parse(text);
20
+ const hosts = Array.isArray(manifest?.hosts) ? manifest.hosts : [manifest?.harness];
21
+ return hosts.includes('claude');
22
+ } catch { return false; }
23
+ }
24
+
25
+ // Lines outside fenced code, so an example in a fence is not read as the map.
26
+ function proseLines(text) {
27
+ let fence = null;
28
+ return text.split(/\r?\n/).map(line => {
29
+ const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
30
+ if (!fence) {
31
+ if (!marker || (marker[0] === '`' && line.trimStart().slice(marker.length).includes('`'))) return line;
32
+ fence = marker;
33
+ } else if (marker && marker[0] === fence[0] && marker.length >= fence.length && /^\s*[`~]+\s*$/.test(line)) fence = null;
34
+ return '';
35
+ });
36
+ }
37
+
38
+ /** The lines under the context map heading, up to the next heading of the same or a higher level; null when there is none. */
39
+ function contextMap(text) {
40
+ const lines = proseLines(text);
41
+ // Any heading whose text starts with "context map": `## Context Map (read only what you need)`.
42
+ const start = lines.findIndex(line => /^ {0,3}#{1,6}\s+context map\b/i.test(line));
43
+ if (start === -1) return null;
44
+ const level = /^ {0,3}(#+)/.exec(lines[start])[1].length;
45
+ const end = lines.findIndex((line, index) => index > start && (/^ {0,3}(#+)\s/.exec(line)?.[1].length ?? 7) <= level);
46
+ return lines.slice(start + 1, end === -1 ? undefined : end);
47
+ }
48
+
49
+ /** Reference-link definitions (`[label]: target`) outside code, keyed by lowercased label. */
50
+ function linkDefinitions(lines) {
51
+ const out = new Map();
52
+ for (const line of lines) {
53
+ const match = /^ {0,3}\[([^\]]+)\]:\s+(?:<([^>]+)>|(\S+))/.exec(line);
54
+ const label = match?.[1].trim().toLowerCase();
55
+ if (label && !out.has(label)) out.set(label, match[2] ?? match[3]);
56
+ }
57
+ return out;
58
+ }
59
+
60
+ /**
61
+ * Project-relative targets of a table row: inline links, full and collapsed
62
+ * reference links (`[p][ref]`, `[p][]`) and backticked paths. A leading `/` means
63
+ * the project root.
64
+ */
65
+ function rowTargets(row, definitions = new Map()) {
66
+ const raw = [
67
+ ...[...row.matchAll(/\[[^\]]*\]\((?:<([^>]+)>|([^)\s]+))[^)]*\)/g)].map(match => match[1] ?? match[2]),
68
+ ...[...row.matchAll(/\[([^\]]*)\]\[([^\]]*)\]/g)].map(match => definitions.get((match[2] || match[1]).trim().toLowerCase())).filter(Boolean),
69
+ ...[...row.matchAll(/`([^`\s]+)`/g)].map(match => match[1]).filter(value => value.includes('/') || /\.[a-z0-9]+$/i.test(value)),
70
+ ];
71
+ return raw.map(target => target.split('#')[0])
72
+ .filter(target => target && !/^[a-z][a-z0-9+.-]*:/i.test(target) && !target.startsWith('//'))
73
+ .map(target => target.replace(/^\/+/, ''))
74
+ .filter(Boolean)
75
+ .map(target => path.posix.normalize(target));
76
+ }
77
+
78
+ const imports = (text, file) => text !== null && proseLines(text).some(line => new RegExp(`^\\s*@(\\./)?${file.replace('.', '\\.')}\\s*$`).test(line));
79
+
80
+ /** True when AGENTS.md is CLAUDE.md (a symlink) or imports it, so Claude Code reads both without a reciprocal import. */
81
+ function agentsDefersToClaude(root, agents) {
82
+ try { if (realpathSync(path.join(root, 'AGENTS.md')) === realpathSync(path.join(root, 'CLAUDE.md'))) return true; } catch { /* either file missing */ }
83
+ return imports(agents, 'CLAUDE.md');
84
+ }
85
+
86
+ /** Items of the `## Not yet mapped` list in the project context page: areas setup has not read yet. */
87
+ export function unmappedAreas(text) {
88
+ if (text === null) return [];
89
+ const lines = proseLines(text);
90
+ const start = lines.findIndex(line => /^ {0,3}#{1,6}\s+not yet mapped\b/i.test(line));
91
+ if (start === -1) return [];
92
+ const level = /^ {0,3}(#+)/.exec(lines[start])[1].length;
93
+ const areas = [];
94
+ for (const line of lines.slice(start + 1)) {
95
+ if ((/^ {0,3}(#+)\s/.exec(line)?.[1].length ?? 7) <= level) break;
96
+ const item = /^\s*[-*+]\s+(.+?)\s*$/.exec(line)?.[1];
97
+ if (item) areas.push(item);
98
+ }
99
+ return areas;
100
+ }
101
+
102
+ function contextPage(root) {
103
+ try { return `${workPaths(root).context}/project.md`; } catch { return 'docs/context/project.md'; }
104
+ }
105
+
106
+ const outsideJoycraft = target => target !== '.joycraft' && !target.startsWith('.joycraft/') && !target.startsWith('../');
107
+
108
+ /** Report what is missing for the project to be wired up. Reads files only. */
109
+ export function checkWiring(root, { hosts } = {}) {
110
+ const findings = [];
111
+ const agents = read(root, 'AGENTS.md');
112
+ if (agents === null) {
113
+ findings.push({ check: 'no-agents-md', path: 'AGENTS.md', detail: 'The project has no AGENTS.md, so agents get no Joycraft lines and no context map.', fix: "Ask the agent to set up Joycraft's context map (see .joycraft/references/setup.md)." });
114
+ } else {
115
+ if (!agents.includes('update-check.mjs check')) {
116
+ findings.push({ check: 'no-joycraft-lines', path: 'AGENTS.md', detail: 'AGENTS.md has no `node .joycraft/runtime/update-check.mjs check` line, so sessions do not start with Joycraft.', fix: 'Add the Joycraft lines from .joycraft/references/setup.md with a targeted edit.' });
117
+ }
118
+ const map = contextMap(agents);
119
+ if (map === null) {
120
+ findings.push({ check: 'no-context-map', path: 'AGENTS.md', detail: 'AGENTS.md has no `## Context Map` heading, so agents cannot find project knowledge.', fix: 'Add a context map table that links project documents, each with a "read when".' });
121
+ } else {
122
+ const rows = map.filter(line => /^\s*\|/.test(line));
123
+ const definitions = linkDefinitions(proseLines(agents));
124
+ if (!rows.some(row => rowTargets(row, definitions).some(outsideJoycraft))) {
125
+ findings.push({ check: 'empty-context-map', path: 'AGENTS.md', detail: 'The context map has no row that points to a project document outside .joycraft/.', fix: 'Add rows for the project documents agents should read, each with a "read when".' });
126
+ }
127
+ }
128
+ }
129
+ if (claudeInstalled(root, hosts)) {
130
+ const claude = read(root, 'CLAUDE.md');
131
+ // An @AGENTS.md line inside a code fence is an example, not an import.
132
+ if (!imports(claude, 'AGENTS.md') && !(claude !== null && agentsDefersToClaude(root, agents))) {
133
+ findings.push({ check: 'no-claude-import', path: 'CLAUDE.md', detail: claude === null ? 'Claude Code is installed, but there is no CLAUDE.md, so Claude Code does not read AGENTS.md.' : 'Claude Code is installed, but CLAUDE.md has no `@AGENTS.md` line, so Claude Code does not read AGENTS.md.', fix: 'Add a line `@AGENTS.md` to CLAUDE.md, creating the file if needed.' });
134
+ }
135
+ }
136
+ const advice = [];
137
+ const page = contextPage(root);
138
+ const areas = unmappedAreas(read(root, page));
139
+ if (areas.length) {
140
+ advice.push({ check: 'unmapped-areas', path: page, areas, detail: `Setup has not read ${areas.length === 1 ? 'one area' : `${areas.length} areas`} yet: ${areas.join('; ')}.`, fix: 'When a request touches a listed area, map that area first (read it, propose rows, write on yes) and remove it from the list.' });
141
+ }
142
+ return { wired: findings.length === 0, findings, advice };
143
+ }
144
+
145
+ export async function main(argv = process.argv.slice(2)) {
146
+ const index = argv.indexOf('--root');
147
+ if (!(argv.length === 0 || (argv.length === 2 && index === 0))) throw new Error('Usage: wiring.mjs [--root <project>]');
148
+ const result = checkWiring(path.resolve(index === 0 ? argv[1] : '.'));
149
+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
150
+ if (!result.wired) process.exitCode = 2;
151
+ return result;
152
+ }
153
+
154
+ if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
155
+ main().catch(error => { process.stderr.write(`Wiring check stopped: ${error.message}\n`); process.exitCode = 1; });
156
+ }
@@ -17,3 +17,5 @@ cleanup:
17
17
  impact: []
18
18
  # - source: src/auction/**
19
19
  # docs: [docs/context/auction-rules.md]
20
+ # Word budget for AGENTS.md and CLAUDE.md; cleanup.mjs flags a longer file.
21
+ # entryWords: 1000
@@ -1,6 +1,6 @@
1
1
  # <Project name>
2
2
 
3
- Copy to `docs/context/project.md` during a kickoff. Delete every section that
3
+ Copy to `docs/context/project.md` during a kickoff or setup. Delete every section that
4
4
  has no content yet; never leave a placeholder. Mark each statement as the
5
5
  user's words, a decision, or an assumption.
6
6
 
@@ -27,6 +27,11 @@ What this project will not do, as the user stated it.
27
27
  | Term | Meaning, in the user's words |
28
28
  |---|---|
29
29
 
30
+ ## Not yet mapped
31
+
32
+ - One item per project area setup has not read yet (a folder or component).
33
+ Remove an item once its area is mapped; keep no history here.
34
+
30
35
  ## Open questions
31
36
 
32
37
  Consequential unknowns that are not decided yet. Do not write them as boundaries.
package/payload/PIN CHANGED
@@ -1,52 +1,54 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "source": "joycraft-prototype",
4
- "tag": "field-10",
5
- "commit": "c535c1dcbfd1256b06a4c981352d8bbf358a182b",
4
+ "tag": "field-14",
5
+ "commit": "a23fc6943b2937f66e72d6feec3d686c16b7b846",
6
6
  "files": {
7
- ".agents/skills/joycraft-cleanup/SKILL.md": "e9a6eda4773332d87cc6a13cc939aaa5d3ea1ec1f980b1132a6794740cdfe39f",
8
- ".agents/skills/joycraft-context/SKILL.md": "e0a5f7d82fe8b6b6d3aeab38f7cf570ca939dba07034243af1ef86d24448c084",
7
+ ".agents/skills/joycraft-cleanup/SKILL.md": "99ce785e551be33412ac7a99ce44585a9b2be4440617caac273680383b4f7057",
8
+ ".agents/skills/joycraft-context/SKILL.md": "e2f85baa47058fd61811fdb60d0cb41fb3f505f3957812d929db95bb99124f1b",
9
9
  ".agents/skills/joycraft-decompose/SKILL.md": "a24c9d9cf2dc7af4b99ad67575b64b9d0c99818044f7fafc3a5243dc4c557b5f",
10
- ".agents/skills/joycraft-entry/SKILL.md": "c6102aca5e8f7e864a963ab1b3fa26007ef6118dee30a3eb59af55a3a52c9c8d",
10
+ ".agents/skills/joycraft-entry/SKILL.md": "5b9f58369259def87b5b3c0dffa6383e93a0f4844b971d85b594f422cd5398ac",
11
11
  ".agents/skills/joycraft-implement/SKILL.md": "075832c85f6bff177eca45f5ce4412f6a6661fe9be9213674ddc2f74c2dc211e",
12
12
  ".agents/skills/joycraft-retro/SKILL.md": "156f36cb047604c734bf273bd02822d964b6af86619ed6c2a30fa6d79eb9a986",
13
13
  ".agents/skills/joycraft-retro/agents/openai.yaml": "f0eb4732261635f41e08f0bbe9a931d62fd8ac645149d3406e6fc7e16a81750b",
14
- ".agents/skills/joycraft-session-end/SKILL.md": "31fd6ef54b46fec92a7e52e381a8e25886239d0e3c3ce8ca820c3be6fa1e1877",
14
+ ".agents/skills/joycraft-session-end/SKILL.md": "55bcf6099d52abe1f7b4a0de376333f435a7154aae4690d679948f9f837702fa",
15
15
  ".agents/skills/joycraft-testing/SKILL.md": "89e983b285099c38821dc807311b27d450e6dec9fb691cd687ca74332b091157",
16
16
  ".agents/skills/joycraft-ui-slice/SKILL.md": "fcb5f109c9bd23d4afe5b47d19c90fd34485754ce9061c64bce1ae2ce0376484",
17
17
  ".agents/skills/joycraft-ui-slice/scripts/serve.mjs": "c16858800b6fbe6f7a3a21b21e785ad70c9a89a3fe970bc08701fefeac5042fa",
18
18
  ".agents/skills/joycraft-verify/SKILL.md": "f18eda5910e1ca5c312f5185b0dbceb4dc09fb9d73951e64410b5d59db046511",
19
19
  ".claude/agents/joycraft-implementer.md": "30b26779bd49d2d66758bcb26442e78755b018a3830ac52ff634ebf057ce1cc5",
20
20
  ".claude/agents/joycraft-reviewer.md": "488b1923115257dbe966bbe4717d21f95900b18cff68febd848e1f8f362a9d37",
21
- ".joycraft/assets/artifacts/kit.css": "9b04b739b3b137d4a3052a939cbc46b5acb9abde085989bd599481ae40e5c6a9",
22
- ".joycraft/assets/artifacts/kit.js": "e54db2157cfee278f5e6777b6b6fe2d2f5297cd2401b173d1a4b72e3fad00562",
23
- ".joycraft/assets/artifacts/transports.js": "e53c67ac030a1d7c9ce4666b998604a471598cb4df08bc83f37e3d166b8017eb",
21
+ ".joycraft/assets/artifacts/kit.css": "b3481214b73fa8919708075e97aae60ed42dda386c8837129ee153099adf5b43",
22
+ ".joycraft/assets/artifacts/kit.js": "5de876e66536ad1e10ad6dc65d775c6d0a59540c81c5b48b5d4239fbdbf0569a",
23
+ ".joycraft/assets/artifacts/transports.js": "318e97895468b47f07febc913d3a6e100b0ad19b78b3a4fc51bebc488e67c25d",
24
24
  ".joycraft/contracts/types.d.ts": "5c4e654ea929778c586bc6cce44e60dc031578b2414dd1b8161359cf9f424b41",
25
25
  ".joycraft/references/architecture.md": "52eaaa4b88053481c9f8cad2418ea0f1db880184c3a50c95901f30f24be75852",
26
26
  ".joycraft/references/archive.md": "7deca056a93b21c97d82633bcdf5acf6c77bf2c59b2430e648f665923c020794",
27
- ".joycraft/references/artifacts.md": "1f21223601342f4ce54c4d76320f89f4eea1c8d0089396495993ba62155f422e",
28
- ".joycraft/references/cleanup.md": "c223e17ea970fd528b44f0f22e614763d2281b49531c1ee566b3fba60417eeac",
27
+ ".joycraft/references/artifacts.md": "f9ae6d86f604eea7424b97076aad91bec0f6b69e4c4d6954f86d2b15fb531f66",
28
+ ".joycraft/references/cleanup.md": "aa784c63442a289c67de359d82c78abca3aa8cab5b5e2d91fcd731b45c209003",
29
29
  ".joycraft/references/completion.md": "7df48664861f41e2e503a828e97d6b6f615745591a3f47f17d196fa4d24a122d",
30
- ".joycraft/references/context.md": "f2c8313eaf996b633040e52855ae1eef57b03cad2b024bb5eacb70b38d39ca95",
30
+ ".joycraft/references/context.md": "df72d3b59d55f0d9741234d4a3d7b56532f560d787c88d5d8630d954472bc430",
31
31
  ".joycraft/references/delivery.md": "1afc417ee3922ebf5e84c0ae87796d6cb6305679c0257ed38a35f396949de5e8",
32
32
  ".joycraft/references/dispatch.md": "b80d6899c52b7c003012fdfc774be271773213b7fedc37f4c247b431cdf8207d",
33
+ ".joycraft/references/doc-cleanup-LICENSE.md": "a9e210590e2d0ebf719fe3801f1c0fda8f940af28656ff36e908c4315d94f886",
34
+ ".joycraft/references/knowledge.md": "a08a117a5d0ae65a45dfd8ab3f3da92dd3c7aeedaa09ae1d71ddf3d6528c7f95",
33
35
  ".joycraft/references/recurring-failures.md": "7080f6c55492bc19c2897f4f0b128a830a71cdb516678c79ff6e97ffa1dc6b86",
34
36
  ".joycraft/references/retro.md": "f359eae19747777fb4687c1bc7eb280f0319ae629ee62913346e60fc56551562",
35
- ".joycraft/references/setup.md": "ab06b0b7b83cb141b04f4ad75af1e28beb278c3b39a29acbb07fd8580bf0ca1f",
37
+ ".joycraft/references/setup.md": "54800d023afa6fe4153dbd0d17b3453d570e31ba416df9fde054e9aa2e333c71",
36
38
  ".joycraft/references/testing.md": "7a0be4a5424f0fac89cba6e896c66a50948e31332bb7f032f688d72a203e4f4d",
37
- ".joycraft/references/update.md": "8e26ddaa21d3b133902bebcb6662a16f52f3ae3f04c51c69fdb325a8e9c0aeac",
39
+ ".joycraft/references/update.md": "95569e44fe36af52b9d72bc6b64b36745fcfc5d31b9b4d91f10e6bed40a0e987",
38
40
  ".joycraft/references/workflow.md": "ed4a6618ab3288ea213691e4485f580d8348f717b6e663d29fbb570541e42c2c",
39
41
  ".joycraft/references/worktrees.md": "fb18af0cd76d4e3c5d5b892a7ae10946f21f189e642243235c188b571635f735",
40
42
  ".joycraft/runtime/archive.mjs": "c153f5407fe6abffe5cf9655b0ff40db2254712a1bfee429dad93251bb7d0121",
41
43
  ".joycraft/runtime/artifacts/cli.mjs": "d30152e6829e07d9c7ff6ceedbfa6813931674d8529778f62b0d64e3a4049ab0",
42
- ".joycraft/runtime/artifacts/decisions.mjs": "9cba81346daf59cd020b8d976af98b1f6c2aec8d0a1575e5e0f806334ae622d0",
44
+ ".joycraft/runtime/artifacts/decisions.mjs": "fda4289eb0b7059906e0bd03b6078d1ff6fa45e23a495630721ee84ee84e0f1d",
43
45
  ".joycraft/runtime/artifacts/model.mjs": "fbe44d37049759387ecc02ba2580c94e26e6c5cb8cac3dcbcc79aeab3b75756b",
44
46
  ".joycraft/runtime/artifacts/preferences.mjs": "9165e1c753aa8533affe976cacecb135b0ee3cc9f455f5f80b1568103bb49fd6",
45
47
  ".joycraft/runtime/artifacts/render.mjs": "488673cab94fa6bfde223c2c41650f8e183f7ac0be3840d371ee057d95ea0fa5",
46
- ".joycraft/runtime/artifacts/server.mjs": "a96048fad649e8053c70ce95c5a757929ab57ae9de27198121224326551c0a05",
47
- ".joycraft/runtime/cleanup.mjs": "99aa8ba12e856893e47232f2944013e56c3925e8ab8f732c195c092497690c3f",
48
+ ".joycraft/runtime/artifacts/server.mjs": "0c787812ffbea22c3edb7cb7281e95f54e44da4361f57ac9906487e7b5e6f8e9",
49
+ ".joycraft/runtime/cleanup.mjs": "9a10dfd27c12f807c71f407352f1526fdb9b4632c523a965952f65d1b7af158c",
48
50
  ".joycraft/runtime/completion.mjs": "11635b11eb7df90398a69b6d41f96d9c7b9d2dc2255ae4a4a129562d46572ec1",
49
- ".joycraft/runtime/config.mjs": "9b64d7f6928bbcc8145c8de51994d82dd8e3323878d321bce0fb3bc11975eedf",
51
+ ".joycraft/runtime/config.mjs": "72a536f3453dd73f65fdc243e2a13b562eee5a7ba59528adca4bde684307036a",
50
52
  ".joycraft/runtime/context/cli.mjs": "40adc206c8c3b7f4f5bedffb097d9ae1b0718f0586a055796e4987e9c3088eee",
51
53
  ".joycraft/runtime/context/index.mjs": "5a69d33d9a1a66ef23301e952ecb1ec427ff4b0baf408ede67a2600d3f2a173c",
52
54
  ".joycraft/runtime/context/search.mjs": "e32a42ba9b168ca7c68fed46d47a79250c27aa4c07c0835feae084b5d1e0d0ca",
@@ -60,18 +62,19 @@
60
62
  ".joycraft/runtime/redact.mjs": "cc8c0fe5e8d8fe78116ef126f6eee757a247739084e19c342bcf09a2b06524bc",
61
63
  ".joycraft/runtime/retro.mjs": "6f3664b0d50c12d4f2d8eef4b4d0d62897939d03e45860d4dcf35c0f5f92677c",
62
64
  ".joycraft/runtime/review-tools.json": "c00e4209d67fd655a351946509a2aba2ee287dbaa0a1ad60c22e1286de0b4893",
63
- ".joycraft/runtime/review-tools.mjs": "17c13f7ab746478bce5711501a5190991b46616c849780196614950cfc6f0208",
65
+ ".joycraft/runtime/review-tools.mjs": "2df0d7da93a62b06aa938c40499a564c1e87c5471b51f62478c675a9d488c0cc",
64
66
  ".joycraft/runtime/scope.mjs": "e2cdd929596246bf24e18850698db440119badc7068a3c5beab03ded45abbd65",
65
67
  ".joycraft/runtime/status.mjs": "0e1d2cc23f8d847ae14e8fc2dd909910d6b5655a0bb0305355f6f4d9709f1e33",
66
68
  ".joycraft/runtime/trace.mjs": "b7924f759b07991f4135698df9c32654631a325957f0f8de5c2ca1262c0a836a",
67
- ".joycraft/runtime/update-check.mjs": "324b2eda4ac1feb6bb5b15ef488bea5f2f8a6312bc7b1c24719e0b7fd6a84634",
69
+ ".joycraft/runtime/update-check.mjs": "987b65605a26ea71b6417fda7b48753980e0d8afa20eadbd527143850a93319e",
70
+ ".joycraft/runtime/wiring.mjs": "e08bcc604d40560f260edbc3499a4481a1efa7c7d2fa80545caa858827404667",
68
71
  ".joycraft/runtime/worktrees.mjs": "d463e1df5735550acf4f3a0e6f96f723d8f55806ba64d38190163d0cc0154f03",
69
72
  ".joycraft/templates/README.md": "56a166d0729e8b6c3bcb098afb8145006259357087fd8b1f1f343d9a2b4d36e0",
70
73
  ".joycraft/templates/artifact.json": "fda5f7c32516d6ab094ee0e8506d84a1a0d6d4d0f49048b01aa392c619996f05",
71
74
  ".joycraft/templates/brief.md": "03479342500570aba9fb206beef6f6049fd180bec814dd8001987174aecfef25",
72
75
  ".joycraft/templates/decisions.md": "49e0c9b3efe51d1c2e87345fcefe23ef0579e524d50febef8ef43a35141c8002",
73
- ".joycraft/templates/joycraft.yaml": "3aa465896e58cfec956040d9f2b13ce4f4be84c027a6bb1a3e2a9c0e834d2ace",
74
- ".joycraft/templates/project-context.md": "d7c81fee08609a7db45c5df0cb2bd5cb3409760169d8b03cc5f19b1ff82d03c2",
76
+ ".joycraft/templates/joycraft.yaml": "32ec8e9987030485f2a29d9231b2b15c310470d2f1269550e56c4dde0133becf",
77
+ ".joycraft/templates/project-context.md": "cf2455fef663e647962495175fa6a7a44301c4047eecff5811d9c91e21d9e266",
75
78
  ".joycraft/templates/queue.json": "88f922b6cc47b80befc27df86a143d6bae0b30869c46d712958b64291e5ebcc2",
76
79
  ".joycraft/templates/spec.md": "5f4b1490c2ba2e47ced1ef5b369fe3e41386eb61386c42c7a561b1e8af02ea5e",
77
80
  ".joycraft/templates/ui-slice.html": "0c3cf45709ff37815f8f0550b4b9431cb935589b282d40e8688b310a91de2274",