joycraft 1.0.0 → 1.1.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 (30) hide show
  1. package/README.md +54 -0
  2. package/dist/joycraft-release.json +1 -1
  3. package/package.json +3 -3
  4. package/payload/.agents/skills/joycraft-cleanup/SKILL.md +41 -0
  5. package/payload/.agents/skills/joycraft-entry/SKILL.md +10 -0
  6. package/payload/.agents/skills/joycraft-implement/SKILL.md +14 -2
  7. package/payload/.agents/skills/joycraft-session-end/SKILL.md +10 -4
  8. package/payload/.agents/skills/joycraft-verify/SKILL.md +4 -0
  9. package/payload/.claude/agents/joycraft-implementer.md +7 -1
  10. package/payload/.claude/agents/joycraft-reviewer.md +9 -0
  11. package/payload/.joycraft/references/archive.md +17 -0
  12. package/payload/.joycraft/references/cleanup.md +35 -0
  13. package/payload/.joycraft/references/context.md +5 -0
  14. package/payload/.joycraft/references/dispatch.md +6 -1
  15. package/payload/.joycraft/references/setup.md +30 -1
  16. package/payload/.joycraft/references/testing.md +10 -0
  17. package/payload/.joycraft/references/workflow.md +5 -0
  18. package/payload/.joycraft/references/worktrees.md +26 -0
  19. package/payload/.joycraft/runtime/archive.mjs +35 -15
  20. package/payload/.joycraft/runtime/cleanup.mjs +149 -0
  21. package/payload/.joycraft/runtime/config.mjs +191 -0
  22. package/payload/.joycraft/runtime/context/search.mjs +5 -3
  23. package/payload/.joycraft/runtime/coordinator.mjs +169 -0
  24. package/payload/.joycraft/runtime/dispatch-start.mjs +18 -3
  25. package/payload/.joycraft/runtime/review-tools.json +7 -0
  26. package/payload/.joycraft/runtime/status.mjs +97 -0
  27. package/payload/.joycraft/runtime/trace.mjs +79 -0
  28. package/payload/.joycraft/runtime/worktrees.mjs +201 -0
  29. package/payload/.joycraft/templates/joycraft.yaml +19 -0
  30. package/payload/PIN +28 -19
