@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
package/src/prompts.ts ADDED
@@ -0,0 +1,161 @@
1
+ import { attachmentProjectPath } from './attachment-paths';
2
+
3
+ /**
4
+ * The instructions behind the MCP prompts, exported so other tools (e.g. a
5
+ * UI that shows what to ask the agent) give exactly the same text.
6
+ */
7
+
8
+ export function shapePrdPrompt(
9
+ overview?: string,
10
+ filename?: string,
11
+ mode: 'light' | 'detailed' = 'detailed',
12
+ prdsPath = '.prds',
13
+ ) {
14
+ const light = mode === 'light';
15
+ const start = filename
16
+ ? `Keep shaping the PRD "${filename}". Read it with get_prd first. Preserve existing decisions and focus on unresolved questions relevant to this interview mode.`
17
+ : overview
18
+ ? `What the user wants to build:\n\n${overview}\n\nTreat this as the starting point: do not ask again what it already answers.`
19
+ : '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.';
20
+
21
+ return [
22
+ `We are shaping a product requirements document before any code is written. ${start}`,
23
+ light ? 'Interview mode: light.' : 'Interview mode: detailed.',
24
+ '',
25
+ 'How to run the interview:',
26
+ '- 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.',
27
+ "- 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.",
28
+ '- 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.',
29
+ '- Look up facts yourself (the codebase, existing PRDs, docs) instead of asking. Only decisions go to the user.',
30
+ '- 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.',
31
+ '- 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).',
32
+ '- After each round, record what was decided before asking the next round.',
33
+ '- 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.',
34
+ '',
35
+ '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.',
36
+ '',
37
+ ...(light
38
+ ? [
39
+ '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.',
40
+ '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.',
41
+ '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.',
42
+ '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.',
43
+ ]
44
+ : [
45
+ 'Cover the template’s interview_focus questions in the rounds.',
46
+ 'Order of the rounds, broad to detailed:',
47
+ '1. What we are building and for whom (create_prd once this is clear, if there is no PRD yet).',
48
+ '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.',
49
+ '3. Whether this is an internal tool or a product for many customers or tenants. It changes what should be configurable versus hard-coded.',
50
+ '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.',
51
+ '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.',
52
+ '6. For each feature: what is in and out of scope, and what a person must be able to do (acceptance criteria).',
53
+ '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.',
54
+ '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.',
55
+ '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".',
56
+ '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".',
57
+ '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.',
58
+ '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.',
59
+ ]),
60
+ '',
61
+ 'Then slice the work:',
62
+ '- 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.',
63
+ '- Size stories small. Split one that has more than three or four acceptance criteria, covers several screens, endpoints or roles, or needs "and" in its title. More small stories are better than a few broad ones. Still slice vertically where you can (one field end to end, not every field in one layer), and put refactoring needed by later stories in its own earlier story.',
64
+ '- 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.',
65
+ '- 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.',
66
+ '- 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.',
67
+ '- 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.',
68
+ '- 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.',
69
+ `- 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.`,
70
+ '- 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.',
71
+ '- 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.',
72
+ ].join('\n');
73
+ }
74
+
75
+ export function architectPrdPrompt(filename: string, prdsPath?: string) {
76
+ const designPath = attachmentProjectPath(
77
+ filename,
78
+ 'architecture.md',
79
+ prdsPath,
80
+ );
81
+
82
+ return [
83
+ `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.`,
84
+ '',
85
+ '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.',
86
+ '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.',
87
+ `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.`,
88
+ '',
89
+ '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:',
90
+ '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.',
91
+ '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.',
92
+ '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.',
93
+ '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.',
94
+ '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.',
95
+ ' 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.',
96
+ '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.',
97
+ '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.',
98
+ ].join('\n');
99
+ }
100
+
101
+ export function reviewStoryPrompt(
102
+ filename: string,
103
+ storyId: string,
104
+ base?: string,
105
+ ) {
106
+ const diff = base
107
+ ? `Use the supplied starting ref with git diff ${base}, scoped to the story-owned paths.`
108
+ : '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.';
109
+
110
+ return [
111
+ `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.`,
112
+ '',
113
+ `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.`,
114
+ '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.',
115
+ '3. Scope: list changes the story did not ask for, especially anything in non-goals or out of scope.',
116
+ '4. Tests: check that tests exercise the listed test seams and cover the criteria and the decided edge cases through public behaviour.',
117
+ "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.",
118
+ '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.',
119
+ '',
120
+ 'Report:',
121
+ '- 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.',
122
+ '- Criteria: one line per criterion with its result and evidence.',
123
+ '- Scope: extra or missing work, or "none".',
124
+ '- Deviations: whether each one listed in the log is acceptable, or "none".',
125
+ '- Security: holes found, or "none".',
126
+ '- Tests: gaps, or "none".',
127
+ '- If sending back: a short list of specific fixes, written for the agent that will make them.',
128
+ '',
129
+ '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.',
130
+ ].join('\n');
131
+ }
132
+
133
+ export function implementStoryPrompt(
134
+ filename: string,
135
+ storyId?: string,
136
+ singleStory = false,
137
+ ) {
138
+ return [
139
+ `You are implementing the stories from the PRD "${filename}".`,
140
+ singleStory
141
+ ? 'Handle one story, then report the result. Use a separate working tree for parallel work and the same PRD store for claims.'
142
+ : 'Continue between stories without waiting for human approval. Honor any user instruction to pause, stop, or limit which stories to implement.',
143
+ '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.',
144
+ '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.',
145
+ '',
146
+ `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.`,
147
+ '',
148
+ '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.',
149
+ ' 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.',
150
+ " 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.",
151
+ '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.',
152
+ '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.',
153
+ '4. Run the project checks and fix what fails.',
154
+ '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.',
155
+ '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.',
156
+ '7. When the review passes, call update_story_status with status "completed". If completion verification fails, fix the failures and retry before moving on.',
157
+ singleStory
158
+ ? '8. Report the story result and any pending external checks or blockers.'
159
+ : '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.',
160
+ ].join('\n');
161
+ }
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Accept only a bare file name. Anything that could escape the intended
3
+ * directory (path separators, parent references, hidden files) is rejected
4
+ * before the filesystem is touched.
5
+ */
6
+ export function assertSafeFileName(value: string, label = 'file name') {
7
+ const name = value.trim();
8
+
9
+ if (
10
+ name.length === 0 ||
11
+ name.includes('..') ||
12
+ name.includes('/') ||
13
+ name.includes('\\') ||
14
+ name.startsWith('.')
15
+ ) {
16
+ throw new Error(`Invalid ${label} "${value}"`);
17
+ }
18
+
19
+ return name;
20
+ }
21
+
22
+ /**
23
+ * Accept only a relative path that stays inside the directory it is joined
24
+ * to: no absolute paths, no `..`, no backslashes, no empty or hidden segments.
25
+ * This is a check on the text only; code that serves the file must still
26
+ * resolve symlinks before reading it.
27
+ */
28
+ export function assertSafeRelativePath(value: string, label = 'path') {
29
+ const path = value.trim();
30
+ const segments = path.split('/');
31
+
32
+ if (
33
+ path.length === 0 ||
34
+ path.includes('\\') ||
35
+ /^[a-zA-Z]:/.test(path) ||
36
+ segments.some((segment) => segment.length === 0 || segment.startsWith('.'))
37
+ ) {
38
+ throw new Error(`Invalid ${label} "${value}"`);
39
+ }
40
+
41
+ return path;
42
+ }