@makerkit/prd 0.0.3 → 0.0.5

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 (63) hide show
  1. package/.turbo/turbo-build.log +78 -0
  2. package/.turbo/turbo-test.log +19 -0
  3. package/.turbo/turbo-typecheck.log +6 -0
  4. package/README.md +7 -1
  5. package/dist/README.md +71 -0
  6. package/dist/attachment-paths-BAhRGiib.js +112 -0
  7. package/dist/attachment-paths-C-SWgoSx.mjs +77 -0
  8. package/dist/index.d.ts +81 -0
  9. package/{index.js → dist/index.js} +257 -524
  10. package/{index.mjs → dist/index.mjs} +189 -462
  11. package/{mcp.d.ts → dist/mcp.d.ts} +2 -4
  12. package/{mcp.js → dist/mcp.js} +24 -24
  13. package/{mcp.mjs → dist/mcp.mjs} +24 -24
  14. package/{node.d.ts → dist/node.d.ts} +4 -4
  15. package/{node.js → dist/node.js} +28 -4
  16. package/{node.mjs → dist/node.mjs} +30 -6
  17. package/dist/operations.d.ts +141 -0
  18. package/dist/operations.js +22 -0
  19. package/dist/operations.mjs +1 -0
  20. package/dist/package.json +54 -0
  21. package/dist/prd-operations-BvFxo9bg.mjs +459 -0
  22. package/dist/prd-operations-CcahfbOy.js +584 -0
  23. package/dist/prd.service-CTwKZV-3.d.ts +114 -0
  24. package/{prompts-DJQ4FQ11.js → dist/prompts-1qhax_dj.js} +150 -167
  25. package/{prompts-B0VejF7q.mjs → dist/prompts-BlsYD0gf.mjs} +121 -132
  26. package/{prd.service-x5EpOoMv.d.ts → dist/schema-BwTnt0B9.d.ts} +545 -323
  27. package/package.json +26 -2
  28. package/src/__tests__/agent-workflow.test.ts +417 -0
  29. package/src/__tests__/attachments.test.ts +505 -0
  30. package/src/__tests__/node.test.ts +199 -0
  31. package/src/__tests__/plan-check.test.ts +390 -0
  32. package/src/__tests__/planning.test.ts +1137 -0
  33. package/src/__tests__/prd-operations.test.ts +571 -0
  34. package/src/__tests__/prd.service.test.ts +652 -0
  35. package/src/__tests__/prd.tool.test.ts +282 -0
  36. package/src/__tests__/templates.test.ts +145 -0
  37. package/src/applicability.ts +73 -0
  38. package/src/attachment-paths.ts +83 -0
  39. package/src/attachments.ts +166 -0
  40. package/src/edge-cases.ts +61 -0
  41. package/src/index.ts +33 -0
  42. package/src/markdown.ts +297 -0
  43. package/src/mcp/index.ts +875 -0
  44. package/src/mcp/tool-response.ts +85 -0
  45. package/src/node.ts +184 -0
  46. package/src/open-questions.ts +98 -0
  47. package/src/plan-check.ts +385 -0
  48. package/src/planning-operations.ts +524 -0
  49. package/src/prd-operations.ts +769 -0
  50. package/src/prd.service.ts +1165 -0
  51. package/src/prompts.ts +161 -0
  52. package/src/safe-file-name.ts +42 -0
  53. package/src/schema.ts +1090 -0
  54. package/src/templates.ts +173 -0
  55. package/src/testing/fake-mcp-server.ts +81 -0
  56. package/src/types.ts +381 -0
  57. package/tsconfig.json +23 -0
  58. package/tsconfig.lib.json +8 -0
  59. package/tsconfig.spec.json +7 -0
  60. package/tsdown.config.mts +12 -0
  61. package/vitest.config.mts +8 -0
  62. package/index.d.ts +0 -228
  63. /package/{LICENSE → dist/LICENSE} +0 -0
@@ -1,83 +1,6 @@
1
+ const require_attachment_paths = require("./attachment-paths-BAhRGiib.js");
1
2
  let zod_v3 = require("zod/v3");
