joycraft 0.7.16 → 1.0.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.
- package/README.md +137 -156
- package/dist/cli.js +1593 -373
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +4 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -1
- package/dist/joycraft-release.json +1 -1
- package/package.json +9 -3
- package/payload/.agents/skills/joycraft-context/SKILL.md +36 -0
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +68 -0
- package/payload/.agents/skills/joycraft-entry/SKILL.md +103 -0
- package/payload/.agents/skills/joycraft-implement/SKILL.md +106 -0
- package/payload/.agents/skills/joycraft-retro/SKILL.md +54 -0
- package/payload/.agents/skills/joycraft-retro/agents/openai.yaml +5 -0
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +78 -0
- package/payload/.agents/skills/joycraft-testing/SKILL.md +60 -0
- package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +59 -0
- package/payload/.agents/skills/joycraft-ui-slice/scripts/serve.mjs +97 -0
- package/payload/.agents/skills/joycraft-verify/SKILL.md +103 -0
- package/payload/.claude/agents/joycraft-implementer.md +31 -0
- package/payload/.claude/agents/joycraft-reviewer.md +30 -0
- package/payload/.joycraft/assets/artifacts/kit.css +102 -0
- package/payload/.joycraft/assets/artifacts/kit.js +301 -0
- package/payload/.joycraft/assets/artifacts/transports.js +236 -0
- package/payload/.joycraft/contracts/types.d.ts +185 -0
- package/payload/.joycraft/references/architecture.md +90 -0
- package/payload/.joycraft/references/archive.md +211 -0
- package/payload/.joycraft/references/artifacts.md +176 -0
- package/payload/.joycraft/references/completion.md +109 -0
- package/payload/.joycraft/references/context.md +80 -0
- package/payload/.joycraft/references/delivery.md +32 -0
- package/payload/.joycraft/references/dispatch.md +226 -0
- package/payload/.joycraft/references/recurring-failures.md +33 -0
- package/payload/.joycraft/references/retro.md +94 -0
- package/payload/.joycraft/references/setup.md +279 -0
- package/payload/.joycraft/references/testing.md +120 -0
- package/payload/.joycraft/references/update.md +44 -0
- package/payload/.joycraft/references/workflow.md +113 -0
- package/payload/.joycraft/references/worktrees.md +148 -0
- package/payload/.joycraft/runtime/archive.mjs +463 -0
- package/payload/.joycraft/runtime/artifacts/cli.mjs +61 -0
- package/payload/.joycraft/runtime/artifacts/decisions.mjs +214 -0
- package/payload/.joycraft/runtime/artifacts/model.mjs +161 -0
- package/payload/.joycraft/runtime/artifacts/preferences.mjs +127 -0
- package/payload/.joycraft/runtime/artifacts/render.mjs +21 -0
- package/payload/.joycraft/runtime/artifacts/server.mjs +40 -0
- package/payload/.joycraft/runtime/completion.mjs +300 -0
- package/payload/.joycraft/runtime/context/cli.mjs +75 -0
- package/payload/.joycraft/runtime/context/index.mjs +29 -0
- package/payload/.joycraft/runtime/context/search.mjs +149 -0
- package/payload/.joycraft/runtime/delivery.mjs +142 -0
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +535 -0
- package/payload/.joycraft/runtime/dispatch-start.mjs +98 -0
- package/payload/.joycraft/runtime/evidence.mjs +137 -0
- package/payload/.joycraft/runtime/identity.mjs +486 -0
- package/payload/.joycraft/runtime/kickoff.mjs +174 -0
- package/payload/.joycraft/runtime/redact.mjs +9 -0
- package/payload/.joycraft/runtime/retro.mjs +151 -0
- package/payload/.joycraft/runtime/review-tools.json +34 -0
- package/payload/.joycraft/runtime/review-tools.mjs +331 -0
- package/payload/.joycraft/runtime/scope.mjs +129 -0
- package/payload/.joycraft/runtime/update-check.mjs +142 -0
- package/payload/.joycraft/templates/README.md +7 -0
- package/payload/.joycraft/templates/artifact.json +33 -0
- package/payload/.joycraft/templates/brief.md +35 -0
- package/payload/.joycraft/templates/decisions.md +13 -0
- package/payload/.joycraft/templates/project-context.md +36 -0
- package/payload/.joycraft/templates/queue.json +27 -0
- package/payload/.joycraft/templates/spec.md +39 -0
- package/payload/.joycraft/templates/ui-slice.html +71 -0
- package/payload/PIN +74 -0
- package/payload/scripts/export.mjs +301 -0
- package/payload/scripts/hook-paths.mjs +35 -0
- package/payload/scripts/legacy-hooks.mjs +128 -0
- package/payload/scripts/legacy-inventory.json +117 -0
- package/dist/chunk-35RQLGKM.js +0 -2167
- package/dist/chunk-35RQLGKM.js.map +0 -1
- package/dist/chunk-7BPB2IKY.js +0 -255
- package/dist/chunk-7BPB2IKY.js.map +0 -1
- package/dist/chunk-B73DPYYC.js +0 -377
- package/dist/chunk-B73DPYYC.js.map +0 -1
- package/dist/chunk-GTP7Z52K.js +0 -3942
- package/dist/chunk-GTP7Z52K.js.map +0 -1
- package/dist/chunk-K4AI6FKB.js +0 -417
- package/dist/chunk-K4AI6FKB.js.map +0 -1
- package/dist/chunk-KKDKC4FM.js +0 -115
- package/dist/chunk-KKDKC4FM.js.map +0 -1
- package/dist/chunk-OMFGDJW4.js +0 -97
- package/dist/chunk-OMFGDJW4.js.map +0 -1
- package/dist/chunk-Z5JFEGWG.js +0 -563
- package/dist/chunk-Z5JFEGWG.js.map +0 -1
- package/dist/init-MUB5CC6L.js +0 -60
- package/dist/init-MUB5CC6L.js.map +0 -1
- package/dist/init-autofix-2DMBO4QN.js +0 -122
- package/dist/init-autofix-2DMBO4QN.js.map +0 -1
- package/dist/install-manifest-EQHT4474.js +0 -37
- package/dist/install-manifest-EQHT4474.js.map +0 -1
- package/dist/release-artifact-4TL5L2ZY.js +0 -14
- package/dist/release-artifact-4TL5L2ZY.js.map +0 -1
- package/dist/release-resolver-P2H46QTU.js +0 -293
- package/dist/release-resolver-P2H46QTU.js.map +0 -1
- package/dist/telemetry-store-IBO5GRTA.js +0 -14
- package/dist/telemetry-store-IBO5GRTA.js.map +0 -1
- package/dist/update-LFLQTPUA.js +0 -19
- package/dist/update-LFLQTPUA.js.map +0 -1
- package/dist/update-check-YT765NE7.js +0 -36
- package/dist/update-check-YT765NE7.js.map +0 -1
- package/dist/upgrade-L5WERK4X.js +0 -28
- package/dist/upgrade-L5WERK4X.js.map +0 -1
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
(function artifactTransports(global) {
|
|
2
|
+
'use strict';
|
|
3
|
+
|
|
4
|
+
var SCHEMA_VERSION = 1;
|
|
5
|
+
var RESPONSE_KIND = 'joycraft-artifact-responses';
|
|
6
|
+
var MAX_NOTE_LENGTH = 4000;
|
|
7
|
+
var QUESTION_STATES = new Set(['open', 'assigned', 'clarified', 'settled', 'backlogged', 'discarded']);
|
|
8
|
+
|
|
9
|
+
function fail(message) { throw new Error(message); }
|
|
10
|
+
function nonempty(value) { return typeof value === 'string' && value.trim().length > 0; }
|
|
11
|
+
function own(object, key) { return Object.prototype.hasOwnProperty.call(object, key); }
|
|
12
|
+
|
|
13
|
+
function validateModel(model) {
|
|
14
|
+
if (!model || typeof model !== 'object' || Array.isArray(model) || !nonempty(model.artifactId)) fail('Artifact model needs an artifactId.');
|
|
15
|
+
if (!model.source || !nonempty(model.source.path) || !nonempty(model.source.revision) || (model.source.viewRevision !== undefined && !nonempty(model.source.viewRevision))) fail('Artifact model needs a source path and revision.');
|
|
16
|
+
if (!Array.isArray(model.questions)) fail('Artifact model needs questions.');
|
|
17
|
+
var ids = new Set();
|
|
18
|
+
model.questions.forEach(function (question) {
|
|
19
|
+
if (!question || typeof question !== 'object' || Array.isArray(question) || !nonempty(question.id) || ids.has(question.id)) fail('Questions need unique IDs.');
|
|
20
|
+
if (!QUESTION_STATES.has(question.status)) fail('Question ' + question.id + ' has an invalid status.');
|
|
21
|
+
if (!Array.isArray(question.options) || question.options.length < 1) fail('Question ' + question.id + ' needs declared options.');
|
|
22
|
+
ids.add(question.id);
|
|
23
|
+
var options = new Set();
|
|
24
|
+
question.options.forEach(function (option) {
|
|
25
|
+
if (!option || typeof option !== 'object' || Array.isArray(option) || !nonempty(option.value) || options.has(option.value)) fail('Question ' + question.id + ' has invalid options.');
|
|
26
|
+
if (option.requiresNote !== undefined && typeof option.requiresNote !== 'boolean') fail('Question ' + question.id + ' has an invalid requiresNote flag.');
|
|
27
|
+
options.add(option.value);
|
|
28
|
+
});
|
|
29
|
+
});
|
|
30
|
+
return model;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function questionIndex(model) {
|
|
34
|
+
return model.questions.reduce(function (index, question) { index[question.id] = question; return index; }, Object.create(null));
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function validateAnswers(model, answers, mutation) {
|
|
38
|
+
if (!Array.isArray(answers)) fail('Answers must be an array.');
|
|
39
|
+
var questions = questionIndex(model);
|
|
40
|
+
var seen = new Set();
|
|
41
|
+
return answers.map(function (response) {
|
|
42
|
+
if (!response || typeof response !== 'object' || Array.isArray(response) || !nonempty(response.id) || !nonempty(response.answer) || seen.has(response.id)) fail('Answers need unique question IDs and declared choices.');
|
|
43
|
+
if (!own(questions, response.id)) fail('Answer refers to an unknown question.');
|
|
44
|
+
var question = questions[response.id];
|
|
45
|
+
if (mutation && ['backlogged', 'discarded', 'settled'].indexOf(question.status) !== -1) fail('This question is not open for responses.');
|
|
46
|
+
var option = question.options.filter(function (candidate) { return candidate.value === response.answer; })[0];
|
|
47
|
+
if (!option) fail('Answer is not one of the declared options.');
|
|
48
|
+
var note = own(response, 'note') && response.note !== undefined ? response.note : undefined;
|
|
49
|
+
if (note !== undefined && typeof note !== 'string') fail('Answer notes must be strings.');
|
|
50
|
+
if (note !== undefined && note.length > MAX_NOTE_LENGTH) fail('Answer notes cannot exceed 4000 characters.');
|
|
51
|
+
if (option.requiresNote && !nonempty(note)) fail('This answer requires a note.');
|
|
52
|
+
if (mutation && question.status === 'clarified' && (question.answer !== response.answer || (question.note || '') !== (note || ''))) fail('Clarified responses can only be replayed exactly.');
|
|
53
|
+
seen.add(response.id);
|
|
54
|
+
var answer = { id: response.id, answer: response.answer };
|
|
55
|
+
if (note !== undefined && note !== '') answer.note = note;
|
|
56
|
+
return answer;
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function sourceMatches(model, source) {
|
|
61
|
+
return source && source.path === model.source.path && source.revision === model.source.revision && source.viewRevision === model.source.viewRevision;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function envelope(model, answers) {
|
|
65
|
+
return {
|
|
66
|
+
schemaVersion: SCHEMA_VERSION,
|
|
67
|
+
kind: RESPONSE_KIND,
|
|
68
|
+
artifactId: model.artifactId,
|
|
69
|
+
source: Object.assign({ path: model.source.path, revision: model.source.revision }, model.source.viewRevision === undefined ? {} : { viewRevision: model.source.viewRevision }),
|
|
70
|
+
answers: validateAnswers(model, answers)
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function validateEnvelope(model, stored) {
|
|
75
|
+
if (!stored || typeof stored !== 'object' || Array.isArray(stored)) fail('Stored responses are malformed.');
|
|
76
|
+
if (stored.schemaVersion !== SCHEMA_VERSION || stored.kind !== RESPONSE_KIND || stored.artifactId !== model.artifactId) fail('Stored responses belong to a different artifact.');
|
|
77
|
+
if (!sourceMatches(model, stored.source)) fail('Stored responses belong to a different source revision. Reload the matching artifact.');
|
|
78
|
+
return envelope(model, stored.answers);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function mergeAnswers(model, existing, incoming) {
|
|
82
|
+
var values = Object.create(null);
|
|
83
|
+
validateAnswers(model, existing || []).forEach(function (answer) { values[answer.id] = answer; });
|
|
84
|
+
validateAnswers(model, incoming || []).forEach(function (answer) { values[answer.id] = answer; });
|
|
85
|
+
return Object.keys(values).sort().map(function (id) { return values[id]; });
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function result(model, answers, writable, message, storage) {
|
|
89
|
+
return { model: model, responses: validateAnswers(model, answers || []), writable: Boolean(writable), message: message || '', storage: storage || 'memory' };
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function responseRevision(model, revision) {
|
|
93
|
+
if (revision !== model.source.revision) fail('Source changed. Refresh before saving responses.');
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
function requestedAnswers(model, request) {
|
|
97
|
+
if (!request || !Array.isArray(request.answers) || request.answers.length === 0) fail('Choose at least one response before saving.');
|
|
98
|
+
return validateAnswers(model, request.answers, true);
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
function portable(model, options) {
|
|
102
|
+
validateModel(model);
|
|
103
|
+
options = options || {}; // Intentionally memory-only: an export is the persistence boundary.
|
|
104
|
+
var saved = [];
|
|
105
|
+
var notice = 'Prepared for export; not saved to Claude or brief.';
|
|
106
|
+
return {
|
|
107
|
+
load: async function () { return result(model, saved, true, notice, 'memory'); },
|
|
108
|
+
save: async function (request) {
|
|
109
|
+
request = request || {};
|
|
110
|
+
responseRevision(model, request.revision);
|
|
111
|
+
saved = mergeAnswers(model, saved, requestedAnswers(model, request));
|
|
112
|
+
return result(model, saved, true, notice, 'memory');
|
|
113
|
+
},
|
|
114
|
+
exportResponses: function (responses) { return envelope(model, responses === undefined ? saved : responses); }
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
function local(model, options) {
|
|
119
|
+
validateModel(model);
|
|
120
|
+
options = options || {};
|
|
121
|
+
if (!nonempty(options.token)) fail('Local transport needs an artifact token.');
|
|
122
|
+
var request = options.fetch || global.fetch;
|
|
123
|
+
if (typeof request !== 'function') fail('Local transport needs fetch.');
|
|
124
|
+
function headers() { return { 'X-Artifact-Token': options.token, 'Content-Type': 'application/json' }; }
|
|
125
|
+
async function call(path, init) {
|
|
126
|
+
var response = await request(path, init);
|
|
127
|
+
var payload;
|
|
128
|
+
try { payload = await response.json(); } catch (_) { fail('Local response service returned invalid JSON.'); }
|
|
129
|
+
if (!response || !response.ok) {
|
|
130
|
+
var detail = payload && (payload.error || payload.message);
|
|
131
|
+
fail(typeof detail === 'string' && detail ? detail : 'Local response service rejected the request' + (response && response.status ? ' (' + response.status + ')' : '') + '.');
|
|
132
|
+
}
|
|
133
|
+
return payload;
|
|
134
|
+
}
|
|
135
|
+
function decoded(payload) {
|
|
136
|
+
if (!payload || typeof payload !== 'object') fail('Local response service returned no state.');
|
|
137
|
+
var remoteModel = payload.model || model;
|
|
138
|
+
validateModel(remoteModel);
|
|
139
|
+
if (remoteModel.artifactId !== model.artifactId || remoteModel.source.path !== model.source.path) fail('Local response service returned another artifact.');
|
|
140
|
+
model = remoteModel;
|
|
141
|
+
return result(model, payload.responses || [], payload.writable !== false, payload.message, 'brief');
|
|
142
|
+
}
|
|
143
|
+
return {
|
|
144
|
+
load: async function () { return decoded(await call('/state', { method: 'GET', headers: headers() })); },
|
|
145
|
+
save: async function (requestBody) {
|
|
146
|
+
requestBody = requestBody || {};
|
|
147
|
+
responseRevision(model, requestBody.revision);
|
|
148
|
+
var submitted = requestedAnswers(model, requestBody);
|
|
149
|
+
await call('/answers', { method: 'POST', headers: headers(), body: JSON.stringify(Object.assign({ revision: requestBody.revision, answers: submitted }, model.source.viewRevision === undefined ? {} : { viewRevision: model.source.viewRevision })) });
|
|
150
|
+
var verified = decoded(await call('/state', { method: 'GET', headers: headers() }));
|
|
151
|
+
var verifiedById = new Map(verified.responses.map(function (answer) { return [answer.id, answer]; }));
|
|
152
|
+
submitted.forEach(function (answer) {
|
|
153
|
+
var actual = verifiedById.get(answer.id);
|
|
154
|
+
if (!actual || actual.answer !== answer.answer || (actual.note || '') !== (answer.note || '')) fail('Local response service did not durably confirm every saved response.');
|
|
155
|
+
});
|
|
156
|
+
return verified;
|
|
157
|
+
},
|
|
158
|
+
exportResponses: function (responses) { return envelope(model, responses); }
|
|
159
|
+
};
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
function unavailable(error) {
|
|
163
|
+
return /sign.?in|unauth|permission|forbidden|not.?available|unsupported/i.test(String(error && error.message || error));
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
function claude(model, options) {
|
|
167
|
+
validateModel(model);
|
|
168
|
+
options = options || {};
|
|
169
|
+
var host = options.host === undefined ? global.claude : options.host;
|
|
170
|
+
var fallback = portable(model);
|
|
171
|
+
var dbPromise;
|
|
172
|
+
var usingFallback = false;
|
|
173
|
+
var documentPrefix = 'joycraft-artifacts/' + encodeURIComponent(model.artifactId) + '/revisions/' + encodeURIComponent(model.source.revision) + '/views/' + encodeURIComponent(model.source.viewRevision || 'none') + '/decisions/';
|
|
174
|
+
|
|
175
|
+
async function database() {
|
|
176
|
+
if (usingFallback) return null;
|
|
177
|
+
if (!dbPromise) dbPromise = Promise.resolve().then(function () {
|
|
178
|
+
if (!host || typeof host.use !== 'function') return null;
|
|
179
|
+
return host.use('db');
|
|
180
|
+
});
|
|
181
|
+
try {
|
|
182
|
+
var db = await dbPromise;
|
|
183
|
+
if (!db || typeof db.doc !== 'function') { usingFallback = true; return null; }
|
|
184
|
+
return db;
|
|
185
|
+
} catch (_) { usingFallback = true; return null; }
|
|
186
|
+
}
|
|
187
|
+
async function fallbackResult() { usingFallback = true; return fallback.load(); }
|
|
188
|
+
function fromSnapshot(snapshot, id) {
|
|
189
|
+
if (!snapshot) return [];
|
|
190
|
+
if (snapshot.metadata && (snapshot.metadata.hasPendingWrites || snapshot.metadata.fromCache)) fail('Claude storage has not durably confirmed this response yet.');
|
|
191
|
+
if (snapshot.exists === false) return [];
|
|
192
|
+
if (typeof snapshot.data !== 'function') fail('Claude storage returned an unreadable response.');
|
|
193
|
+
var answers = validateEnvelope(model, snapshot.data()).answers;
|
|
194
|
+
if (answers.length !== 1 || answers[0].id !== id) fail('Claude storage returned a response under the wrong decision key.');
|
|
195
|
+
return answers;
|
|
196
|
+
}
|
|
197
|
+
function documentFor(db, id) { return db.doc(documentPrefix + encodeURIComponent(id)); }
|
|
198
|
+
async function readOne(db, id) { return fromSnapshot(await documentFor(db, id).get(), id)[0]; }
|
|
199
|
+
async function readAll(db) {
|
|
200
|
+
var answers = await Promise.all(model.questions.map(async function (question) { return readOne(db, question.id); }));
|
|
201
|
+
return answers.filter(Boolean);
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
return {
|
|
205
|
+
load: async function () {
|
|
206
|
+
var db = await database();
|
|
207
|
+
if (!db) return fallbackResult();
|
|
208
|
+
try { return result(model, await readAll(db), true, 'Responses load from Claude artifact storage. They do not update the brief.', 'claude'); }
|
|
209
|
+
catch (error) { if (unavailable(error)) return fallbackResult(); throw error; }
|
|
210
|
+
},
|
|
211
|
+
save: async function (requestBody) {
|
|
212
|
+
requestBody = requestBody || {};
|
|
213
|
+
responseRevision(model, requestBody.revision);
|
|
214
|
+
var db = await database();
|
|
215
|
+
if (!db) return fallback.save(requestBody);
|
|
216
|
+
var submitted = requestedAnswers(model, requestBody);
|
|
217
|
+
var saved = 0;
|
|
218
|
+
for (var index = 0; index < submitted.length; index += 1) {
|
|
219
|
+
var answer = submitted[index];
|
|
220
|
+
try {
|
|
221
|
+
await documentFor(db, answer.id).set(envelope(model, [answer]));
|
|
222
|
+
var confirmed = await readOne(db, answer.id);
|
|
223
|
+
if (!confirmed || confirmed.answer !== answer.answer || (confirmed.note || '') !== (answer.note || '')) fail('Claude storage did not durably confirm this response.');
|
|
224
|
+
saved += 1;
|
|
225
|
+
} catch (error) {
|
|
226
|
+
fail('Saved ' + saved + ' of ' + submitted.length + '; refresh to see stored answers. ' + (error && error.message ? error.message : 'Claude storage failed.'));
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
return result(model, await readAll(db), true, 'Saved in Claude artifact storage. This does not update the brief.', 'claude');
|
|
230
|
+
},
|
|
231
|
+
exportResponses: function (responses) { return envelope(model, responses); }
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
global.JoycraftArtifactTransports = { local: local, claude: claude, portable: portable };
|
|
236
|
+
})(window);
|
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
/** Contract v1. Paths are project-relative, except QueueSpec.file. */
|
|
2
|
+
export type SpecStatus = 'todo' | 'in-review' | 'done';
|
|
3
|
+
export type DecisionStatus = 'open' | 'clarified' | 'backlogged' | 'discarded' | 'assigned';
|
|
4
|
+
export type Result = 'PASS' | 'FAIL' | 'UNVERIFIED';
|
|
5
|
+
export type EvidenceKind = 'runtime' | 'visual' | 'structural';
|
|
6
|
+
/** Presentation-only artifact theme. */
|
|
7
|
+
export type ArtifactTheme = 'light' | 'dark';
|
|
8
|
+
/** A source-bound, deterministic decision-artifact view. */
|
|
9
|
+
export interface ArtifactView {
|
|
10
|
+
schemaVersion: 1;
|
|
11
|
+
artifactId?: string;
|
|
12
|
+
title: string;
|
|
13
|
+
summary?: string;
|
|
14
|
+
/** Overrides the project artifact theme for this view. */
|
|
15
|
+
theme?: ArtifactTheme;
|
|
16
|
+
decisionIds?: string[];
|
|
17
|
+
comparisons?: Array<{
|
|
18
|
+
title: string;
|
|
19
|
+
decisionId?: string;
|
|
20
|
+
images: Array<{ path: string; label: string; alt: string; caption?: string }>;
|
|
21
|
+
}>;
|
|
22
|
+
reviews?: Array<{ path: string; title?: string }>;
|
|
23
|
+
}
|
|
24
|
+
/** Current source identity for an artifact model or exported response envelope. */
|
|
25
|
+
export interface ArtifactSource {
|
|
26
|
+
path: string;
|
|
27
|
+
/** SHA-256 of the exact current brief bytes. */
|
|
28
|
+
revision: string;
|
|
29
|
+
/** SHA-256 covering view data plus every selected image and review-report byte. */
|
|
30
|
+
viewRevision: string;
|
|
31
|
+
}
|
|
32
|
+
export interface ArtifactAnswer { id: string; answer: string; note?: string }
|
|
33
|
+
/** Detached answers are drafts until a current source-bound import is applied. */
|
|
34
|
+
export interface ArtifactResponseEnvelope {
|
|
35
|
+
schemaVersion: 1;
|
|
36
|
+
kind: 'joycraft-artifact-responses';
|
|
37
|
+
artifactId: string;
|
|
38
|
+
source: ArtifactSource;
|
|
39
|
+
answers: ArtifactAnswer[];
|
|
40
|
+
}
|
|
41
|
+
export interface Criterion {
|
|
42
|
+
id: string;
|
|
43
|
+
requirement: { path: string; anchor: string };
|
|
44
|
+
requiredKinds: EvidenceKind[];
|
|
45
|
+
}
|
|
46
|
+
export interface VerificationInput {
|
|
47
|
+
path: string;
|
|
48
|
+
kind: 'code' | 'requirement' | 'check' | 'fixture';
|
|
49
|
+
/** Deliberate removal of a non-requirement input; reappearance invalidates review. */
|
|
50
|
+
state?: 'absent';
|
|
51
|
+
/** Optional exact requirement scope; omitted means the whole file remains governing. */
|
|
52
|
+
scope?: { anchors?: string[]; decisionIds?: string[] };
|
|
53
|
+
}
|
|
54
|
+
export interface QueueSpec {
|
|
55
|
+
id: number;
|
|
56
|
+
file: string;
|
|
57
|
+
depends_on: number[];
|
|
58
|
+
status: SpecStatus;
|
|
59
|
+
mode: 'batch' | 'checkpoint' | 'isolated';
|
|
60
|
+
/** Concurrent mutable work requires a linked worker worktree; absent means legacy serial. */
|
|
61
|
+
execution?: { parallel: boolean };
|
|
62
|
+
verification: {
|
|
63
|
+
inputs: VerificationInput[];
|
|
64
|
+
criteria: Criterion[];
|
|
65
|
+
/** Captured before implementation; never infer it from a moving upstream branch. */
|
|
66
|
+
changeScope?: { baseRevision: string; exclusions?: Array<{ path: string; reason: string }> };
|
|
67
|
+
};
|
|
68
|
+
acceptedReport?: { path: string; sha256: string };
|
|
69
|
+
/** Explicit owner exception, mutually exclusive with acceptedReport; not a PASS. */
|
|
70
|
+
ownerAcceptance?: Receipt;
|
|
71
|
+
}
|
|
72
|
+
export interface SpecQueue { schemaVersion: 1; feature: string; specs: QueueSpec[] }
|
|
73
|
+
export interface BoundInput extends VerificationInput {
|
|
74
|
+
sha256: string;
|
|
75
|
+
normalization: 'none' | 'spec-status' | 'queue-status' | 'queue-scope' | 'requirement-scope' | 'absent';
|
|
76
|
+
}
|
|
77
|
+
export interface VerificationSubject {
|
|
78
|
+
schemaVersion: 1;
|
|
79
|
+
/** SHA-256 of canonical fields except identity; retain original revision on re-check. */
|
|
80
|
+
identity: string;
|
|
81
|
+
implementationRevision: string;
|
|
82
|
+
queuePath: string;
|
|
83
|
+
specId: number;
|
|
84
|
+
specPath: string;
|
|
85
|
+
criteria: Criterion[];
|
|
86
|
+
inputs: BoundInput[];
|
|
87
|
+
/** Absent on legacy reports, which retain whole-file/whole-queue semantics. */
|
|
88
|
+
binding?: {
|
|
89
|
+
version: 1;
|
|
90
|
+
queue: { specIds: number[] };
|
|
91
|
+
governing: Array<{ path: string; anchors?: string[]; decisionIds?: string[] }>;
|
|
92
|
+
/** Changed-file coverage complements, but does not discover, semantic dependencies. */
|
|
93
|
+
changeScope?: {
|
|
94
|
+
baseRevision: string;
|
|
95
|
+
paths: Array<{ path: string; beforePath?: string; status: string; stages?: string[]; state: 'present' | 'deleted' }>;
|
|
96
|
+
};
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
export interface Receipt { path: string; sha256: string }
|
|
100
|
+
export interface Observation {
|
|
101
|
+
kind: EvidenceKind;
|
|
102
|
+
method: 'test' | 'command' | 'browser' | 'manual' | 'source';
|
|
103
|
+
result: Result;
|
|
104
|
+
actual: string;
|
|
105
|
+
receipts: Receipt[];
|
|
106
|
+
/** Mandatory for test/command observations; null means unavailable. */
|
|
107
|
+
command?: { argv: string[]; exitCode: number | null };
|
|
108
|
+
/** Mandatory for visual observations. Interactions name actual outcomes. */
|
|
109
|
+
visual?: {
|
|
110
|
+
route: string;
|
|
111
|
+
state: string;
|
|
112
|
+
viewport: { width: number; height: number };
|
|
113
|
+
inspected: boolean;
|
|
114
|
+
interactions: string[];
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
export interface FlowEvidence {
|
|
118
|
+
id: string;
|
|
119
|
+
subjectIdentity: string;
|
|
120
|
+
criteria: string[];
|
|
121
|
+
representativeInput: string;
|
|
122
|
+
expected: string;
|
|
123
|
+
observations: Observation[];
|
|
124
|
+
limits: string[];
|
|
125
|
+
}
|
|
126
|
+
/** Observed native host identity. A child may share its parent's sessionId. */
|
|
127
|
+
export interface NativeActor {
|
|
128
|
+
host: string;
|
|
129
|
+
sessionId: string;
|
|
130
|
+
/** Actual host-issued agent/invocation ID; omit for a native root session. */
|
|
131
|
+
agentId?: string;
|
|
132
|
+
}
|
|
133
|
+
export interface VerificationReport {
|
|
134
|
+
schemaVersion: 1;
|
|
135
|
+
subject: VerificationSubject;
|
|
136
|
+
implementerSessionId: string;
|
|
137
|
+
/** Both actors must be supplied together; legacy reports keep distinct session IDs. */
|
|
138
|
+
implementerActor?: NativeActor;
|
|
139
|
+
reviewer: { sessionId: string; actor?: NativeActor; independent: boolean; scopeReviewed: boolean };
|
|
140
|
+
verdict: Result;
|
|
141
|
+
flows: FlowEvidence[];
|
|
142
|
+
unresolved: string[];
|
|
143
|
+
createdAt: string;
|
|
144
|
+
}
|
|
145
|
+
/** Scoped human instruction recorded by the host; bindings do not authenticate its origin. */
|
|
146
|
+
export interface OwnerAcceptance {
|
|
147
|
+
schemaVersion: 1;
|
|
148
|
+
kind: 'owner-acceptance';
|
|
149
|
+
queuePath: string;
|
|
150
|
+
specId: number;
|
|
151
|
+
subjectIdentity: string;
|
|
152
|
+
/** Current independent FAIL/UNVERIFIED report, retained without changing its verdict. */
|
|
153
|
+
review: Receipt;
|
|
154
|
+
/** Exact human instruction in its conversational scope, never inferred from general permission. */
|
|
155
|
+
instruction: string;
|
|
156
|
+
limitations: string[];
|
|
157
|
+
createdAt: string;
|
|
158
|
+
}
|
|
159
|
+
export interface ValidationResult { ok: boolean; errors: string[] }
|
|
160
|
+
export type Need = 'repair' | 'feature' | 'context' | 'decision' | 'ui-exploration' | 'implementation' | 'verification' | 'unknown';
|
|
161
|
+
export type NextInteraction = 'continue' | 'inspect' | 'render-slice' | 'ask-focused' | 'verify' | 'abstain';
|
|
162
|
+
export interface RoutingRequest {
|
|
163
|
+
schemaVersion: 1;
|
|
164
|
+
requestId: string;
|
|
165
|
+
text: string;
|
|
166
|
+
context: string;
|
|
167
|
+
openDecisionIds: string[];
|
|
168
|
+
}
|
|
169
|
+
export interface RoutingAdvice {
|
|
170
|
+
schemaVersion: 1;
|
|
171
|
+
requestId: string;
|
|
172
|
+
needs: Need[];
|
|
173
|
+
next: NextInteraction;
|
|
174
|
+
reason: string;
|
|
175
|
+
provenance: 'rules' | 'agent' | 'jev' | 'fallback';
|
|
176
|
+
confidence: number | null;
|
|
177
|
+
abstained: boolean;
|
|
178
|
+
fallbackReason: string | null;
|
|
179
|
+
}
|
|
180
|
+
export interface RoutingOptions {
|
|
181
|
+
mode: 'rules-only' | 'advisory' | 'live-advisory';
|
|
182
|
+
/** W08 owns the injected provider transport; secrets remain outside records. */
|
|
183
|
+
provider?: (request: RoutingRequest) => Promise<unknown>;
|
|
184
|
+
timeoutMs?: number;
|
|
185
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Focused architecture discovery
|
|
2
|
+
|
|
3
|
+
Use this when the requested behavior crosses an unclear responsibility, state or
|
|
4
|
+
data boundary. Examples include save/retry/refresh interactions, several writers
|
|
5
|
+
of one record, or a representation produced and consumed in different languages.
|
|
6
|
+
If the relevant flow is already understood, reuse it. A copy/style repair does
|
|
7
|
+
not need a broad architecture review. A read-only explanation stays read-only.
|
|
8
|
+
|
|
9
|
+
## Trace only the affected flow
|
|
10
|
+
|
|
11
|
+
Start with existing context pointers and the actual entry point. Follow callers,
|
|
12
|
+
state owners, services, persisted representations and affected consumers far
|
|
13
|
+
enough to explain the requested behavior. Search for counterpart definitions,
|
|
14
|
+
literals and shapes even when retrieval did not rank them. A TypeScript producer
|
|
15
|
+
and SQL validator, for example, may have different names for the same contract.
|
|
16
|
+
Find the currently defining source rather than assuming an old migration is
|
|
17
|
+
still authoritative; source inspection does not prove deployed database state.
|
|
18
|
+
|
|
19
|
+
For asynchronous editing, distinguish local working edits, the loaded or
|
|
20
|
+
acknowledged baseline, and the latest saved state. Inspect what is sent, retried,
|
|
21
|
+
replaced and adopted when a reply arrives. Do not conflate a successful save with
|
|
22
|
+
permission to replace later typing or another writer's untouched fields. The
|
|
23
|
+
owning product decision determines conflict behavior; it is not a universal merge
|
|
24
|
+
algorithm. Read existing decisions before asking for a missing choice.
|
|
25
|
+
|
|
26
|
+
Keep three things distinct: observed code behavior, intended behavior in the
|
|
27
|
+
owning brief, and proposed changes. Report a consequential mismatch; do not
|
|
28
|
+
silently turn a proposed refactor into current architecture. Resolve engineering
|
|
29
|
+
facts yourself. Ask the human only for missing behavior or a material tradeoff,
|
|
30
|
+
using one short example or an inspected UI view when it helps. Technical detail
|
|
31
|
+
is optional. Do not require the user to select libraries or design a schema to
|
|
32
|
+
enter the ordinary workflow.
|
|
33
|
+
|
|
34
|
+
## Keep useful navigation in its existing home
|
|
35
|
+
|
|
36
|
+
Reuse a focused project reference or an existing architecture document. Add a
|
|
37
|
+
small context-map pointer only when there is reusable content; otherwise keep
|
|
38
|
+
task-local findings in the brief/spec. Do not create empty architecture files,
|
|
39
|
+
a second decision store, or an architecture-complete flag.
|
|
40
|
+
|
|
41
|
+
A compact reference can use these columns, populated with actual project paths:
|
|
42
|
+
|
|
43
|
+
| Concern | Owning sources and decision | Observable obligation/check and limits | Read/update when |
|
|
44
|
+
|---|---|---|---|
|
|
45
|
+
| Display/storage agreement | Producer, current storage validator/applier, renderer; owning behavior decision | Display rename preserves stored values; both representations match independently expected output | Changing literals, shapes or display mapping |
|
|
46
|
+
| Edit/save ownership | Controls, state owner, save/retry path; owning conflict decision | Delayed acknowledgement preserves later typing; concurrent edits follow the chosen policy | Changing state adoption, payloads, retries or remounts |
|
|
47
|
+
|
|
48
|
+
These are examples, not required rows or prescribed filenames. Record the
|
|
49
|
+
inspected revision/date or other available source identity and unresolved
|
|
50
|
+
coverage. Link the actual check/receipt and what it established. A helper test
|
|
51
|
+
or source scan must not appear to prove an unobserved rendered or deployed flow.
|
|
52
|
+
The implementing worker proposes affected updates with the task; the independent
|
|
53
|
+
reviewer checks them. Promote resulting behavior into reusable accepted context
|
|
54
|
+
only after guarded completion, reconciling it at session end. Existing task
|
|
55
|
+
coordination handles the combined change; add no new serial architecture role
|
|
56
|
+
or checkpoint when current ownership is sufficient.
|
|
57
|
+
|
|
58
|
+
## Deliver sources and discriminating checks
|
|
59
|
+
|
|
60
|
+
Before splitting affected work, identify the coupled owners and a scenario that
|
|
61
|
+
would distinguish the requested behavior from the prior behavior. Depending on
|
|
62
|
+
the change, exercise absent and existing parents, create/clear/reload, delayed
|
|
63
|
+
replies with later typing, two writers in both save orders, or a stored value
|
|
64
|
+
with a different display label. Select relevant cases, not this entire list.
|
|
65
|
+
Inspect combined behavior rather than relying on matching helper outputs or a
|
|
66
|
+
green test count. Use a small working slice to resolve consequential uncertainty
|
|
67
|
+
when useful; it is not a prerequisite for every queue.
|
|
68
|
+
|
|
69
|
+
Name the real sources, owning choices, fixtures and checks in each affected
|
|
70
|
+
spec and its exact verification inputs. Include the relevant context reference
|
|
71
|
+
as a task input when needed, not merely a link the worker may never follow.
|
|
72
|
+
Dispatch delivers declared sources; hashes cannot discover omitted dependencies.
|
|
73
|
+
If work reveals another coupled source, update affected inputs and prepare the
|
|
74
|
+
review from current sources through the existing helpers. Do not reuse a stale
|
|
75
|
+
subject or provide the reviewer with an intended verdict or implementer reasoning.
|
|
76
|
+
|
|
77
|
+
## Maintain scope and cost
|
|
78
|
+
|
|
79
|
+
Update only affected accepted facts in their owning reference, reconciling them
|
|
80
|
+
at session end before any eligible archival. Active choices remain in their
|
|
81
|
+
brief; rationale links to that choice; proposals stay marked as proposals.
|
|
82
|
+
References describe and navigate the project. They neither grant permission nor
|
|
83
|
+
become global Jev constraints. Do not add them to global hook rule paths or make
|
|
84
|
+
extra live classification calls merely to maintain a map. Retrieval scores and
|
|
85
|
+
this procedure do not certify exhaustive discovery.
|
|
86
|
+
|
|
87
|
+
Keep task context bounded to relevant sources. When evaluating the change,
|
|
88
|
+
record newly delivered input bytes, repeated reads/provider calls, human
|
|
89
|
+
questions, repair rounds and reference maintenance alongside observed defects.
|
|
90
|
+
A cleaner map alone is not evidence of better software or lower cost.
|