@@ -0,0 +1,97 @@
1
+ import { existsSync, readdirSync, writeFileSync } from 'node:fs';
2
+ import path from 'node:path';
3
+ import { pathToFileURL } from 'node:url';
4
+ import { journalPath } from './completion.mjs';
5
+ import { workPaths } from './config.mjs';
6
+ import { briefDecisionRecords, isObject, localPath, parseJson, readLocal, specStatus, validateQueue } from './identity.mjs';
7
+ import { listWorktrees } from './worktrees.mjs';
8
+
9
+ // The queue is the status authority; spec frontmatter mirrors it. This report
10
+ // shows where the mirror or the working folders have drifted, so a session can
11
+ // close them before they read as current knowledge.
12
+ const queueName = 'specs/.joycraft-spec-queue.json';
13
+
14
+ function queuePaths(root) {
15
+ const featuresHome = workPaths(root).features;
16
+ const home = path.join(root, featuresHome);
17
+ if (!existsSync(home)) return [];
18
+ return readdirSync(home, { withFileTypes: true })
19
+ .filter(entry => entry.isDirectory() && existsSync(path.join(home, entry.name, queueName)))
20
+ .map(entry => `${featuresHome}/${entry.name}/${queueName}`).sort();
21
+ }
22
+
23
+ const accepted = spec => spec.status === 'done' && (isObject(spec.acceptedReport) || isObject(spec.ownerAcceptance));
24
+
25
+ function openDecisions(root, folder) {
26
+ const brief = `${folder}/brief.md`;
27
+ if (!existsSync(localPath(root, brief, true))) return [];
28
+ try { return briefDecisionRecords(readLocal(root, brief), brief).filter(record => isObject(record) && record.status === 'open').map(record => record.id); }
29
+ catch { return []; }
30
+ }
31
+
32
+ function worktreeCounts(root) {
33
+ try {
34
+ const { trees } = listWorktrees({ root, sizes: false });
35
+ return {
36
+ owned: trees.filter(tree => tree.owner === 'joycraft' && !tree.missing).length,
37
+ prunable: trees.filter(tree => tree.owner === 'joycraft' && !tree.missing && tree.specStatus === 'done' && tree.clean && tree.merged).length,
38
+ unknown: trees.filter(tree => tree.owner !== 'joycraft').length,
39
+ };
40
+ } catch { return null; }
41
+ }
42
+
43
+ /** Report every queue's specs (in paths.features), drift between queue and frontmatter, and features ready to archive. */
44
+ export function projectStatus({ root = process.cwd(), fix = false } = {}) {
45
+ const features = [];
46
+ const drift = [];
47
+ const fixed = [];
48
+ const readyToArchive = [];
49
+ const problems = [];
50
+ for (const queuePath of queuePaths(root)) {
51
+ const folder = path.posix.dirname(path.posix.dirname(queuePath));
52
+ let queue;
53
+ try { queue = parseJson(readLocal(root, queuePath), queuePath); validateQueue(queue, { select: () => false }); }
54
+ catch (error) { problems.push({ queuePath, problem: error.message }); continue; }
55
+ const pendingJournal = existsSync(localPath(root, journalPath(queuePath), true));
56
+ const specs = queue.specs.map(spec => {
57
+ const specPath = path.posix.join(path.posix.dirname(queuePath), spec.file);
58
+ let frontmatter = null;
59
+ let mirror = null;
60
+ try { mirror = specStatus(readLocal(root, specPath)); frontmatter = mirror.status; }
61
+ catch (error) { problems.push({ specPath, problem: error.message }); }
62
+ const row = { id: spec.id, file: specPath, queue: spec.status, frontmatter };
63
+ if (frontmatter !== null && frontmatter !== spec.status) {
64
+ const fixable = accepted(spec) && !pendingJournal;
65
+ const reason = pendingJournal ? `A completion journal is pending; run node .joycraft/runtime/completion.mjs recover --queue ${queuePath}`
66
+ : fixable ? 'The queue records an accepted completion; the frontmatter lags.'
67
+ : 'Only an accepted done spec is repaired automatically; reconcile this one by hand.';
68
+ if (fix && fixable) {
69
+ writeFileSync(localPath(root, specPath), mirror.replace(spec.status));
70
+ fixed.push({ feature: queue.feature, specId: spec.id, file: specPath, from: frontmatter, to: spec.status });
71
+ row.frontmatter = spec.status;
72
+ } else drift.push({ feature: queue.feature, specId: spec.id, file: specPath, queue: spec.status, frontmatter, fixable, reason });
73
+ }
74
+ return row;
75
+ });
76
+ features.push({ feature: queue.feature, queuePath, pendingJournal, specs });
77
+ if (queue.specs.every(spec => spec.status === 'done')) readyToArchive.push({ feature: queue.feature, folder, openDecisions: openDecisions(root, folder) });
78
+ }
79
+ return { features, drift, fixed, readyToArchive, worktrees: worktreeCounts(root), problems };
80
+ }
81
+
82
+ export async function main(argv = process.argv.slice(2)) {
83
+ const flags = {};
84
+ for (let index = 0; index < argv.length; index += 1) {
85
+ if (argv[index] === '--fix') { flags['--fix'] = true; continue; }
86
+ if (argv[index] === '--root') { flags['--root'] = argv[index + 1]; index += 1; continue; }
87
+ throw new Error('Usage: status.mjs [--root <project>] [--fix]');
88
+ }
89
+ const result = projectStatus({ root: path.resolve(flags['--root'] ?? '.'), fix: flags['--fix'] === true });
90
+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
91
+ if (result.drift.length || result.problems.length) process.exitCode = 2;
92
+ return result;
93
+ }
94
+
95
+ if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
96
+ main().catch(error => { process.stderr.write(`Status stopped: ${error.message}\n`); process.exitCode = 1; });
97
+ }
@@ -0,0 +1,79 @@
1
+ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
2
+ import path from 'node:path';
3
+ import { pathToFileURL } from 'node:url';
4
+ import { checkGlob, globToRegExp } from './config.mjs';
5
+ import { parseJson, readLocal, relativePath, requireValue, validateQueue } from './identity.mjs';
6
+
7
+ // Tests name the acceptance criterion they check with [AC:<criterion-id>]. The
8
+ // trace shows which criteria have a test and which do not. It reports; the
9
+ // reviewer decides what a gap means (it never blocks completion by itself).
10
+ const tag = /\[AC:([A-Za-z0-9_.-]+)\]/g;
11
+
12
+ function filesMatching(root, glob) {
13
+ const pattern = globToRegExp(checkGlob(glob, '--tests'));
14
+ const out = [];
15
+ const walk = relative => {
16
+ let entries;
17
+ try { entries = readdirSync(path.join(root, relative || '.'), { withFileTypes: true }); } catch { return; }
18
+ for (const entry of entries) {
19
+ if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.joycraft') continue;
20
+ const child = relative ? `${relative}/${entry.name}` : entry.name;
21
+ if (entry.isDirectory()) walk(child);
22
+ else if (entry.isFile() && pattern.test(child)) out.push(child);
23
+ }
24
+ };
25
+ walk('');
26
+ return out;
27
+ }
28
+
29
+ /** Map each criterion of one spec to the test lines tagged with its ID. */
30
+ export function traceSpec({ root = process.cwd(), queuePath, specId, tests = [] }) {
31
+ queuePath = relativePath(queuePath);
32
+ const queue = parseJson(readLocal(root, queuePath), queuePath);
33
+ validateQueue(queue, { select: spec => spec.id === specId });
34
+ const spec = queue.specs.find(item => item.id === specId);
35
+ requireValue(spec, `Spec ${specId} does not exist in queue`);
36
+ const criteria = (spec.verification.criteria ?? []).map(item => item.id);
37
+ const declared = spec.verification.inputs.filter(input => input.kind === 'check' && input.state !== 'absent').map(input => relativePath(input.path));
38
+ // A declared check folder stands for every file inside it.
39
+ const expanded = declared.flatMap(file => existsSync(path.join(root, file)) && statSync(path.join(root, file)).isDirectory() ? filesMatching(root, `${file}/**`) : [file]);
40
+ const files = [...new Set([...expanded, ...tests.flatMap(glob => filesMatching(root, glob))])].sort();
41
+ const untraceableIds = criteria.filter(id => !/^[A-Za-z0-9_.-]+$/.test(id));
42
+ const traced = Object.fromEntries(criteria.map(id => [id, []]));
43
+ const unknownTags = [];
44
+ const missingFiles = [];
45
+ for (const file of files) {
46
+ const full = path.join(root, file);
47
+ if (!existsSync(full)) { missingFiles.push(file); continue; }
48
+ const lines = readFileSync(full, 'utf8').split('\n');
49
+ for (const [index, line] of lines.entries()) {
50
+ for (const match of line.matchAll(tag)) {
51
+ if (Object.hasOwn(traced, match[1])) traced[match[1]].push({ file, line: index + 1 });
52
+ else unknownTags.push({ id: match[1], file, line: index + 1 });
53
+ }
54
+ }
55
+ }
56
+ const untraced = criteria.filter(id => traced[id].length === 0);
57
+ return {
58
+ queuePath, specId, files, criteria: criteria.map(id => ({ id, tests: traced[id] })), untraced, unknownTags, missingFiles,
59
+ ...(untraceableIds.length ? { untraceableIds, untraceableNote: 'These criterion IDs contain characters an [AC:<id>] tag cannot hold; use letters, digits, ., _ and -.' } : {}),
60
+ ...(files.length === 0 ? { note: 'No check inputs are declared and no --tests glob was given.' } : {}),
61
+ };
62
+ }
63
+
64
+ export async function main(argv = process.argv.slice(2)) {
65
+ const flags = { '--tests': [] };
66
+ for (let index = 0; index < argv.length; index += 2) {
67
+ requireValue(['--root', '--queue', '--spec', '--tests'].includes(argv[index]) && argv[index + 1], 'Usage: trace.mjs --queue <queue> --spec <id> [--tests <glob>]... [--root <project>]');
68
+ if (argv[index] === '--tests') flags['--tests'].push(argv[index + 1]); else flags[argv[index]] = argv[index + 1];
69
+ }
70
+ requireValue(/^(?:0|[1-9]\d*)$/.test(flags['--spec'] ?? ''), 'Spec ID must be a nonnegative integer');
71
+ const result = traceSpec({ root: path.resolve(flags['--root'] ?? '.'), queuePath: flags['--queue'], specId: Number(flags['--spec']), tests: flags['--tests'] });
72
+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
73
+ if (result.untraced.length) process.exitCode = 2;
74
+ return result;
75
+ }
76
+
77
+ if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
78
+ main().catch(error => { process.stderr.write(`Trace stopped: ${error.message}\n`); process.exitCode = 1; });
79
+ }
@@ -0,0 +1,201 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
3
+ import path from 'node:path';
4
+ import { pathToFileURL } from 'node:url';
5
+ import { ensureLocal, mainTree, withLock } from './coordinator.mjs';
6
+ import { isObject, parseJson, readLocal, relativePath, requireValue, validateQueue } from './identity.mjs';
7
+
8
+ // Worker worktrees have one home and one ledger, so a later session can tell
9
+ // its own trees from someone else's and release them once their work is in.
10
+ export const ledgerPath = '.joycraft/local/worktrees.json';
11
+ export const treeHome = '.joycraft/local/worktrees';
12
+
13
+ const git = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
14
+ const gitOk = (cwd, args) => { try { git(cwd, args); return true; } catch { return false; } };
15
+
16
+ // The ledger and tree home live in the main checkout, so a coordinator in any
17
+ // linked tree reads and writes the same records.
18
+ function gitRoot(root) {
19
+ try { git(root, ['rev-parse', '--show-toplevel']); } catch { throw new Error(`Not a Git working tree: ${root}`); }
20
+ return mainTree(root);
21
+ }
22
+
23
+ export function readLedger(root) {
24
+ const file = path.join(root, ledgerPath);
25
+ if (!existsSync(file)) return { schemaVersion: 1, trees: [] };
26
+ const ledger = parseJson(readFileSync(file), ledgerPath);
27
+ requireValue(isObject(ledger) && ledger.schemaVersion === 1 && Array.isArray(ledger.trees), `Unsupported worktree ledger: ${ledgerPath}`);
28
+ return ledger;
29
+ }
30
+
31
+ function writeLedger(root, ledger) {
32
+ ensureLocal(root);
33
+ writeFileSync(path.join(root, ledgerPath), `${JSON.stringify(ledger, null, 2)}\n`);
34
+ }
35
+
36
+ function readQueueFile(root, queuePath) {
37
+ const queue = parseJson(readLocal(root, queuePath), queuePath);
38
+ validateQueue(queue, { select: () => false });
39
+ return queue;
40
+ }
41
+
42
+ /** Create a worker tree for one spec from a captured base revision and record its owner. */
43
+ export function createWorktree({ root = process.cwd(), queuePath, specId, session, base = 'HEAD' }) {
44
+ root = gitRoot(root);
45
+ queuePath = relativePath(queuePath);
46
+ requireValue(typeof session === 'string' && session.trim(), 'Creating a worker tree needs the coordinator --session');
47
+ const queue = readQueueFile(root, queuePath);
48
+ requireValue(/^[a-z0-9][a-z0-9-]*$/.test(queue.feature), 'Worker trees need a queue feature that is a lowercase slug');
49
+ requireValue(queue.specs.some(spec => spec.id === specId), `Spec ${specId} does not exist in queue`);
50
+ const name = `${queue.feature}-${specId}`;
51
+ const treePath = `${treeHome}/${name}`;
52
+ const branch = `joycraft/${name}`;
53
+ let baseRevision;
54
+ try { baseRevision = git(root, ['rev-parse', '--verify', `${base}^{commit}`]).trim(); } catch { throw new Error(`Unknown base revision: ${base}`); }
55
+ ensureLocal(root);
56
+ return withLock(path.join(root, ledgerPath), () => {
57
+ const ledger = readLedger(root);
58
+ requireValue(!ledger.trees.some(tree => tree.path === treePath), `A worker tree for spec ${specId} is already recorded: ${treePath}; run prune or list first`);
59
+ requireValue(!existsSync(path.join(root, treePath)), `Worker tree path already exists: ${treePath}`);
60
+ mkdirSync(path.join(root, treeHome), { recursive: true });
61
+ git(root, ['worktree', 'add', '-b', branch, treePath, baseRevision]);
62
+ const entry = { path: treePath, branch, feature: queue.feature, queuePath, specId, baseRevision, coordinatorSession: session, createdAt: new Date().toISOString() };
63
+ ledger.trees.push(entry);
64
+ writeLedger(root, ledger);
65
+ return { ...entry, next: 'Run the project bootstrap in this tree before any edit.' };
66
+ });
67
+ }
68
+
69
+ function linkedTrees(root) {
70
+ const blocks = git(root, ['worktree', 'list', '--porcelain']).split(/\n\n+/).filter(Boolean);
71
+ const trees = blocks.map(block => {
72
+ const tree = {};
73
+ for (const line of block.split('\n')) {
74
+ const [key, ...rest] = line.split(' ');
75
+ tree[key] = rest.join(' ') || true;
76
+ }
77
+ return tree;
78
+ });
79
+ // The first entry is the main working tree; the coordinator never prunes itself.
80
+ return trees.slice(1).filter(tree => !existsSync(tree.worktree) || realpathSync(tree.worktree) !== root);
81
+ }
82
+
83
+ function sizeOf(target) {
84
+ let total = 0;
85
+ const stack = [target];
86
+ while (stack.length) {
87
+ const current = stack.pop();
88
+ let stat;
89
+ try { stat = lstatSync(current); } catch { continue; }
90
+ if (stat.isDirectory()) for (const name of readdirSync(current)) stack.push(path.join(current, name));
91
+ else total += stat.size;
92
+ }
93
+ return total;
94
+ }
95
+
96
+ function queueSpec(root, entry, queues) {
97
+ try {
98
+ if (!queues.has(entry.queuePath)) queues.set(entry.queuePath, readQueueFile(root, entry.queuePath));
99
+ return queues.get(entry.queuePath).specs.find(spec => spec.id === entry.specId) ?? { status: 'missing' };
100
+ } catch { return { status: 'unknown' }; }
101
+ }
102
+
103
+ // Ignored files are not "uncommitted changes", so git removes them with the tree.
104
+ // List them, and name accepted evidence that exists only in this tree.
105
+ function ignoredEntries(tree) {
106
+ return git(tree, ['status', '--ignored', '--porcelain']).split('\n').filter(line => line.startsWith('!! ')).map(line => line.slice(3));
107
+ }
108
+
109
+ function evidenceOnlyHere(root, tree, spec) {
110
+ return [spec.acceptedReport?.path, spec.ownerAcceptance?.path].filter(Boolean)
111
+ .filter(file => existsSync(path.join(tree, file)) && !existsSync(path.join(root, file)));
112
+ }
113
+
114
+ /** Every linked tree with its owner, spec status, merged and clean state. */
115
+ export function listWorktrees({ root = process.cwd(), into = 'HEAD', sizes = true } = {}) {
116
+ root = gitRoot(root);
117
+ const ledger = readLedger(root);
118
+ const owned = new Map(ledger.trees.map(entry => [path.resolve(root, entry.path), entry]));
119
+ const queues = new Map();
120
+ const seen = new Set();
121
+ const trees = linkedTrees(root).map(tree => {
122
+ const absolute = existsSync(tree.worktree) ? realpathSync(tree.worktree) : tree.worktree;
123
+ const entry = owned.get(absolute) ?? owned.get(tree.worktree);
124
+ if (entry) seen.add(entry.path);
125
+ const exists = existsSync(absolute);
126
+ const spec = entry ? queueSpec(root, entry, queues) : null;
127
+ const record = {
128
+ path: path.relative(root, absolute) || '.',
129
+ branch: typeof tree.branch === 'string' ? tree.branch.replace(/^refs\/heads\//, '') : null,
130
+ owner: entry ? 'joycraft' : 'unknown-owner',
131
+ ...(entry ? { feature: entry.feature, specId: entry.specId, coordinatorSession: entry.coordinatorSession, ledgerBranch: entry.branch, specStatus: spec.status } : {}),
132
+ ...(entry && exists ? { ignored: ignoredEntries(absolute), evidenceOnlyHere: evidenceOnlyHere(root, absolute, spec) } : {}),
133
+ merged: typeof tree.HEAD === 'string' && gitOk(root, ['merge-base', '--is-ancestor', tree.HEAD, into]),
134
+ clean: exists && gitOk(absolute, ['diff', '--quiet', 'HEAD']) && git(absolute, ['status', '--porcelain']).trim() === '',
135
+ exists,
136
+ };
137
+ if (sizes) record.bytes = exists ? sizeOf(absolute) : 0;
138
+ return record;
139
+ });
140
+ const missing = ledger.trees.filter(entry => !seen.has(entry.path)).map(entry => ({ path: entry.path, branch: entry.branch, owner: 'joycraft', feature: entry.feature, specId: entry.specId, exists: false, missing: true }));
141
+ return { root, into, trees: [...trees, ...missing] };
142
+ }
143
+
144
+ function decide(tree) {
145
+ if (tree.owner === 'joycraft' && !tree.exists) return { action: 'forget', reason: 'Recorded tree no longer exists; drop the ledger entry.' };
146
+ if (tree.owner !== 'joycraft') return { action: 'keep', reason: 'Not created by worktrees.mjs; inspect it, then remove it with git worktree remove if it is yours.' };
147
+ if (tree.specStatus !== 'done') return { action: 'keep', reason: `Spec ${tree.specId} is ${tree.specStatus}; keep the tree until it is done.` };
148
+ if (!tree.clean) return { action: 'keep', reason: 'The tree has uncommitted changes; commit or discard them first.' };
149
+ if (!tree.merged) return { action: 'keep', reason: 'The branch has commits that are not in the integration ref.' };
150
+ if (tree.evidenceOnlyHere.length) return { action: 'keep', reason: `Accepted evidence exists only in this tree: ${tree.evidenceOnlyHere.join(', ')}; copy it to the main checkout first.` };
151
+ return { action: 'remove', reason: 'Spec done, tree clean, branch integrated.', ...(tree.ignored.length ? { deletesIgnored: tree.ignored } : {}) };
152
+ }
153
+
154
+ /** Preview by default; apply removes only owned, clean, integrated trees of done specs. */
155
+ export function pruneWorktrees({ root = process.cwd(), into = 'HEAD', apply = false } = {}) {
156
+ const listing = listWorktrees({ root, into, sizes: false });
157
+ root = listing.root;
158
+ const plan = listing.trees.map(tree => ({ path: tree.path, branch: tree.branch, specId: tree.specId, ...decide(tree), ledgerBranch: tree.ledgerBranch }));
159
+ const strip = items => items.map(({ ledgerBranch, ...item }) => item);
160
+ if (!apply) return { applied: false, into, plan: strip(plan) };
161
+ ensureLocal(root);
162
+ return withLock(path.join(root, ledgerPath), () => {
163
+ const ledger = readLedger(root);
164
+ for (const item of plan.filter(item => item.action !== 'keep')) {
165
+ if (item.action === 'remove') {
166
+ try { git(root, ['worktree', 'remove', item.path]); } catch (error) {
167
+ item.action = 'keep'; item.reason = `git worktree remove refused: ${String(error.stderr ?? error.message).trim()}`; continue;
168
+ }
169
+ // Delete only the branch Joycraft created, and only if it is merged (-d).
170
+ item.branchDeleted = item.branch !== null && item.branch === item.ledgerBranch && gitOk(root, ['branch', '-d', item.branch]);
171
+ }
172
+ ledger.trees = ledger.trees.filter(entry => entry.path !== item.path);
173
+ }
174
+ gitOk(root, ['worktree', 'prune']);
175
+ writeLedger(root, ledger);
176
+ return { applied: true, into, plan: strip(plan) };
177
+ });
178
+ }
179
+
180
+ export async function main(argv = process.argv.slice(2)) {
181
+ const [command, ...rest] = argv;
182
+ const flags = {};
183
+ for (let index = 0; index < rest.length; index += 1) {
184
+ if (['--apply', '--no-size'].includes(rest[index])) { flags[rest[index]] = true; continue; }
185
+ flags[rest[index]] = rest[index + 1]; index += 1;
186
+ }
187
+ const root = path.resolve(flags['--root'] ?? '.');
188
+ let result;
189
+ if (command === 'create') {
190
+ requireValue(/^(?:0|[1-9]\d*)$/.test(flags['--spec'] ?? ''), 'Spec ID must be a nonnegative integer');
191
+ result = createWorktree({ root, queuePath: flags['--queue'], specId: Number(flags['--spec']), session: flags['--session'], base: flags['--base'] ?? 'HEAD' });
192
+ } else if (command === 'list') result = listWorktrees({ root, into: flags['--into'] ?? 'HEAD', sizes: flags['--no-size'] !== true });
193
+ else if (command === 'prune') result = pruneWorktrees({ root, into: flags['--into'] ?? 'HEAD', apply: flags['--apply'] === true });
194
+ else throw new Error('Usage: worktrees.mjs create --queue <queue> --spec <id> --session <coordinator> [--base <rev>] | list [--into <ref>] [--no-size] | prune [--into <ref>] [--apply] [--root <project>]');
195
+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
196
+ return result;
197
+ }
198
+
199
+ if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
200
+ main().catch(error => { process.stderr.write(`Worktrees stopped: ${error.message}\n`); process.exitCode = 1; });
201
+ }
@@ -0,0 +1,19 @@
1
+ # joycraft.yaml: project settings for Joycraft. This file is yours; Joycraft only
2
+ # reads it. Every setting is optional; delete what you do not change.
3
+
4
+ paths:
5
+ features: docs/features # working briefs and specs (not current knowledge)
6
+ archive: docs/archive # finished features (history)
7
+ context: docs/context # current project knowledge
8
+
9
+ hooks:
10
+ # Runs once after a feature is archived, from the project root, with
11
+ # JOYCRAFT_FEATURE, JOYCRAFT_ARCHIVE_PATH and JOYCRAFT_SOURCE_PATH set.
12
+ # afterArchive: node scripts/wiki-sync.mjs
13
+
14
+ cleanup:
15
+ # Code that each context page describes. cleanup.mjs flags a page when this
16
+ # code changed after the page last changed.
17
+ impact: []
18
+ # - source: src/auction/**
19
+ # docs: [docs/context/auction-rules.md]
package/payload/PIN CHANGED
@@ -1,67 +1,76 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "source": "joycraft-prototype",
4
- "tag": "field-7",
5
- "commit": "df3df23ef782cea2cadbe14933fc4db760ea382c",
4
+ "tag": "field-9",
5
+ "commit": "f1ce2d0b2c07e8512247d176b7c8f79045c63f07",
6
6
  "files": {
7
+ ".agents/skills/joycraft-cleanup/SKILL.md": "e9a6eda4773332d87cc6a13cc939aaa5d3ea1ec1f980b1132a6794740cdfe39f",
7
8
  ".agents/skills/joycraft-context/SKILL.md": "e0a5f7d82fe8b6b6d3aeab38f7cf570ca939dba07034243af1ef86d24448c084",
8
9
  ".agents/skills/joycraft-decompose/SKILL.md": "a24c9d9cf2dc7af4b99ad67575b64b9d0c99818044f7fafc3a5243dc4c557b5f",
9
- ".agents/skills/joycraft-entry/SKILL.md": "c8985b43fcd225fbea7622290a83a8d1a994ed19a057634b69d1d7c0324dee56",
10
- ".agents/skills/joycraft-implement/SKILL.md": "49e6b65936649bca22a7862045235538704acfe23e49f415ba1c919c10e2cbde",
10
+ ".agents/skills/joycraft-entry/SKILL.md": "c6102aca5e8f7e864a963ab1b3fa26007ef6118dee30a3eb59af55a3a52c9c8d",
11
+ ".agents/skills/joycraft-implement/SKILL.md": "075832c85f6bff177eca45f5ce4412f6a6661fe9be9213674ddc2f74c2dc211e",
11
12
  ".agents/skills/joycraft-retro/SKILL.md": "156f36cb047604c734bf273bd02822d964b6af86619ed6c2a30fa6d79eb9a986",
12
13
  ".agents/skills/joycraft-retro/agents/openai.yaml": "f0eb4732261635f41e08f0bbe9a931d62fd8ac645149d3406e6fc7e16a81750b",
13
- ".agents/skills/joycraft-session-end/SKILL.md": "c2d2282e8fed0edfb91db9042380ec9902cddb32cf140a3b6e4e5ee8e227de0e",
14
+ ".agents/skills/joycraft-session-end/SKILL.md": "31fd6ef54b46fec92a7e52e381a8e25886239d0e3c3ce8ca820c3be6fa1e1877",
14
15
  ".agents/skills/joycraft-testing/SKILL.md": "89e983b285099c38821dc807311b27d450e6dec9fb691cd687ca74332b091157",
15
16
  ".agents/skills/joycraft-ui-slice/SKILL.md": "fcb5f109c9bd23d4afe5b47d19c90fd34485754ce9061c64bce1ae2ce0376484",
16
17
  ".agents/skills/joycraft-ui-slice/scripts/serve.mjs": "c16858800b6fbe6f7a3a21b21e785ad70c9a89a3fe970bc08701fefeac5042fa",
17
- ".agents/skills/joycraft-verify/SKILL.md": "cce30cf1ee39b6a6aa0211a661660ef9be9ec55bb83650456ddac0bac0037274",
18
- ".claude/agents/joycraft-implementer.md": "11281faae296097ea8f5d8780629dc83b6a918830eab8c252d665b1653a34338",
19
- ".claude/agents/joycraft-reviewer.md": "e54107707d453aba73e6acbb4ef1d26b4ad89291183abec7d8ea49a520aed9d5",
18
+ ".agents/skills/joycraft-verify/SKILL.md": "f18eda5910e1ca5c312f5185b0dbceb4dc09fb9d73951e64410b5d59db046511",
19
+ ".claude/agents/joycraft-implementer.md": "30b26779bd49d2d66758bcb26442e78755b018a3830ac52ff634ebf057ce1cc5",
20
+ ".claude/agents/joycraft-reviewer.md": "488b1923115257dbe966bbe4717d21f95900b18cff68febd848e1f8f362a9d37",
20
21
  ".joycraft/assets/artifacts/kit.css": "9b04b739b3b137d4a3052a939cbc46b5acb9abde085989bd599481ae40e5c6a9",
21
22
  ".joycraft/assets/artifacts/kit.js": "e54db2157cfee278f5e6777b6b6fe2d2f5297cd2401b173d1a4b72e3fad00562",
22
23
  ".joycraft/assets/artifacts/transports.js": "e53c67ac030a1d7c9ce4666b998604a471598cb4df08bc83f37e3d166b8017eb",
23
24
  ".joycraft/contracts/types.d.ts": "5c4e654ea929778c586bc6cce44e60dc031578b2414dd1b8161359cf9f424b41",
24
25
  ".joycraft/references/architecture.md": "52eaaa4b88053481c9f8cad2418ea0f1db880184c3a50c95901f30f24be75852",
25
- ".joycraft/references/archive.md": "d421e17ed3724fc1dacc9f3397a50d7976329d5dfb5e274791931df5544d5be4",
26
+ ".joycraft/references/archive.md": "7deca056a93b21c97d82633bcdf5acf6c77bf2c59b2430e648f665923c020794",
26
27
  ".joycraft/references/artifacts.md": "1f21223601342f4ce54c4d76320f89f4eea1c8d0089396495993ba62155f422e",
28
+ ".joycraft/references/cleanup.md": "c223e17ea970fd528b44f0f22e614763d2281b49531c1ee566b3fba60417eeac",
27
29
  ".joycraft/references/completion.md": "7df48664861f41e2e503a828e97d6b6f615745591a3f47f17d196fa4d24a122d",
28
- ".joycraft/references/context.md": "22967383c85e36153b57ed301b51f0a5fed9ccd0a1114226ade6d88b81076215",
30
+ ".joycraft/references/context.md": "f2c8313eaf996b633040e52855ae1eef57b03cad2b024bb5eacb70b38d39ca95",
29
31
  ".joycraft/references/delivery.md": "1afc417ee3922ebf5e84c0ae87796d6cb6305679c0257ed38a35f396949de5e8",
30
- ".joycraft/references/dispatch.md": "9368b93f35af7271718136c256f325cefc459d428e3aba445fc650d57370484b",
32
+ ".joycraft/references/dispatch.md": "b80d6899c52b7c003012fdfc774be271773213b7fedc37f4c247b431cdf8207d",
31
33
  ".joycraft/references/recurring-failures.md": "7080f6c55492bc19c2897f4f0b128a830a71cdb516678c79ff6e97ffa1dc6b86",
32
34
  ".joycraft/references/retro.md": "f359eae19747777fb4687c1bc7eb280f0319ae629ee62913346e60fc56551562",
33
- ".joycraft/references/setup.md": "39642785bd205e7663914bf186c8747878c6763da408b1ce004123f55bbae755",
34
- ".joycraft/references/testing.md": "064edc82feb4c29485e9b5d9fbc5140d1f908d77006963482445ae1e4793fc2f",
35
+ ".joycraft/references/setup.md": "ab06b0b7b83cb141b04f4ad75af1e28beb278c3b39a29acbb07fd8580bf0ca1f",
36
+ ".joycraft/references/testing.md": "7a0be4a5424f0fac89cba6e896c66a50948e31332bb7f032f688d72a203e4f4d",
35
37
  ".joycraft/references/update.md": "8e26ddaa21d3b133902bebcb6662a16f52f3ae3f04c51c69fdb325a8e9c0aeac",
36
- ".joycraft/references/workflow.md": "1e982310f98cb61749ff921f96c7aa2da52fcd3df4eb444608216fbf6e126a53",
37
- ".joycraft/references/worktrees.md": "00c151b62d433bc7aecb669ba17795c1011e3bc18828b9cb63c506d83bd852bc",
38
- ".joycraft/runtime/archive.mjs": "44a2953e60af1aa231f4b8affba3d51058b58bc025a72ae1affdbe7c3182f9d1",
38
+ ".joycraft/references/workflow.md": "ed4a6618ab3288ea213691e4485f580d8348f717b6e663d29fbb570541e42c2c",
39
+ ".joycraft/references/worktrees.md": "fb18af0cd76d4e3c5d5b892a7ae10946f21f189e642243235c188b571635f735",
40
+ ".joycraft/runtime/archive.mjs": "c153f5407fe6abffe5cf9655b0ff40db2254712a1bfee429dad93251bb7d0121",
39
41
  ".joycraft/runtime/artifacts/cli.mjs": "d30152e6829e07d9c7ff6ceedbfa6813931674d8529778f62b0d64e3a4049ab0",
40
42
  ".joycraft/runtime/artifacts/decisions.mjs": "9cba81346daf59cd020b8d976af98b1f6c2aec8d0a1575e5e0f806334ae622d0",
41
43
  ".joycraft/runtime/artifacts/model.mjs": "fbe44d37049759387ecc02ba2580c94e26e6c5cb8cac3dcbcc79aeab3b75756b",
42
44
  ".joycraft/runtime/artifacts/preferences.mjs": "9165e1c753aa8533affe976cacecb135b0ee3cc9f455f5f80b1568103bb49fd6",
43
45
  ".joycraft/runtime/artifacts/render.mjs": "488673cab94fa6bfde223c2c41650f8e183f7ac0be3840d371ee057d95ea0fa5",
44
46
  ".joycraft/runtime/artifacts/server.mjs": "a96048fad649e8053c70ce95c5a757929ab57ae9de27198121224326551c0a05",
47
+ ".joycraft/runtime/cleanup.mjs": "0fb9aac9b266b2efbaddb6a3984ee9afb4544f8aca24f1bcc50e4eedb80818cc",
45
48
  ".joycraft/runtime/completion.mjs": "11635b11eb7df90398a69b6d41f96d9c7b9d2dc2255ae4a4a129562d46572ec1",
49
+ ".joycraft/runtime/config.mjs": "7b5a0eb268149251fd5c31238efdf71abed70be4df982c720f842cb0511f59b0",
46
50
  ".joycraft/runtime/context/cli.mjs": "40adc206c8c3b7f4f5bedffb097d9ae1b0718f0586a055796e4987e9c3088eee",
47
51
  ".joycraft/runtime/context/index.mjs": "5a69d33d9a1a66ef23301e952ecb1ec427ff4b0baf408ede67a2600d3f2a173c",
48
- ".joycraft/runtime/context/search.mjs": "e7f48d8ada52574ddca22d0eaee5ce2a405c4074910879e47c01ca287bba52b4",
52
+ ".joycraft/runtime/context/search.mjs": "e32a42ba9b168ca7c68fed46d47a79250c27aa4c07c0835feae084b5d1e0d0ca",
53
+ ".joycraft/runtime/coordinator.mjs": "6c120f4bcca76f5e976a5afd0be676cba82c1f25c10ac2def2ae3163bb4dc7c5",
49
54
  ".joycraft/runtime/delivery.mjs": "4fe897714eec33b24003f0d69abe1522a5199193ab7333fa6421776ee048df1c",
50
55
  ".joycraft/runtime/dispatch-preflight.mjs": "1b8283c06c8a2a41bfca06b1d5f0f83a093825911fbab1e04657dee06fa91c5d",
51
- ".joycraft/runtime/dispatch-start.mjs": "e7879d20348c1e442c7f586eadabf99abf3c52df34b0d352664797d06d0c4d96",
56
+ ".joycraft/runtime/dispatch-start.mjs": "b8d27b53566062c79cb95bf3f89bcb3e4abc9dd9dc15612cfced8685cf3a1c41",
52
57
  ".joycraft/runtime/evidence.mjs": "80a386dd6d81e5fd32c64e53d5fb089072bc28f36df6c4f6c924077dd064604b",
53
58
  ".joycraft/runtime/identity.mjs": "f5a10dd58f2dd259502b04eaa2af42d2a74a09614e097a6efc35104c80bba024",
54
59
  ".joycraft/runtime/kickoff.mjs": "9d96998bff94662863182b9a922f26732c649b7a0b0130b6da7d63ec73eb3590",
55
60
  ".joycraft/runtime/redact.mjs": "cc8c0fe5e8d8fe78116ef126f6eee757a247739084e19c342bcf09a2b06524bc",
56
61
  ".joycraft/runtime/retro.mjs": "6f3664b0d50c12d4f2d8eef4b4d0d62897939d03e45860d4dcf35c0f5f92677c",
57
- ".joycraft/runtime/review-tools.json": "e4bc5ba2e0f6ab71a8af90a6f225f4655b9c1e7ee13d9303bd6e219002547a96",
62
+ ".joycraft/runtime/review-tools.json": "c00e4209d67fd655a351946509a2aba2ee287dbaa0a1ad60c22e1286de0b4893",
58
63
  ".joycraft/runtime/review-tools.mjs": "17c13f7ab746478bce5711501a5190991b46616c849780196614950cfc6f0208",
59
64
  ".joycraft/runtime/scope.mjs": "e2cdd929596246bf24e18850698db440119badc7068a3c5beab03ded45abbd65",
65
+ ".joycraft/runtime/status.mjs": "0b8c7535409c1b47f8227e430c3edb98c942abeb3457c5d6f6dd4ae2e2d855b8",
66
+ ".joycraft/runtime/trace.mjs": "51e0a8e9d4b0fc1e97042bed7b89397f7b2a4db2234f547c613720f029b2e1ae",
60
67
  ".joycraft/runtime/update-check.mjs": "324b2eda4ac1feb6bb5b15ef488bea5f2f8a6312bc7b1c24719e0b7fd6a84634",
68
+ ".joycraft/runtime/worktrees.mjs": "ba11b2e3fe96f47275c1dfddd087b7d40b8989e3d73f6187cb04887b5a66cd7f",
61
69
  ".joycraft/templates/README.md": "56a166d0729e8b6c3bcb098afb8145006259357087fd8b1f1f343d9a2b4d36e0",
62
70
  ".joycraft/templates/artifact.json": "fda5f7c32516d6ab094ee0e8506d84a1a0d6d4d0f49048b01aa392c619996f05",
63
71
  ".joycraft/templates/brief.md": "03479342500570aba9fb206beef6f6049fd180bec814dd8001987174aecfef25",
64
72
  ".joycraft/templates/decisions.md": "49e0c9b3efe51d1c2e87345fcefe23ef0579e524d50febef8ef43a35141c8002",
73
+ ".joycraft/templates/joycraft.yaml": "3aa465896e58cfec956040d9f2b13ce4f4be84c027a6bb1a3e2a9c0e834d2ace",
65
74
  ".joycraft/templates/project-context.md": "d7c81fee08609a7db45c5df0cb2bd5cb3409760169d8b03cc5f19b1ff82d03c2",
66
75
  ".joycraft/templates/queue.json": "88f922b6cc47b80befc27df86a143d6bae0b30869c46d712958b64291e5ebcc2",
67
76
  ".joycraft/templates/spec.md": "5f4b1490c2ba2e47ced1ef5b369fe3e41386eb61386c42c7a561b1e8af02ea5e",