2
- //#region src/safe-file-name.ts
3
- /**
4
- * Accept only a bare file name. Anything that could escape the intended
5
- * directory (path separators, parent references, hidden files) is rejected
6
- * before the filesystem is touched.
7
- */
8
- function assertSafeFileName(value, label = "file name") {
9
- const name = value.trim();
10
- if (name.length === 0 || name.includes("..") || name.includes("/") || name.includes("\\") || name.startsWith(".")) throw new Error(`Invalid ${label} "${value}"`);
11
- return name;
12
- }
13
- /**
14
- * Accept only a relative path that stays inside the directory it is joined
15
- * to: no absolute paths, no `..`, no backslashes, no empty or hidden segments.
16
- * This is a check on the text only; code that serves the file must still
17
- * resolve symlinks before reading it.
18
- */
19
- function assertSafeRelativePath(value, label = "path") {
20
- const path = value.trim();
21
- const segments = path.split("/");
22
- if (path.length === 0 || path.includes("\\") || /^[a-zA-Z]:/.test(path) || segments.some((segment) => segment.length === 0 || segment.startsWith("."))) throw new Error(`Invalid ${label} "${value}"`);
23
- return path;
24
- }
25
- //#endregion
26
- //#region src/attachment-paths.ts
27
- /**
28
- * The folder for a PRD's files, relative to `.prds`: the PRD file name
29
- * without `.json`, so `notes.json` keeps its files in `.prds/notes/`.
30
- */
31
- function attachmentsFolder(filename) {
32
- return filename.replace(/\.json$/, "");
33
- }
34
- /** An attachment's file relative to the project root, e.g. `.prds/notes/a.png`. */
35
- function attachmentProjectPath(filename, path) {
36
- return `.prds/${attachmentsFolder(filename)}/${path}`;
37
- }
38
- /** Attachments as an agent needs them: file paths from the project root. */
39
- function resolveAttachments(filename, attachments) {
40
- return attachments.map(({ path, ...attachment }) => ({
41
- ...attachment,
42
- ...path ? { path: attachmentProjectPath(filename, path) } : {}
43
- }));
44
- }
45
- /**
46
- * Attachments as stored, with hand-edited entries that would break readers
47
- * or point outside the PRD folder dropped: each needs a string id and title
48
- * and either a safe relative path or an http(s) url.
49
- */
50
- function normalizeAttachments(value) {
51
- if (!Array.isArray(value)) return [];
52
- return value.flatMap((entry) => {
53
- if (typeof entry !== "object" || entry === null) return [];
54
- const { id, title, path, url, note } = entry;
55
- if (typeof id !== "string" || typeof title !== "string") return [];
56
- const base = {
57
- id,
58
- title,
59
- ...typeof note === "string" && note ? { note } : {}
60
- };
61
- if (typeof path === "string" && url === void 0 && isSafePath(path)) return [{
62
- ...base,
63
- path
64
- }];
65
- if (typeof url === "string" && path === void 0 && /^https?:\/\//i.test(url)) return [{
66
- ...base,
67
- url
68
- }];
69
- return [];
70
- });
71
- }
72
- function isSafePath(path) {
73
- try {
74
- return assertSafeRelativePath(path) === path;
75
- } catch {
76
- return false;
77
- }
78
- }
79
- //#endregion
80
- //#region src/templates.ts
3
+ // src/templates.ts
81
4
  const TEMPLATE_IDS = [
82
5
  "saas-feature",
83
6
  "internal-tool",
@@ -174,9 +97,8 @@ function getTemplate(id) {
174
97
  if (!template) throw new Error(`Unknown template "${id}". Templates: ${TEMPLATE_IDS.join(", ")}.`);
175
98
  return template;
176
99
  }
177
- //#endregion
178
- //#region src/schema.ts
179
- const FilenameSchema = zod_v3.z.string().min(1).describe("PRD file name inside .prds, e.g. notes-feature.json");
100
+ // src/schema.ts
101
+ const FilenameSchema = zod_v3.z.string().min(1).describe("PRD file name in the PRD directory, e.g. notes-feature.json");
180
102
  const StoryStatusSchema = zod_v3.z.enum([
181
103
  "not_started",
182
104
  "research",
@@ -198,6 +120,43 @@ const StoryComplexitySchema = zod_v3.z.enum([
198
120
  "L",
199
121
  "XL"
200
122
  ]);
123
+ const ProofKindSchema = zod_v3.z.enum([
124
+ "unit",
125
+ "integration",
126
+ "e2e",
127
+ "judge",
128
+ "manual",
129
+ "post-deploy"
130
+ ]);
131
+ const CriterionProofSchema = zod_v3.z.object({
132
+ criterion: zod_v3.z.string().min(1).describe("The acceptance criterion this proves, exactly as written"),
133
+ kind: ProofKindSchema.describe("unit/integration/e2e: a test at the lowest seam that can assert it. judge: the reviewing agent scores it against a rubric, for judgment that can be written down (tone, clarity, layout). manual/post-deploy only when the truth lives outside the test environment (a real third party, production-only conditions, human judgment) — never because a test is hard"),
134
+ seam: zod_v3.z.string().min(1).optional().describe("The entry point or test file the test exercises"),
135
+ reason: zod_v3.z.string().min(1).optional().describe("Required for manual and post-deploy: why no test can prove it. For e2e: why a lower seam will not do"),
136
+ fallback: zod_v3.z.string().min(1).optional().describe("For manual and post-deploy: the strongest automated check still made"),
137
+ rubric: zod_v3.z.array(zod_v3.z.string().min(1)).optional().describe("Required for judge: the points the reviewer scores against, each one checkable, e.g. \"Says what failed and what to do next\"")
138
+ });
139
+ const RoadmapLabelSchema = zod_v3.z.string().trim().min(1).max(120);
140
+ const PrdCriticalitySchema = zod_v3.z.enum([
141
+ "critical",
142
+ "high",
143
+ "medium",
144
+ "low"
145
+ ]);
146
+ const PrdRoadmapSchema = zod_v3.z.object({
147
+ order: zod_v3.z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional(),
148
+ criticality: PrdCriticalitySchema.optional(),
149
+ plan: RoadmapLabelSchema.optional(),
150
+ group: RoadmapLabelSchema.optional(),
151
+ section: RoadmapLabelSchema.optional()
152
+ });
153
+ const PrdRoadmapUpdateSchema = zod_v3.z.object({
154
+ order: PrdRoadmapSchema.shape.order.nullable(),
155
+ criticality: PrdRoadmapSchema.shape.criticality.nullable(),
156
+ plan: PrdRoadmapSchema.shape.plan.nullable(),
157
+ group: PrdRoadmapSchema.shape.group.nullable(),
158
+ section: PrdRoadmapSchema.shape.section.nullable()
159
+ }).strict();
201
160
  const PrdSummarySchema = zod_v3.z.object({
202
161
  filename: zod_v3.z.string(),
203
162
  title: zod_v3.z.string(),
@@ -205,7 +164,8 @@ const PrdSummarySchema = zod_v3.z.object({
205
164
  progress: zod_v3.z.number().int().min(0).max(100),
206
165
  total_stories: zod_v3.z.number().int().min(0),
207
166
  completed_stories: zod_v3.z.number().int().min(0),
208
- blocked_stories: zod_v3.z.number().int().min(0)
167
+ blocked_stories: zod_v3.z.number().int().min(0),
168
+ roadmap: PrdRoadmapSchema.optional()
209
169
  });
210
170
  const ListPrdsInputSchema = zod_v3.z.object({});
211
171
  const ListPrdsOutputSchema = zod_v3.z.object({
@@ -235,6 +195,7 @@ const CreatePrdInputSchema = zod_v3.z.object({
235
195
  outOfScope: zod_v3.z.array(zod_v3.z.string()).optional(),
236
196
  assumptions: zod_v3.z.array(zod_v3.z.string()).optional(),
237
197
  openQuestions: zod_v3.z.array(zod_v3.z.string()).optional(),
198
+ roadmap: PrdRoadmapSchema.strict().optional(),
238
199
  template: zod_v3.z.enum(TEMPLATE_IDS).optional().describe("Start from a template (see list_templates). Values given here win.")
239
200
  });
240
201
  const CreatePrdOutputSchema = zod_v3.z.object({
@@ -262,6 +223,7 @@ const AddUserStoryInputSchema = zod_v3.z.object({
262
223
  */
263
224
  estimatedComplexity: StoryComplexitySchema.optional(),
264
225
  testSeams: zod_v3.z.array(zod_v3.z.string().min(1)).optional().describe("Public entry points the tests exercise, e.g. a route or server action"),
226
+ proofs: zod_v3.z.array(CriterionProofSchema).optional().describe("How each acceptance criterion is proven, one per criterion. Replaces the list"),
265
227
  dependencies: zod_v3.z.array(zod_v3.z.string().min(1)).optional().describe("Ids of stories that must be completed first, e.g. [\"US001\"]"),
266
228
  phaseId: zod_v3.z.string().min(1).optional().describe("Phase to put the story in, e.g. \"PHASE002\""),
267
229
  attachmentIds: zod_v3.z.array(zod_v3.z.string().min(1)).optional().describe("Ids of PRD attachments this story uses, e.g. [\"ATT001\"]"),
@@ -284,7 +246,9 @@ const UpdateStoryStatusInputSchema = zod_v3.z.object({
284
246
  filename: FilenameSchema,
285
247
  storyId: zod_v3.z.string().min(1),
286
248
  status: StoryStatusSchema,
249
+ workerId: zod_v3.z.string().trim().min(1).optional().describe("Stable run ID used to claim an active story and to update a story already claimed by this worker."),
287
250
  notes: zod_v3.z.string().optional(),
251
+ recordDeviations: zod_v3.z.array(zod_v3.z.string().min(1)).optional().describe("Only when completing: deviations from the story log, copied exactly, to record as accepted decisions so the PRD says what was built"),
288
252
  expectedRevision: zod_v3.z.number().int().min(0).optional().describe("The PRD revision (metadata.revision) the change is based on, checked before the project checks run. When the PRD changed since, the change is rejected: read it again and retry.")
289
253
  });
290
254
  const StoryVerificationSchema = zod_v3.z.object({
@@ -298,7 +262,9 @@ const UpdateStoryStatusOutputSchema = zod_v3.z.object({
298
262
  status: StoryStatusSchema,
299
263
  progress: zod_v3.z.number().int().min(0).max(100),
300
264
  /** Present only when the story was marked completed and checks ran. */
301
- verification: StoryVerificationSchema.nullable()
265
+ verification: StoryVerificationSchema.nullable(),
266
+ /** Ids of the decisions recorded from the story's deviations. */
267
+ recorded_decisions: zod_v3.z.array(zod_v3.z.string())
302
268
  });
303
269
  const UpdateUserStoryInputSchema = zod_v3.z.object({
304
270
  filename: FilenameSchema,
@@ -315,6 +281,7 @@ const UpdateUserStoryInputSchema = zod_v3.z.object({
315
281
  dependencies: zod_v3.z.array(zod_v3.z.string()).optional(),
316
282
  notes: zod_v3.z.string().optional(),
317
283
  testSeams: zod_v3.z.array(zod_v3.z.string().min(1)).optional().describe("Public entry points the tests exercise, e.g. a route or server action"),
284
+ proofs: zod_v3.z.array(CriterionProofSchema).optional().describe("How each acceptance criterion is proven, one per criterion. Replaces the list"),
318
285
  attachmentIds: zod_v3.z.array(zod_v3.z.string().min(1)).optional().describe("Ids of PRD attachments this story uses, e.g. [\"ATT001\"]"),
319
286
  designNotes: zod_v3.z.array(zod_v3.z.string().min(1)).optional().describe("Design notes for this story only (layout, empty/loading/error states, copy) beyond the PRD design guidance"),
320
287
  securityNotes: zod_v3.z.array(zod_v3.z.string().min(1)).optional().describe("Security notes for this story only: each specific way it could be abused and the defence, beyond the PRD security considerations"),
@@ -476,13 +443,15 @@ const GetStoryOutputSchema = zod_v3.z.object({
476
443
  security: zod_v3.z.object({
477
444
  permissions: zod_v3.z.array(zod_v3.z.string()),
478
445
  compliance: zod_v3.z.array(zod_v3.z.string()),
479
- considerations: zod_v3.z.array(zod_v3.z.string())
446
+ considerations: zod_v3.z.array(zod_v3.z.string()),
447
+ story_notes: zod_v3.z.array(zod_v3.z.string())
480
448
  }),
481
449
  /** Parts of the PRD that do not apply, with the reason: do not invent them. */
482
450
  not_applicable: zod_v3.z.record(zod_v3.z.string(), zod_v3.z.string()),
483
451
  /** Standing design rules and accepted design decisions. */
484
452
  design: zod_v3.z.object({
485
453
  guidance: zod_v3.z.array(zod_v3.z.string()),
454
+ story_notes: zod_v3.z.array(zod_v3.z.string()),
486
455
  decisions: zod_v3.z.array(zod_v3.z.object({
487
456
  id: zod_v3.z.string(),
488
457
  decision: zod_v3.z.string(),
@@ -504,6 +473,7 @@ const GetStoryOutputSchema = zod_v3.z.object({
504
473
  const AddStoryLogInputSchema = zod_v3.z.object({
505
474
  filename: FilenameSchema,
506
475
  storyId: zod_v3.z.string().min(1),
476
+ workerId: zod_v3.z.string().trim().min(1).optional(),
507
477
  whatsNew: zod_v3.z.array(zod_v3.z.string().min(1)).min(1).describe("What a person can now try, in plain language"),
508
478
  technicalNotes: zod_v3.z.array(zod_v3.z.string().min(1)).default([]).describe("Decisions, gotchas and file locations for the next agent"),
509
479
  deviations: zod_v3.z.array(zod_v3.z.string().min(1)).optional().describe("Where the work departed from the PRD and why: changed criteria, extra or skipped scope, a different approach")
@@ -518,6 +488,7 @@ const StringList = zod_v3.z.array(zod_v3.z.string().min(1));
518
488
  * merged (only the keys supplied change); list sections are replaced.
519
489
  */
520
490
  const PrdSectionValueSchemas = {
491
+ roadmap: PrdRoadmapUpdateSchema,
521
492
  introduction: zod_v3.z.object({
522
493
  title: zod_v3.z.string().min(1),
523
494
  overview: zod_v3.z.string()
@@ -613,7 +584,7 @@ const UpdatePrdSectionInputSchema = zod_v3.z.object({
613
584
  filename: FilenameSchema,
614
585
  section: zod_v3.z.enum(PRD_SECTIONS),
615
586
  expectedRevision: zod_v3.z.number().int().min(0).optional().describe("The PRD revision (metadata.revision) this change is based on. When given and the PRD changed since, the update is rejected: read it again and retry."),
616
- value: zod_v3.z.unknown().describe("Object sections (introduction, problemStatement, solutionOverview, technicalRequirements, technicalContracts, acceptanceCriteria, constraints, rolloutPlan, measurementPlan) take an object and only the keys given change. List sections (nonGoals, outOfScope, assumptions, designGuidance, securityConsiderations) take a string array and replace the list. openQuestions takes an array of { question, why, options, recommended, storyIds } (a plain string is accepted too) and replaces the list; keep the ids of existing questions. risks, dependencies and edgeCases take an array of items and replace the list; items without an id get one. An edge case is { case, expectedBehavior, status: \"open\" | \"decided\", storyIds? }; a decided one needs expectedBehavior, and storyIds must name existing stories.")
587
+ value: zod_v3.z.unknown().describe("roadmap takes a partial object with order, criticality, plan, group and section. Pass null to clear a field. Object sections (introduction, problemStatement, solutionOverview, technicalRequirements, technicalContracts, acceptanceCriteria, constraints, rolloutPlan, measurementPlan) take an object and only the keys given change. List sections (nonGoals, outOfScope, assumptions, designGuidance, securityConsiderations) take a string array and replace the list. openQuestions takes an array of { question, why, options, recommended, storyIds } (a plain string is accepted too) and replaces the list; keep the ids of existing questions. risks, dependencies and edgeCases take an array of items and replace the list; items without an id get one. An edge case is { case, expectedBehavior, status: \"open\" | \"decided\", storyIds? }; a decided one needs expectedBehavior, and storyIds must name existing stories.")
617
588
  });
618
589
  const UpdatePrdSectionOutputSchema = zod_v3.z.object({
619
590
  section: zod_v3.z.string(),
@@ -661,7 +632,7 @@ const ExpectedRevisionSchema = zod_v3.z.number().int().min(0).optional().describ
661
632
  const AddAttachmentInputSchema = zod_v3.z.object({
662
633
  filename: FilenameSchema,
663
634
  title: zod_v3.z.string().min(1).describe("What it is, e.g. \"Approve view mockup\""),
664
- path: zod_v3.z.string().min(1).optional().describe("File inside the PRD folder (.prds/<prd name>/), relative to it, e.g. \"mockups/approve.png\". Save the file there first. Give path or url, not both."),
635
+ path: zod_v3.z.string().min(1).optional().describe("File inside the PRD folder (next to its JSON file), relative to it, e.g. \"mockups/approve.png\". Save the file there first. Give path or url, not both."),
665
636
  url: zod_v3.z.string().url().optional().describe("A web page or document link. Give path or url, not both."),
666
637
  note: zod_v3.z.string().min(1).optional().describe("What to take from it, e.g. \"Layout only; colours are placeholders\""),
667
638
  storyIds: zod_v3.z.array(zod_v3.z.string().min(1)).optional().describe("Stories that use it, e.g. [\"US003\"]"),
@@ -770,40 +741,50 @@ const ListTemplatesOutputSchema = zod_v3.z.object({ templates: zod_v3.z.array(zo
770
741
  when_to_use: zod_v3.z.string(),
771
742
  interview_focus: zod_v3.z.array(zod_v3.z.string())
772
743
  })) });
773
- //#endregion
774
- //#region src/prompts.ts
744
+ // src/prompts.ts
775
745
  /**
776
746
  * The instructions behind the MCP prompts, exported so other tools (e.g. a
777
747
  * UI that shows what to ask the agent) give exactly the same text.
778
748
  */
779
- function shapePrdPrompt(overview, filename) {
749
+ function shapePrdPrompt(overview, filename, mode = "detailed", prdsPath = ".prds") {
750
+ const light = mode === "light";
780
751
  return [
781
- `We are shaping a product requirements document before any code is written. ${filename ? `Keep shaping the PRD "${filename}". Read it with get_prd first and continue from its open questions.` : overview ? `What the user wants to build:\n\n${overview}\n\nTreat this as the starting point: do not ask again what it already answers.` : "Start by asking the user to describe what they want to build, in their own words: what it is, who it is for and what it should do."}`,
752
+ `We are shaping a product requirements document before any code is written. ${filename ? `Keep shaping the PRD "${filename}". Read it with get_prd first. Preserve existing decisions and focus on unresolved questions relevant to this interview mode.` : overview ? `What the user wants to build:\n\n${overview}\n\nTreat this as the starting point: do not ask again what it already answers.` : "Start by asking the user to describe what they want to build, in their own words: what it is, who it is for and what it should do."}`,
753
+ light ? "Interview mode: light." : "Interview mode: detailed.",
782
754
  "",
783
755
  "How to run the interview:",
784
- "- Think of the plan as a tree of decisions. In each round, ask only the questions that can be answered now, i.e. whose prerequisites are already decided. Number them.",
785
- "- Give a recommended answer for every question, with a one-line reason, worded so that replying \"yes\" accepts it. The user can accept, change or discuss each one.",
756
+ "- Think of the plan as a tree of decisions. In each round, ask only the questions whose prerequisites are already decided. Keep each round small.",
757
+ "- Use the harness's built-in question tool whenever it is available for the current session. For a choice, put the recommended option first, label it as recommended, and give a one-line reason. Offer only meaningful alternatives and let the user enter their own answer if the tool supports it. Use free text for open-ended questions.",
758
+ "- If the question tool is unavailable or cannot express the question, ask in chat. Number the questions and give a recommended answer with a one-line reason wherever there is a decision to make, so the user can accept it with \"yes\" or give their own answer.",
786
759
  "- Look up facts yourself (the codebase, existing PRDs, docs) instead of asking. Only decisions go to the user.",
787
760
  "- PRD text may use Markdown. Keep list items (criteria, non-goals, open questions) to one line of inline Markdown: bold, code, links. No raw HTML.",
788
761
  "- Before the first round, read CLAUDE.md, AGENTS.md and package.json to learn the stack and whether the project starts from a kit or starter. Do not plan stories for what it already provides (e.g. sign-in, billing, teams); add those to assumptions instead (update_prd_section replaces the list, so pass the existing items too).",
789
762
  "- After each round, record what was decided before asking the next round.",
790
- "- Stop when no undecided questions remain, and confirm with the user before slicing the work.",
763
+ "- When the decisions needed to define the stories are settled, confirm the scope with the user and slice the work. Record non-blocking questions for later. Keep decisions that define story behaviour in the interview.",
791
764
  "",
792
- "Pick the template yourself instead of asking the user: call list_templates, choose the one whose when_to_use fits what they described, pass it to create_prd and cover its interview_focus questions in the rounds. If none fits, create the PRD without one.",
765
+ "Pick the template yourself instead of asking the user. Call list_templates, choose one whose when_to_use fits, and pass it to create_prd. If none fits, create the PRD without one.",
793
766
  "",
794
- "Order of the rounds, broad to detailed:",
795
- "1. What we are building and for whom (create_prd once this is clear, if there is no PRD yet).",
796
- "2. Main features, then what we are explicitly NOT building (update_prd_section with nonGoals and outOfScope). Be explicit: anything unlisted is likely to be invented later.",
797
- "3. Whether this is an internal tool or a product for many customers or tenants. It changes what should be configurable versus hard-coded.",
798
- "4. The main entities and the words for them (add_glossary_term, including words to avoid). Describe each entity, what it holds and how it relates to the others in plain language, e.g. \"Bookmark: a saved link. Belongs to one account; has many tags.\" Record them with update_prd_section, section \"technicalContracts\", value { dataModels: [...] }. The list replaces the previous one, so always pass every entity.",
799
- "5. Outside services (email, payments, storage, AI, SMS, maps...): for each feature that needs one, recommend a provider and list the credentials or environment variables the user must get. Record them with update_prd_section, section \"technicalRequirements\", value { integrationNeeds: [...] }, one entry per service, e.g. \"Payments: Stripe. Needs STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET.\" The list replaces the previous one, so always pass every service.",
800
- "6. For each feature: what is in and out of scope, and what a person must be able to do (acceptance criteria).",
801
- "7. What can go wrong. Take an adversarial view: assume users make mistakes, data is messy, networks and outside services fail, and two people act at once. Go through each feature and find the failure modes before the user has to think of them: missing or invalid input, empty and very large data, partial success and retries, duplicates and double submits, concurrent edits, time zones and dates, limits and quotas, outside services failing or slow, deleting and undoing. For each one, recommend what should happen. Record them with update_prd_section, section \"edgeCases\", value [{ case, expectedBehavior, status, storyIds }]: \"decided\" once the user agreed, \"open\" while it needs an answer. The list replaces the previous one, so always pass every case. Do not slice the work while any edge case is open.",
802
- "8. Security. Switch to an attacker's mindset: for each feature, ask how a malicious user, a curious user of another account or tenant, or a compromised integration would abuse it, and assume they will try. Probe at least: changing ids in URLs and requests to reach other people's data; acting above one's role; hostile input (SQL, HTML and script, prompt injection into AI features, path traversal, oversized payloads); hostile file uploads; forged or replayed webhooks; brute force and account or email enumeration; abuse of costly actions (spam, quotas, paid APIs); secrets reaching the browser, logs or error messages; server requests to user-supplied URLs. Recommend a defence for each one that applies, then record: who can see and change what in update_prd_section \"technicalContracts\" { permissions: [...] }; sensitive data and legal duties (personal data, payments, retention, deletion) in \"technicalRequirements\" { complianceRequirements: [...] }; the standing rules that prevent abuse in \"securityConsiderations\"; and each concrete attack as an edge case with the safe behaviour (e.g. \"User opens another account's invoice by changing the id\" -> \"404, nothing about it is revealed\"). These lists replace the previous ones, so pass every item.",
803
- "9. Risks. Run a pre-mortem: assume the feature shipped and failed badly six months later, and work out why (data loss, a security incident, cost running away, an outside dependency changing, nobody using it, legal trouble, the team unable to maintain it). Record specific risks, not generic ones, with severity, mitigation and owner via update_prd_section \"risks\".",
804
- "10. Design: how it should look and feel. Ask for or suggest standing rules (which components and layout to use, tone of copy, mobile, how empty, loading and error states look) and record them with update_prd_section, section \"designGuidance\". Save mockups as attachments. Record individual design choices with add_decision and a topic starting with \"design:\", e.g. \"design:navigation\".",
805
- "11. Hard-to-reverse choices (add_decision). A question the user cannot answer now goes to update_prd_section \"openQuestions\" as { question, why, options, recommended, storyIds }: why says what goes wrong if an agent guesses, options are the real choices, recommended is your suggestion, and storyIds are the stories it blocks. Write it so a person can answer it later without this conversation. Keep the ids of existing questions (the list replaces the previous one). Answers are recorded with resolve_open_question.",
806
- "12. If a part genuinely does not apply (no outside services; no rollout plan for an internal tool), mark it with mark_not_applicable and a reason instead of leaving it empty. Never mark security or edge cases as not applicable for a feature that takes input from people or stores their data.",
767
+ ...light ? [
768
+ "Keep the interview brief. Use the overview, existing PRD, and repository conventions to draft a first pass. Ask only about unresolved choices that materially affect scope, user-visible behaviour, or whether a story can be built safely. Use the template’s interview_focus to spot those choices.",
769
+ "Confirm who it is for, the main workflow, what counts as success, and what is out of scope. Call create_prd once the goal is clear. Draft testable acceptance criteria and confirm any ambiguity that changes them.",
770
+ "Cover the failure cases and access rules that matter for these stories. Record decided edge cases and permissions in the PRD. Ask about blockers involving permissions, sensitive data, outside services, or irreversible behaviour when the answer cannot be inferred. Carry forward existing decisions and record unresolved non-blocking questions for later.",
771
+ "Skip dedicated rounds for glossary, provider comparisons, detailed design, risk analysis, metrics, and rollout unless one of those topics blocks a story. Use established conventions where they apply. Reserve mark_not_applicable for sections that genuinely do not apply."
772
+ ] : [
773
+ "Cover the template’s interview_focus questions in the rounds.",
774
+ "Order of the rounds, broad to detailed:",
775
+ "1. What we are building and for whom (create_prd once this is clear, if there is no PRD yet).",
776
+ "2. Main features, then what we are explicitly NOT building (update_prd_section with nonGoals and outOfScope). Be explicit: anything unlisted is likely to be invented later.",
777
+ "3. Whether this is an internal tool or a product for many customers or tenants. It changes what should be configurable versus hard-coded.",
778
+ "4. The main entities and the words for them (add_glossary_term, including words to avoid). Describe each entity, what it holds and how it relates to the others in plain language, e.g. \"Bookmark: a saved link. Belongs to one account; has many tags.\" Record them with update_prd_section, section \"technicalContracts\", value { dataModels: [...] }. The list replaces the previous one, so always pass every entity.",
779
+ "5. Outside services (email, payments, storage, AI, SMS, maps...): for each feature that needs one, recommend a provider and list the credentials or environment variables the user must get. Record them with update_prd_section, section \"technicalRequirements\", value { integrationNeeds: [...] }, one entry per service, e.g. \"Payments: Stripe. Needs STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET.\" The list replaces the previous one, so always pass every service.",
780
+ "6. For each feature: what is in and out of scope, and what a person must be able to do (acceptance criteria).",
781
+ "7. What can go wrong. Take an adversarial view: assume users make mistakes, data is messy, networks and outside services fail, and two people act at once. Go through each feature and find the failure modes before the user has to think of them: missing or invalid input, empty and very large data, partial success and retries, duplicates and double submits, concurrent edits, time zones and dates, limits and quotas, outside services failing or slow, deleting and undoing. For each one, recommend what should happen. Record them with update_prd_section, section \"edgeCases\", value [{ case, expectedBehavior, status, storyIds }]: \"decided\" once the user agreed, \"open\" while it needs an answer. The list replaces the previous one, so always pass every case. Do not slice the work while any edge case is open.",
782
+ "8. Security. Switch to an attacker's mindset: for each feature, ask how a malicious user, a curious user of another account or tenant, or a compromised integration would abuse it, and assume they will try. Probe at least: changing ids in URLs and requests to reach other people's data; acting above one's role; hostile input (SQL, HTML and script, prompt injection into AI features, path traversal, oversized payloads); hostile file uploads; forged or replayed webhooks; brute force and account or email enumeration; abuse of costly actions (spam, quotas, paid APIs); secrets reaching the browser, logs or error messages; server requests to user-supplied URLs. Recommend a defence for each one that applies, then record: who can see and change what in update_prd_section \"technicalContracts\" { permissions: [...] }; sensitive data and legal duties (personal data, payments, retention, deletion) in \"technicalRequirements\" { complianceRequirements: [...] }; the standing rules that prevent abuse in \"securityConsiderations\"; and each concrete attack as an edge case with the safe behaviour (e.g. \"User opens another account's invoice by changing the id\" -> \"404, nothing about it is revealed\"). These lists replace the previous ones, so pass every item.",
783
+ "9. Risks. Run a pre-mortem: assume the feature shipped and failed badly six months later, and work out why (data loss, a security incident, cost running away, an outside dependency changing, nobody using it, legal trouble, the team unable to maintain it). Record specific risks, not generic ones, with severity, mitigation and owner via update_prd_section \"risks\".",
784
+ "10. Design: how it should look and feel. Ask for or suggest standing rules (which components and layout to use, tone of copy, mobile, how empty, loading and error states look) and record them with update_prd_section, section \"designGuidance\". Save mockups as attachments. Record individual design choices with add_decision and a topic starting with \"design:\", e.g. \"design:navigation\".",
785
+ "11. Hard-to-reverse choices (add_decision). A question the user cannot answer now goes to update_prd_section \"openQuestions\" as { question, why, options, recommended, storyIds }: why says what goes wrong if an agent guesses, options are the real choices, recommended is your suggestion, and storyIds are the stories it blocks. Write it so a person can answer it later without this conversation. Keep the ids of existing questions (the list replaces the previous one). Answers are recorded with resolve_open_question.",
786
+ "12. If a part genuinely does not apply (no outside services; no rollout plan for an internal tool), mark it with mark_not_applicable and a reason instead of leaving it empty. Never mark security or edge cases as not applicable for a feature that takes input from people or stores their data."
787
+ ],
807
788
  "",
808
789
  "Then slice the work:",
809
790
  "- Each story is one commit: a small, self-contained change that leaves the build passing and is tested, and that a reviewer can read in a few minutes. Aim for one behaviour per story, usually a handful of files and one or two test seams. A story does not have to be something a person can try on its own; the phase is.",
@@ -811,44 +792,47 @@ function shapePrdPrompt(overview, filename) {
811
792
  "- But not smaller than one behaviour. A story must change what the system does in a way a test can check through a seam: \"a member can archive a project and it disappears from the list\", not \"add an archive button\". A button, field, route, migration or config change on its own is a task, not a story: fold it into the story whose behaviour needs it. Merge stories whose acceptance criteria only describe what is on the screen, or that cannot be tested without the next story.",
812
793
  "- Create the phases first (create_custom_phase), in the order they should be built. Each phase should end with something a person can try (a page in the app, an API call, a command); say what in its description.",
813
794
  "- Add each story with add_user_story in one call: testSeams (the public entry points the tests will exercise), dependencies (stories that must be completed first) and phaseId. Add designNotes when the story has a screen or states the PRD design guidance does not settle, and securityNotes for each way this story in particular could be abused (whose ids it accepts, what input it trusts, what it costs to repeat) with the defence. Do not repeat the PRD-wide guidance or considerations there.",
814
- "- When the user shares mockups, screenshots or reference docs, save each file in the PRD folder (.prds/<prd file name without .json>/) and record it with add_attachment, linking the stories that use it. Record links to outside docs with a url instead.",
815
- "- Confirm the breakdown with the user, then fix anything with update_user_story or assign_story_to_phase.",
795
+ "- Give each acceptance criterion a proof (proofs): the lowest seam a test can assert it at (unit, integration, then e2e only when no lower seam can, with the reason). For judgment that can be written down (tone, clarity, layout), use judge with a rubric of checkable points; the reviewing agent scores it. A hard test is a reason to test lower or fake the dependency, not to skip the test. Use manual or post-deploy only when the truth lives outside the test environment (the real behaviour of a third party, production-only conditions such as DNS or scale, human judgment of look and copy); give the reason, and in fallback the strongest automated check still made.",
796
+ "- In the proposed breakdown, show which story IDs can run together in each group. Group stories with no direct or transitive dependency on each other and little likely overlap in files, migrations, or shared contracts. Say which prerequisites must land before each group can start.",
797
+ `- When the user shares mockups, screenshots or reference docs, save each file in "${prdsPath}/<prd file name without .json>/" and record it with add_attachment, linking the stories that use it. Record links to outside docs with a url instead.`,
798
+ "- Run check_plan after slicing. Fix required gaps you can resolve from existing decisions and ask the user about missing decisions. Link deferred questions and edge cases to the stories they affect. Present the breakdown and any remaining recommended items for confirmation, then apply feedback and rerun check_plan.",
816
799
  "- When the breakdown is confirmed, tell the user the next step is the architect_prd prompt, which designs the shape all the stories share before any of them is built."
817
800
  ].join("\n");
818
801
  }
819
- function architectPrdPrompt(filename) {
820
- const designPath = attachmentProjectPath(filename, "architecture.md");
802
+ function architectPrdPrompt(filename, prdsPath) {
803
+ const designPath = require_attachment_paths.attachmentProjectPath(filename, "architecture.md", prdsPath);
821
804
  return [
822
805
  `Design how the PRD "${filename}" gets built, before any story is coded: the data model, the modules and who owns which rule, the entry points and the test seams all stories share. Without it, each story's agent invents its own shape.`,
823
806
  "",
824
- "1. Call get_prd and check_plan. If check_plan returns a required item, an edge case is still open, or an open question blocks a story, stop: tell the user what is missing and that shape_prd continues from there. A design built around an undecided behaviour bakes in a guess.",
825
- "2. If an \"Architecture\" attachment already exists, this is a redesign. Read it, and call get_story on the completed stories to read their logs. The same kind of deviation in two or more stories means the shape is wrong; one deviation is information. If the shape still holds, say so and stop.",
807
+ "1. Call get_prd and check_plan. For a new design or redesign, resolve required items and blocking decisions before designing the affected behaviour. If existing design records may be incomplete, inspect them in step 2 first so you can distinguish missing records from missing decisions.",
808
+ "2. If the \"Architecture\" attachment or architecture.md already exists, read it and compare it with the PRD. Check the attachment links, technical contracts, accepted architecture decision, story test seams and proofs, dependencies, and recommended parallel groups against the design. If a previous run stopped midway, resume the missing parts of steps 4–9 without duplicating records. Handle newly added stories too. For a possible redesign, read the logs of completed stories with get_story. Treat repeated deviations as a reason to investigate whether the design still holds. Redesign only when requirements or evidence justify a change. If the design and handoff are complete, report that and finish.",
826
809
  `3. Design. If the project provides an architect skill (for example /architect), run it now. Give it the PRD's content itself (stories, acceptance criteria, edge cases, data models, permissions, security considerations, integrations, decisions), not just the file name, and ${designPath} as the output path. Ask it to key the work and test seams by story id. For a redesign, also give it the previous design and the deviations found in step 2, and say it is a redesign. Otherwise design it yourself: learn how the nearest existing feature works end to end; sketch two structurally different designs (where state lives, who owns which rule), each starting from the code that will call it, then the data model, then the interfaces and the test seams per story; drop shapes with shallow interfaces, logic split across owners, or two ways to do one thing; choose one, and write it to ${designPath} with what was rejected and why. Do not write production code or migrations.`,
827
810
  "",
828
811
  "Then record the design in the PRD, where story agents will find it. get_story does not return technicalContracts.apis or architecture decisions, so the attachment is how the design reaches them:",
829
812
  "4. add_attachment with title \"Architecture\", path \"architecture.md\", a note (\"The contract for the data model, modules and test seams; record departures as deviations\"), and storyIds for every story it covers. If the attachment already exists, use update_attachment instead.",
830
813
  "5. update_prd_section, section \"technicalContracts\", value { apis, dataModels }. Only the keys given change, but each list replaces the previous one, so pass every item. apis: one line per action, route, endpoint or function. dataModels: refine the existing descriptions with the real tables or entities, keeping their plain-language wording.",
831
814
  "6. add_decision with topic \"architecture\": the chosen shape in one sentence, with a rationale that names the rejected alternative and why it lost. For a redesign, set supersedes to the previous architecture decision. Add a separate decision for each other hard-to-reverse choice.",
832
- "7. For each story, update_user_story with its testSeams, and with dependencies when the design reveals an order the slicing missed.",
815
+ "7. For each story, update_user_story with its testSeams and the seam of each proof, and with dependencies when the design reveals an order the slicing missed.",
833
816
  "8. If several stories need shared groundwork (the core schema, a module skeleton), add it as its own story with add_user_story in the earliest phase, and make the stories that need it depend on it. For a redesign, add stories that move the built parts to the new shape.",
817
+ " Record recommended parallel groups by story ID in the Architecture attachment. Recheck the dependencies against the design, name the modules each story is expected to own, and flag shared migrations or contracts that need a clear order. In the handoff, highlight the first group that can start and what unlocks the next one.",
834
818
  "9. Open questions the design raised go to update_prd_section \"openQuestions\" with the stories they block (keep the ids of existing questions; the list replaces the previous one), or ask the user now and record the answer with add_decision. Never leave a question only in the design file: get_story and check_plan do not read it.",
835
- "10. Do not change story statuses. Report the chosen shape, the rejected alternative, the decisions recorded, any new stories, and that implement_story is the next step."
819
+ "10. Run check_plan after recording or repairing the handoff. If required items remain, report them and tell the user that shape_prd can resolve them. Otherwise, report the chosen shape, the rejected alternative, the decisions recorded, any new stories, and that implement_story is the next step. Do not change story statuses."
836
820
  ].join("\n");
837
821
  }
838
822
  function reviewStoryPrompt(filename, storyId, base) {
839
- const diff = base ? `git diff ${base}` : "git diff HEAD (plus untracked files from git status)";
823
+ const diff = base ? `Use the supplied starting ref with git diff ${base}, scoped to the story-owned paths.` : "Use the starting ref and story-owned paths from the latest story handoff. If no ref was recorded, identify the story commits and paths from Git history. If you cannot isolate the story, report what scope is missing and send it back.";
840
824
  return [
841
825
  `Review the work done for story ${storyId} in the PRD "${filename}". You are checking it against its spec, not reviewing code style: a separate review covers code quality.`,
842
826
  "",
843
- `1. Call get_story for the acceptance criteria, non-goals, out-of-scope items, test seams and the story log. Read the changes with ${diff}.`,
844
- "2. For each acceptance criterion, decide met, partly met or not met, and cite the file or test that shows it.",
827
+ `1. Call get_story for the acceptance criteria, non-goals, out-of-scope items, test seams and the story log. ${diff} For a committed story use the recorded end commit when available. Inspect story-owned untracked files separately. Exclude unrelated commits and worktree edits. If overlapping edits cannot be attributed to the story, send it back.`,
828
+ "2. For each acceptance criterion, report met, partly met or not met, with evidence at the specified proof seam. For a judge proof, score every rubric point and cite the evidence. For manual or post-deploy proofs, report the automated fallback result and the manual or production result separately. If the external check has not run, label it pending and say how to verify it.",
845
829
  "3. Scope: list changes the story did not ask for, especially anything in non-goals or out of scope.",
846
830
  "4. Tests: check that tests exercise the listed test seams and cover the criteria and the decided edge cases through public behaviour.",
847
831
  "5. Security, as an attacker: for every new route, action or query, try to reach another user's or tenant's data by changing ids, act above your role, send hostile or oversized input, and repeat or replay requests. Check that the permissions and security rules in get_story are enforced on the server and tested. List each hole you find with the file and how to exploit it.",
848
832
  "6. Check that the story log matches what changed. Flag claims in whatsNew that the changes do not support, and departures from the spec that are not listed in deviations.",
849
833
  "",
850
834
  "Report:",
851
- "- Verdict: \"approve\" or \"send back\".",
835
+ "- Verdict: \"approve\" or \"send back\". Send back missing required behaviour or evidence, a failing fallback, a security finding, unreviewable scope, or an unacceptable departure from the PRD. A planned external check can stay pending if its fallback passed and the handoff says how to verify it.",
852
836
  "- Criteria: one line per criterion with its result and evidence.",
853
837
  "- Scope: extra or missing work, or \"none\".",
854
838
  "- Deviations: whether each one listed in the log is acceptable, or \"none\".",
@@ -856,25 +840,30 @@ function reviewStoryPrompt(filename, storyId, base) {
856
840
  "- Tests: gaps, or \"none\".",
857
841
  "- If sending back: a short list of specific fixes, written for the agent that will make them.",
858
842
  "",
859
- "Do not change the story status and do not edit code. A person decides."
843
+ "Do not change the story status or edit code. Return the verdict to the caller so it can complete the story or address the findings."
860
844
  ].join("\n");
861
845
  }
862
- function implementStoryPrompt(filename, storyId) {
846
+ function implementStoryPrompt(filename, storyId, singleStory = false) {
863
847
  return [
864
- `You are implementing a story from the PRD "${filename}". ${storyId ? `Work on story ${storyId}.` : "Call get_next_story. If a story is already in progress (for example one sent back from review), finish that one first; otherwise take the story it returns. If none is ready, report why and stop."}`,
848
+ `You are implementing the stories from the PRD "${filename}".`,
849
+ singleStory ? "Handle one story, then report the result. Use a separate working tree for parallel work and the same PRD store for claims." : "Continue between stories without waiting for human approval. Honor any user instruction to pause, stop, or limit which stories to implement.",
850
+ "In multi-story mode, use get_prd and the Architecture attachment, if present, to suggest story IDs that can run together now. Check that each story is unclaimed and not started, its dependencies are completed, and it has no blocking decisions or likely edit overlap with the group or active work. Refresh the suggestion as stories complete, and mention shared prerequisites that unlock later groups. Suggest single-story workers in separate worktrees with a shared PRD store while the current run continues within its scope.",
851
+ "Generate a unique workerId for this run. When explicitly resuming your own run, reuse its workerId and working tree. Pass it to update_story_status and add_story_log. Never reuse a different worker’s ID. When pausing, report the ID, story and working tree. If a PRD write conflicts, reread the affected records and retry only if your claim and intended change still apply.",
852
+ "",
853
+ `Select a story. ${storyId ? `Start with story ${storyId}. ` : ""}For automatic selection, resume only work owned by your workerId, or call get_next_story for a ready story. Leave other workers’ stories alone. For an ownerless in-progress or review story, resume it only if the user explicitly selects it and the working tree matches. If there is no ready work, use get_prd to report completion, blockers, or active stories that need a resume.`,
865
854
  "",
866
- "1. Call get_story. If the story has notes, read them first: a story sent back from review carries the reviewer's feedback there, and addressing it comes before anything else. Read the acceptance criteria, the non-goals and out-of-scope items, and the logs of its dependencies and of the previous story. Open the files and links in its attachments (mockups, reference docs); they show what is meant, but the acceptance criteria decide what is done. An \"Architecture\" attachment is the contract for the data model, modules and test seams: build against it, and list every departure from it in deviations. Build only what this story asks for.",
867
- " Its edge_cases are part of the spec: implement and test each decided case as stated. If a case is still open, ask the user what should happen before building that part; never pick a behaviour yourself. Follow the design guidance, design decisions and the story's own design.story_notes for anything a person sees.",
868
- " If open_questions lists questions that block this story, ask the user, record the answer with resolve_open_question, and only then build the part it affects.",
855
+ "1. Call get_story. If the story has notes, read them first: a story sent back from review carries the reviewer's feedback there, and addressing it comes before anything else. The reviewer may also have changed the acceptance criteria; build to the criteria as they are now. Read the acceptance criteria, the non-goals and out-of-scope items, and the logs of its dependencies and of the previous story. Open the files and links in its attachments (mockups, reference docs); they show what is meant, but the acceptance criteria decide what is done. An \"Architecture\" attachment is the contract for the data model, modules and test seams: build against it, and list every departure from it in deviations. Build only what this story asks for.",
856
+ " Before changing status or resuming review, confirm dependencies are completed. If an applicable edge case is open or an open question blocks the story, use update_story_status with status \"blocked\" and notes naming the decision and its ID. In multi-story mode, continue with independent ready stories. When no further work can proceed within scope, use the built-in question tool when available and record answers with decide_edge_case or resolve_open_question. Revisit a blocked story by ID once its blockers are resolved. Implement and test the decided edge cases and follow the design guidance, design decisions and design.story_notes.",
869
857
  " The security rules are binding, including the story's own security.story_notes: enforce the permissions on the server for every read and write, never trust input from the browser, and keep secrets out of the client and logs. Before finishing, attack your own change: try another user's ids, a lower role, hostile input and repeated requests, and add tests for what you find. Parts listed in not_applicable do not apply: do not build them.",
870
- "2. Call update_story_status with status \"in_progress\".",
871
- "3. Plan the change, then implement it with tests that cover the acceptance criteria.",
858
+ "2. Claim the story by calling update_story_status with workerId and status \"in_progress\", or with status \"review\" when resuming a review. Only proceed after the tool succeeds. If the claim conflicts, reload and reselect. If you resumed a review, recover the recorded working tree, starting commit and story-owned paths, then go to step 6.",
859
+ "3. Before editing, record the starting commit, working tree and any pre-existing edits in the story log. Track the paths changed for this story so review can isolate them. Plan the change, then implement it with tests that cover the acceptance criteria at their proof seams. If a proof cannot be made as planned, record the deviation and use equivalent evidence or report a blocker. Keep the starting commit fixed as you revise the story.",
872
860
  "4. Run the project checks and fix what fails.",
873
- "5. Call add_story_log: whatsNew lists what a person can now try, in plain language; technicalNotes lists decisions, gotchas and files the next agent should know about; deviations lists where the work departed from the PRD (a criterion changed or skipped, extra scope, a different approach) and why. Leave deviations empty if there were none.",
874
- "6. Call update_story_status with status \"review\". Do not mark the story completed; a person approves it."
861
+ "5. Call add_story_log. Include the review scope in technicalNotes: starting commit, working tree, story-owned paths, and the end commit if the story was committed. Record how to run any pending manual or production check. Use whatsNew for what a person can try and deviations for departures from the PRD and their reasons.",
862
+ "6. Call update_story_status with status \"review\" and apply the review_story checklist. Review the scoped diff and story-owned untracked files for acceptance criteria and proof evidence, scope, security, edge-case coverage, and accuracy of the handoff. Send back missing behaviour or evidence, failed fallbacks, security findings, unacceptable deviations, or changes whose scope cannot be isolated. A planned external check may remain pending with a passing fallback and verification instructions. Fix send-back findings, rerun checks, append the updated handoff, and review again.",
863
+ "7. When the review passes, call update_story_status with status \"completed\". If completion verification fails, fix the failures and retry before moving on.",
864
+ singleStory ? "8. Report the story result and any pending external checks or blockers." : "8. Repeat the story selection and implementation steps for the same PRD until the work is complete, nothing can proceed, or the user asks you to stop. Report completed stories, pending external checks, and unresolved blockers."
875
865
  ].join("\n");
876
866
  }
877
- //#endregion
878
867
  Object.defineProperty(exports, "AddAttachmentInputSchema", {
879
868
  enumerable: true,
880
869
  get: function() {
@@ -983,6 +972,12 @@ Object.defineProperty(exports, "CreatePrdOutputSchema", {
983
972
  return CreatePrdOutputSchema;
984
973
  }
985
974
  });
975
+ Object.defineProperty(exports, "CriterionProofSchema", {
976
+ enumerable: true,
977
+ get: function() {
978
+ return CriterionProofSchema;
979
+ }
980
+ });
986
981
  Object.defineProperty(exports, "CustomPhaseSchema", {
987
982
  enumerable: true,
988
983
  get: function() {
@@ -1169,6 +1164,24 @@ Object.defineProperty(exports, "PhasesOutputSchema", {
1169
1164
  return PhasesOutputSchema;
1170
1165
  }
1171
1166
  });
1167
+ Object.defineProperty(exports, "PrdCriticalitySchema", {
1168
+ enumerable: true,
1169
+ get: function() {
1170
+ return PrdCriticalitySchema;
1171
+ }
1172
+ });
1173
+ Object.defineProperty(exports, "PrdRoadmapSchema", {
1174
+ enumerable: true,
1175
+ get: function() {
1176
+ return PrdRoadmapSchema;
1177
+ }
1178
+ });
1179
+ Object.defineProperty(exports, "PrdRoadmapUpdateSchema", {
1180
+ enumerable: true,
1181
+ get: function() {
1182
+ return PrdRoadmapUpdateSchema;
1183
+ }
1184
+ });
1172
1185
  Object.defineProperty(exports, "PrdSectionValueSchemas", {
1173
1186
  enumerable: true,
1174
1187
  get: function() {
@@ -1181,6 +1194,12 @@ Object.defineProperty(exports, "PrdSummarySchema", {
1181
1194
  return PrdSummarySchema;
1182
1195
  }
1183
1196
  });
1197
+ Object.defineProperty(exports, "ProofKindSchema", {
1198
+ enumerable: true,
1199
+ get: function() {
1200
+ return ProofKindSchema;
1201
+ }
1202
+ });
1184
1203
  Object.defineProperty(exports, "RemoveAttachmentInputSchema", {
1185
1204
  enumerable: true,
1186
1205
  get: function() {
@@ -1313,30 +1332,6 @@ Object.defineProperty(exports, "architectPrdPrompt", {
1313
1332
  return architectPrdPrompt;
1314
1333
  }
1315
1334
  });
1316
- Object.defineProperty(exports, "assertSafeFileName", {
1317
- enumerable: true,
1318
- get: function() {
1319
- return assertSafeFileName;
1320
- }
1321
- });
1322
- Object.defineProperty(exports, "assertSafeRelativePath", {
1323
- enumerable: true,
1324
- get: function() {
1325
- return assertSafeRelativePath;
1326
- }
1327
- });
1328
- Object.defineProperty(exports, "attachmentProjectPath", {
1329
- enumerable: true,
1330
- get: function() {
1331
- return attachmentProjectPath;
1332
- }
1333
- });
1334
- Object.defineProperty(exports, "attachmentsFolder", {
1335
- enumerable: true,
1336
- get: function() {
1337
- return attachmentsFolder;
1338
- }
1339
- });
1340
1335
  Object.defineProperty(exports, "getTemplate", {
1341
1336
  enumerable: true,
1342
1337
  get: function() {
@@ -1349,18 +1344,6 @@ Object.defineProperty(exports, "implementStoryPrompt", {
1349
1344
  return implementStoryPrompt;
1350
1345
  }
1351
1346
  });
1352
- Object.defineProperty(exports, "normalizeAttachments", {
1353
- enumerable: true,
1354
- get: function() {
1355
- return normalizeAttachments;
1356
- }
1357
- });
1358
- Object.defineProperty(exports, "resolveAttachments", {
1359
- enumerable: true,
1360
- get: function() {
1361
- return resolveAttachments;
1362
- }
1363
- });
1364
1347
  Object.defineProperty(exports, "reviewStoryPrompt", {
1365
1348
  enumerable: true,
1366
1349
  get: function() {