@makerkit/prd 0.0.0 → 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +2 -21
- package/.turbo/turbo-build.log +0 -46
- package/.turbo/turbo-test.log +0 -21
- package/.turbo/turbo-typecheck.log +0 -1
- package/dist/README.md +0 -65
- package/dist/package.json +0 -49
- package/src/__tests__/agent-workflow.test.ts +0 -377
- package/src/__tests__/attachments.test.ts +0 -475
- package/src/__tests__/node.test.ts +0 -141
- package/src/__tests__/plan-check.test.ts +0 -229
- package/src/__tests__/planning.test.ts +0 -1059
- package/src/__tests__/prd-operations.test.ts +0 -423
- package/src/__tests__/prd.service.test.ts +0 -477
- package/src/__tests__/prd.tool.test.ts +0 -282
- package/src/__tests__/templates.test.ts +0 -141
- package/src/applicability.ts +0 -73
- package/src/attachment-paths.ts +0 -78
- package/src/attachments.ts +0 -160
- package/src/edge-cases.ts +0 -52
- package/src/index.ts +0 -35
- package/src/markdown.ts +0 -268
- package/src/mcp/index.ts +0 -839
- package/src/mcp/tool-response.ts +0 -85
- package/src/node.ts +0 -146
- package/src/open-questions.ts +0 -93
- package/src/plan-check.ts +0 -282
- package/src/planning-operations.ts +0 -429
- package/src/prd-operations.ts +0 -690
- package/src/prd.service.ts +0 -1051
- package/src/prompts.ts +0 -110
- package/src/safe-file-name.ts +0 -42
- package/src/schema.ts +0 -976
- package/src/templates.ts +0 -173
- package/src/testing/fake-mcp-server.ts +0 -81
- package/src/types.ts +0 -333
- package/tsconfig.json +0 -23
- package/tsconfig.lib.json +0 -8
- package/tsconfig.spec.json +0 -7
- package/tsdown.config.mts +0 -11
- package/vitest.config.mts +0 -8
- /package/{dist/LICENSE → LICENSE} +0 -0
- /package/{dist/index.d.ts → index.d.ts} +0 -0
- /package/{dist/index.js → index.js} +0 -0
- /package/{dist/index.mjs → index.mjs} +0 -0
- /package/{dist/mcp.d.ts → mcp.d.ts} +0 -0
- /package/{dist/mcp.js → mcp.js} +0 -0
- /package/{dist/mcp.mjs → mcp.mjs} +0 -0
- /package/{dist/node.d.ts → node.d.ts} +0 -0
- /package/{dist/node.js → node.js} +0 -0
- /package/{dist/node.mjs → node.mjs} +0 -0
- /package/{dist/prd.service-DSBp8sMl.d.ts → prd.service-DSBp8sMl.d.ts} +0 -0
- /package/{dist/prompts-Bber0S1Z.mjs → prompts-Bber0S1Z.mjs} +0 -0
- /package/{dist/prompts-CIX8IeAx.js → prompts-CIX8IeAx.js} +0 -0
package/src/mcp/tool-response.ts
DELETED
|
@@ -1,85 +0,0 @@
|
|
|
1
|
-
import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
|
|
2
|
-
|
|
3
|
-
type TextContent = {
|
|
4
|
-
type: 'text';
|
|
5
|
-
text: string;
|
|
6
|
-
};
|
|
7
|
-
|
|
8
|
-
/**
|
|
9
|
-
* Standard annotation presets. Every registered tool must declare one so MCP
|
|
10
|
-
* clients can gate permissions correctly (e.g. auto-approve read-only tools,
|
|
11
|
-
* always confirm destructive ones).
|
|
12
|
-
*/
|
|
13
|
-
export const READ_ONLY_TOOL: ToolAnnotations = {
|
|
14
|
-
readOnlyHint: true,
|
|
15
|
-
destructiveHint: false,
|
|
16
|
-
idempotentHint: true,
|
|
17
|
-
openWorldHint: false,
|
|
18
|
-
};
|
|
19
|
-
|
|
20
|
-
/** Writes files or state but can be re-applied safely and is reversible. */
|
|
21
|
-
export const MUTATING_TOOL: ToolAnnotations = {
|
|
22
|
-
readOnlyHint: false,
|
|
23
|
-
destructiveHint: false,
|
|
24
|
-
idempotentHint: false,
|
|
25
|
-
openWorldHint: false,
|
|
26
|
-
};
|
|
27
|
-
|
|
28
|
-
/** Same as MUTATING_TOOL but repeating the call has no further effect. */
|
|
29
|
-
export const IDEMPOTENT_MUTATING_TOOL: ToolAnnotations = {
|
|
30
|
-
readOnlyHint: false,
|
|
31
|
-
destructiveHint: false,
|
|
32
|
-
idempotentHint: true,
|
|
33
|
-
openWorldHint: false,
|
|
34
|
-
};
|
|
35
|
-
|
|
36
|
-
/** Deletes or irreversibly replaces data. Clients should always confirm. */
|
|
37
|
-
export const DESTRUCTIVE_TOOL: ToolAnnotations = {
|
|
38
|
-
readOnlyHint: false,
|
|
39
|
-
destructiveHint: true,
|
|
40
|
-
idempotentHint: false,
|
|
41
|
-
openWorldHint: false,
|
|
42
|
-
};
|
|
43
|
-
|
|
44
|
-
/** Read-only but reaches the network (e.g. registry lookups). */
|
|
45
|
-
export const READ_ONLY_OPEN_WORLD_TOOL: ToolAnnotations = {
|
|
46
|
-
readOnlyHint: true,
|
|
47
|
-
destructiveHint: false,
|
|
48
|
-
idempotentHint: true,
|
|
49
|
-
openWorldHint: true,
|
|
50
|
-
};
|
|
51
|
-
|
|
52
|
-
export function buildStructuredResponse<T extends Record<string, unknown>>(
|
|
53
|
-
result: T,
|
|
54
|
-
) {
|
|
55
|
-
return {
|
|
56
|
-
structuredContent: result,
|
|
57
|
-
content: buildTextContent(JSON.stringify(result)),
|
|
58
|
-
};
|
|
59
|
-
}
|
|
60
|
-
|
|
61
|
-
export function buildErrorResponse(tool: string, error: unknown) {
|
|
62
|
-
const message = `${tool} failed: ${toErrorMessage(error)}`;
|
|
63
|
-
|
|
64
|
-
return {
|
|
65
|
-
isError: true as const,
|
|
66
|
-
structuredContent: {
|
|
67
|
-
error: {
|
|
68
|
-
message,
|
|
69
|
-
},
|
|
70
|
-
},
|
|
71
|
-
content: buildTextContent(message),
|
|
72
|
-
};
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
export function toErrorMessage(error: unknown) {
|
|
76
|
-
if (error instanceof Error) {
|
|
77
|
-
return error.message;
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
return 'Unknown error';
|
|
81
|
-
}
|
|
82
|
-
|
|
83
|
-
export function buildTextContent(text: string): TextContent[] {
|
|
84
|
-
return [{ type: 'text', text }];
|
|
85
|
-
}
|
package/src/node.ts
DELETED
|
@@ -1,146 +0,0 @@
|
|
|
1
|
-
import { createRepoChecksServices } from '@makerkit/repo-checks/node';
|
|
2
|
-
|
|
3
|
-
import type { PrdDeps, PrdVerificationResult } from './prd.service';
|
|
4
|
-
|
|
5
|
-
import {
|
|
6
|
-
access,
|
|
7
|
-
mkdir,
|
|
8
|
-
readFile,
|
|
9
|
-
readdir,
|
|
10
|
-
unlink,
|
|
11
|
-
writeFile,
|
|
12
|
-
} from 'node:fs/promises';
|
|
13
|
-
import { join } from 'node:path';
|
|
14
|
-
|
|
15
|
-
/** Check-only scripts that gate marking a story as completed. */
|
|
16
|
-
const DEFAULT_COMPLETION_CHECKS = ['typecheck', 'lint'];
|
|
17
|
-
|
|
18
|
-
/** Output kept from a failing script, so the reason fits in a tool response. */
|
|
19
|
-
const MAX_FAILURE_DETAIL = 300;
|
|
20
|
-
|
|
21
|
-
export interface NodePrdDepsOptions {
|
|
22
|
-
/**
|
|
23
|
-
* Decides whether a story may be marked completed. Defaults to running the
|
|
24
|
-
* project's `typecheck` and `lint` scripts (see `createScriptVerifier`).
|
|
25
|
-
*/
|
|
26
|
-
verifyCompletion?: PrdDeps['verifyCompletion'];
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
/** PRD dependencies backed by the local filesystem, rooted at `rootPath`. */
|
|
30
|
-
export function createNodePrdDeps(
|
|
31
|
-
rootPath = process.cwd(),
|
|
32
|
-
options: NodePrdDepsOptions = {},
|
|
33
|
-
): PrdDeps {
|
|
34
|
-
return {
|
|
35
|
-
rootPath,
|
|
36
|
-
readdir(path) {
|
|
37
|
-
return readdir(path);
|
|
38
|
-
},
|
|
39
|
-
readFile(path) {
|
|
40
|
-
return readFile(path, 'utf8');
|
|
41
|
-
},
|
|
42
|
-
writeFile(path, content) {
|
|
43
|
-
return writeFile(path, content, 'utf8');
|
|
44
|
-
},
|
|
45
|
-
async mkdir(path) {
|
|
46
|
-
await mkdir(path, { recursive: true });
|
|
47
|
-
},
|
|
48
|
-
unlink(path) {
|
|
49
|
-
return unlink(path);
|
|
50
|
-
},
|
|
51
|
-
fileExists,
|
|
52
|
-
now() {
|
|
53
|
-
return new Date();
|
|
54
|
-
},
|
|
55
|
-
verifyCompletion:
|
|
56
|
-
options.verifyCompletion ?? createScriptVerifier(rootPath),
|
|
57
|
-
};
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
/**
|
|
61
|
-
* Verifies completion by running the project's package.json scripts with its
|
|
62
|
-
* package manager (via @makerkit/repo-checks), so a failure comes back as
|
|
63
|
-
* file-and-line diagnostics. Scripts the project does not define are skipped,
|
|
64
|
-
* so a repo without e.g. `lint` can still complete stories.
|
|
65
|
-
*/
|
|
66
|
-
export function createScriptVerifier(
|
|
67
|
-
rootPath: string,
|
|
68
|
-
scripts: string[] = DEFAULT_COMPLETION_CHECKS,
|
|
69
|
-
): PrdDeps['verifyCompletion'] {
|
|
70
|
-
return async () => {
|
|
71
|
-
// A project can be just a folder with .prds: nothing to check then
|
|
72
|
-
if (!(await fileExists(join(rootPath, 'package.json')))) {
|
|
73
|
-
return {
|
|
74
|
-
passed: true,
|
|
75
|
-
checks: [],
|
|
76
|
-
errors: 0,
|
|
77
|
-
warnings: 0,
|
|
78
|
-
diagnostics: [],
|
|
79
|
-
messages: ['No package.json: there are no project checks to run.'],
|
|
80
|
-
} satisfies PrdVerificationResult;
|
|
81
|
-
}
|
|
82
|
-
|
|
83
|
-
const checks = createRepoChecksServices(rootPath);
|
|
84
|
-
const { scripts: available } = await checks.scripts.list();
|
|
85
|
-
const defined = new Set(available.map((script) => script.name));
|
|
86
|
-
|
|
87
|
-
const toRun = scripts.filter((script) => defined.has(script));
|
|
88
|
-
const skipped = scripts.filter((script) => !defined.has(script));
|
|
89
|
-
|
|
90
|
-
const messages = skipped.map(
|
|
91
|
-
(script) => `${script}: skipped (no "${script}" script in package.json)`,
|
|
92
|
-
);
|
|
93
|
-
|
|
94
|
-
if (toRun.length === 0) {
|
|
95
|
-
return {
|
|
96
|
-
passed: true,
|
|
97
|
-
checks: [],
|
|
98
|
-
errors: 0,
|
|
99
|
-
warnings: 0,
|
|
100
|
-
diagnostics: [],
|
|
101
|
-
messages,
|
|
102
|
-
} satisfies PrdVerificationResult;
|
|
103
|
-
}
|
|
104
|
-
|
|
105
|
-
const result = await checks.runChecks.run({ scripts: toRun });
|
|
106
|
-
|
|
107
|
-
// Failures the parser found no diagnostics for: report the output tail
|
|
108
|
-
// instead of "0 errors".
|
|
109
|
-
const unexplained = result.checks.filter(
|
|
110
|
-
(check) => check.status !== 'pass' && check.diagnostics.length === 0,
|
|
111
|
-
);
|
|
112
|
-
|
|
113
|
-
for (const check of unexplained) {
|
|
114
|
-
const detail = (check.stderr.trim() || check.stdout.trim()).slice(
|
|
115
|
-
-MAX_FAILURE_DETAIL,
|
|
116
|
-
);
|
|
117
|
-
|
|
118
|
-
messages.push(
|
|
119
|
-
`${check.script}: ${check.status}${detail ? ` (${detail})` : ''}`,
|
|
120
|
-
);
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
return {
|
|
124
|
-
passed: result.overall === 'pass',
|
|
125
|
-
checks: result.scripts_requested,
|
|
126
|
-
errors: result.summary.errors + unexplained.length,
|
|
127
|
-
warnings: result.summary.warnings,
|
|
128
|
-
diagnostics: result.diagnostics.map((diagnostic) => ({
|
|
129
|
-
file: diagnostic.file,
|
|
130
|
-
line: diagnostic.line,
|
|
131
|
-
message: diagnostic.message,
|
|
132
|
-
severity: diagnostic.severity,
|
|
133
|
-
})),
|
|
134
|
-
messages,
|
|
135
|
-
} satisfies PrdVerificationResult;
|
|
136
|
-
};
|
|
137
|
-
}
|
|
138
|
-
|
|
139
|
-
async function fileExists(path: string) {
|
|
140
|
-
try {
|
|
141
|
-
await access(path);
|
|
142
|
-
return true;
|
|
143
|
-
} catch {
|
|
144
|
-
return false;
|
|
145
|
-
}
|
|
146
|
-
}
|
package/src/open-questions.ts
DELETED
|
@@ -1,93 +0,0 @@
|
|
|
1
|
-
import type { OpenQuestion, StructuredPRD } from './types';
|
|
2
|
-
|
|
3
|
-
/**
|
|
4
|
-
* Open questions as stored. Older files hold plain strings; they become
|
|
5
|
-
* questions with ids in list order. Entries without question text are dropped.
|
|
6
|
-
*/
|
|
7
|
-
export function normalizeOpenQuestions(value: unknown): OpenQuestion[] {
|
|
8
|
-
if (!Array.isArray(value)) {
|
|
9
|
-
return [];
|
|
10
|
-
}
|
|
11
|
-
|
|
12
|
-
const questions: OpenQuestion[] = [];
|
|
13
|
-
|
|
14
|
-
for (const entry of value) {
|
|
15
|
-
if (typeof entry === 'string') {
|
|
16
|
-
if (entry.trim()) {
|
|
17
|
-
questions.push({ id: '', question: entry });
|
|
18
|
-
}
|
|
19
|
-
|
|
20
|
-
continue;
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
if (typeof entry !== 'object' || entry === null) {
|
|
24
|
-
continue;
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
const { id, question, why, options, recommended, storyIds } = entry as Record<
|
|
28
|
-
string,
|
|
29
|
-
unknown
|
|
30
|
-
>;
|
|
31
|
-
|
|
32
|
-
if (typeof question !== 'string' || !question.trim()) {
|
|
33
|
-
continue;
|
|
34
|
-
}
|
|
35
|
-
|
|
36
|
-
const strings = (list: unknown) =>
|
|
37
|
-
Array.isArray(list)
|
|
38
|
-
? list.filter((item): item is string => typeof item === 'string' && item.length > 0)
|
|
39
|
-
: [];
|
|
40
|
-
|
|
41
|
-
questions.push({
|
|
42
|
-
id: typeof id === 'string' ? id : '',
|
|
43
|
-
question,
|
|
44
|
-
...(typeof why === 'string' && why ? { why } : {}),
|
|
45
|
-
...(strings(options).length ? { options: strings(options) } : {}),
|
|
46
|
-
...(typeof recommended === 'string' && recommended ? { recommended } : {}),
|
|
47
|
-
...(strings(storyIds).length ? { storyIds: strings(storyIds) } : {}),
|
|
48
|
-
});
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
// Legacy strings (and hand-written entries) get ids after the highest one present
|
|
52
|
-
let highest = questions.reduce((max, question) => {
|
|
53
|
-
const match = /^Q(\d+)$/.exec(question.id);
|
|
54
|
-
|
|
55
|
-
return match ? Math.max(max, Number(match[1])) : max;
|
|
56
|
-
}, 0);
|
|
57
|
-
|
|
58
|
-
return questions.map((question) =>
|
|
59
|
-
question.id ? question : { ...question, id: formatQuestionId(++highest) },
|
|
60
|
-
);
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
function formatQuestionId(number: number) {
|
|
64
|
-
return `Q${String(number).padStart(3, '0')}`;
|
|
65
|
-
}
|
|
66
|
-
|
|
67
|
-
/**
|
|
68
|
-
* The next question id. Answered questions are quoted in decisions, so an id
|
|
69
|
-
* is never handed out twice: the high-water mark is kept in metadata.
|
|
70
|
-
*/
|
|
71
|
-
export function nextQuestionId(prd: StructuredPRD, extra: OpenQuestion[] = []) {
|
|
72
|
-
const present = [...prd.openQuestions, ...extra].reduce((max, question) => {
|
|
73
|
-
const match = /^Q(\d+)$/.exec(question.id);
|
|
74
|
-
|
|
75
|
-
return match ? Math.max(max, Number(match[1])) : max;
|
|
76
|
-
}, 0);
|
|
77
|
-
const next = Math.max(prd.metadata.lastQuestionNumber ?? 0, present) + 1;
|
|
78
|
-
|
|
79
|
-
prd.metadata.lastQuestionNumber = next;
|
|
80
|
-
|
|
81
|
-
return formatQuestionId(next);
|
|
82
|
-
}
|
|
83
|
-
|
|
84
|
-
/** Open questions that block a story that is not completed yet. */
|
|
85
|
-
export function blockingQuestions(prd: StructuredPRD) {
|
|
86
|
-
const unfinished = new Set(
|
|
87
|
-
prd.userStories.filter((story) => story.status !== 'completed').map((story) => story.id),
|
|
88
|
-
);
|
|
89
|
-
|
|
90
|
-
return prd.openQuestions.filter((question) =>
|
|
91
|
-
question.storyIds?.some((id) => unfinished.has(id)),
|
|
92
|
-
);
|
|
93
|
-
}
|
package/src/plan-check.ts
DELETED
|
@@ -1,282 +0,0 @@
|
|
|
1
|
-
import { isNotApplicable } from './applicability';
|
|
2
|
-
import { blockingQuestions } from './open-questions';
|
|
3
|
-
import type { NotApplicableTopic, StructuredPRD } from './types';
|
|
4
|
-
|
|
5
|
-
/**
|
|
6
|
-
* What a plan is still missing, as items a UI can render as a checklist and an
|
|
7
|
-
* agent can act on. `required` items mean the plan is not ready to build;
|
|
8
|
-
* `recommended` items make it better but do not block.
|
|
9
|
-
*/
|
|
10
|
-
export interface PlanCheckItem {
|
|
11
|
-
/** Stable key, e.g. `stories` or `vague-stories`. */
|
|
12
|
-
id: string;
|
|
13
|
-
/** The PRD section to change, matching `update_prd_section` where possible. */
|
|
14
|
-
section: string;
|
|
15
|
-
message: string;
|
|
16
|
-
severity: 'required' | 'recommended';
|
|
17
|
-
/** Stories the item is about, when it is about specific stories. */
|
|
18
|
-
storyIds?: string[];
|
|
19
|
-
}
|
|
20
|
-
|
|
21
|
-
/** The not-applicable topic each "missing" check is about. */
|
|
22
|
-
const CHECK_TOPICS: Record<string, NotApplicableTopic> = {
|
|
23
|
-
'edge-cases': 'edgeCases',
|
|
24
|
-
'design-guidance': 'design',
|
|
25
|
-
security: 'security',
|
|
26
|
-
permissions: 'security',
|
|
27
|
-
'global-acceptance-criteria': 'qualityBar',
|
|
28
|
-
'target-metrics': 'measurement',
|
|
29
|
-
rollout: 'rollout',
|
|
30
|
-
'data-models': 'dataModel',
|
|
31
|
-
};
|
|
32
|
-
|
|
33
|
-
/** Above this many stories, grouping them into phases is recommended. */
|
|
34
|
-
const PHASE_THRESHOLD = 5;
|
|
35
|
-
|
|
36
|
-
export function checkPlan(prd: StructuredPRD) {
|
|
37
|
-
const items: PlanCheckItem[] = [];
|
|
38
|
-
const stories = prd.userStories;
|
|
39
|
-
|
|
40
|
-
if (stories.length === 0) {
|
|
41
|
-
items.push({
|
|
42
|
-
id: 'stories',
|
|
43
|
-
section: 'userStories',
|
|
44
|
-
message: 'Add user stories to define specific functionality',
|
|
45
|
-
severity: 'required',
|
|
46
|
-
});
|
|
47
|
-
}
|
|
48
|
-
|
|
49
|
-
const withoutCriteria = stories.filter(
|
|
50
|
-
(story) => story.acceptanceCriteria.length === 0,
|
|
51
|
-
);
|
|
52
|
-
|
|
53
|
-
if (withoutCriteria.length > 0) {
|
|
54
|
-
items.push({
|
|
55
|
-
id: 'stories-without-criteria',
|
|
56
|
-
section: 'userStories',
|
|
57
|
-
message: `${withoutCriteria.length} stories have no acceptance criteria`,
|
|
58
|
-
severity: 'required',
|
|
59
|
-
storyIds: withoutCriteria.map((story) => story.id),
|
|
60
|
-
});
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
// What can go wrong is where agents guess most; a plan must say.
|
|
64
|
-
if (stories.length > 0 && prd.edgeCases.length === 0) {
|
|
65
|
-
items.push({
|
|
66
|
-
id: 'edge-cases',
|
|
67
|
-
section: 'edgeCases',
|
|
68
|
-
message:
|
|
69
|
-
'List what can go wrong (bad input, partial success, retries, permissions, limits, time zones) and what should happen',
|
|
70
|
-
severity: 'required',
|
|
71
|
-
});
|
|
72
|
-
}
|
|
73
|
-
|
|
74
|
-
const openEdgeCases = prd.edgeCases.filter((edgeCase) => edgeCase.status === 'open');
|
|
75
|
-
|
|
76
|
-
if (openEdgeCases.length > 0) {
|
|
77
|
-
items.push({
|
|
78
|
-
id: 'open-edge-cases',
|
|
79
|
-
section: 'edgeCases',
|
|
80
|
-
message: `${openEdgeCases.length} edge cases are still open; decide what should happen`,
|
|
81
|
-
severity: 'required',
|
|
82
|
-
storyIds: [...new Set(openEdgeCases.flatMap((edgeCase) => edgeCase.storyIds ?? []))],
|
|
83
|
-
});
|
|
84
|
-
}
|
|
85
|
-
|
|
86
|
-
if (stories.length > 0 && prd.designGuidance.length === 0) {
|
|
87
|
-
items.push({
|
|
88
|
-
id: 'design-guidance',
|
|
89
|
-
section: 'designGuidance',
|
|
90
|
-
message:
|
|
91
|
-
'Add design guidance: the components, layout and tone stories should follow, and how empty and error states look',
|
|
92
|
-
severity: 'recommended',
|
|
93
|
-
});
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
// Who can do what must be stated once there is data or an outside service
|
|
97
|
-
// to protect; agents otherwise default to "any signed-in user".
|
|
98
|
-
if (
|
|
99
|
-
stories.length > 0 &&
|
|
100
|
-
prd.technicalContracts.permissions.length === 0 &&
|
|
101
|
-
(prd.technicalContracts.dataModels.length > 0 ||
|
|
102
|
-
prd.technicalRequirements.integrationNeeds.length > 0)
|
|
103
|
-
) {
|
|
104
|
-
items.push({
|
|
105
|
-
id: 'permissions',
|
|
106
|
-
section: 'technicalContracts',
|
|
107
|
-
message:
|
|
108
|
-
'Say who can see and change what (roles, ownership, other tenants) in technicalContracts.permissions',
|
|
109
|
-
severity: 'required',
|
|
110
|
-
});
|
|
111
|
-
}
|
|
112
|
-
|
|
113
|
-
if (stories.length > 0 && prd.securityConsiderations.length === 0) {
|
|
114
|
-
items.push({
|
|
115
|
-
id: 'security',
|
|
116
|
-
section: 'securityConsiderations',
|
|
117
|
-
message:
|
|
118
|
-
'Add security considerations: think like an attacker (inputs, access to other users\' data, secrets, abuse, rate limits) and state the rules that prevent it',
|
|
119
|
-
severity: 'recommended',
|
|
120
|
-
});
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
if (prd.nonGoals.length === 0 && prd.outOfScope.length === 0) {
|
|
124
|
-
items.push({
|
|
125
|
-
id: 'scope',
|
|
126
|
-
section: 'nonGoals',
|
|
127
|
-
message:
|
|
128
|
-
'Define both non-goals and out-of-scope items to reduce implementation drift',
|
|
129
|
-
severity: 'required',
|
|
130
|
-
});
|
|
131
|
-
} else if (prd.nonGoals.length === 0 || prd.outOfScope.length === 0) {
|
|
132
|
-
items.push({
|
|
133
|
-
id: 'scope',
|
|
134
|
-
section: prd.nonGoals.length === 0 ? 'nonGoals' : 'outOfScope',
|
|
135
|
-
message:
|
|
136
|
-
'Define both non-goals and out-of-scope items to reduce implementation drift',
|
|
137
|
-
severity: 'recommended',
|
|
138
|
-
});
|
|
139
|
-
}
|
|
140
|
-
|
|
141
|
-
if (prd.solutionOverview.successMetrics.length === 0) {
|
|
142
|
-
items.push({
|
|
143
|
-
id: 'success-metrics',
|
|
144
|
-
section: 'solutionOverview',
|
|
145
|
-
message: 'Define success metrics to measure progress',
|
|
146
|
-
severity: 'recommended',
|
|
147
|
-
});
|
|
148
|
-
}
|
|
149
|
-
|
|
150
|
-
if (prd.acceptanceCriteria.global.length === 0) {
|
|
151
|
-
items.push({
|
|
152
|
-
id: 'global-acceptance-criteria',
|
|
153
|
-
section: 'acceptanceCriteria',
|
|
154
|
-
message: 'Add global acceptance criteria for quality standards',
|
|
155
|
-
severity: 'recommended',
|
|
156
|
-
});
|
|
157
|
-
}
|
|
158
|
-
|
|
159
|
-
// A question that blocks a story must be answered before that story is
|
|
160
|
-
// built; the others improve the plan but can wait.
|
|
161
|
-
const blocking = blockingQuestions(prd);
|
|
162
|
-
const others = prd.openQuestions.filter((question) => !blocking.includes(question));
|
|
163
|
-
|
|
164
|
-
if (blocking.length > 0) {
|
|
165
|
-
items.push({
|
|
166
|
-
id: 'blocking-questions',
|
|
167
|
-
section: 'openQuestions',
|
|
168
|
-
message: `${blocking.length} open questions block stories; answer them before those stories are built`,
|
|
169
|
-
severity: 'required',
|
|
170
|
-
storyIds: [...new Set(blocking.flatMap((question) => question.storyIds ?? []))],
|
|
171
|
-
});
|
|
172
|
-
}
|
|
173
|
-
|
|
174
|
-
if (others.length > 0) {
|
|
175
|
-
items.push({
|
|
176
|
-
id: 'open-questions',
|
|
177
|
-
section: 'openQuestions',
|
|
178
|
-
message: `${others.length} open questions remain unresolved`,
|
|
179
|
-
severity: 'recommended',
|
|
180
|
-
});
|
|
181
|
-
}
|
|
182
|
-
|
|
183
|
-
if (prd.measurementPlan.targetMetrics.length === 0) {
|
|
184
|
-
items.push({
|
|
185
|
-
id: 'target-metrics',
|
|
186
|
-
section: 'measurementPlan',
|
|
187
|
-
message:
|
|
188
|
-
'Define target metrics in measurementPlan to validate delivery impact',
|
|
189
|
-
severity: 'recommended',
|
|
190
|
-
});
|
|
191
|
-
}
|
|
192
|
-
|
|
193
|
-
if (prd.rolloutPlan.rolloutPhases.length === 0) {
|
|
194
|
-
items.push({
|
|
195
|
-
id: 'rollout',
|
|
196
|
-
section: 'rolloutPlan',
|
|
197
|
-
message: 'Add rollout phases and rollback conditions',
|
|
198
|
-
severity: 'recommended',
|
|
199
|
-
});
|
|
200
|
-
}
|
|
201
|
-
|
|
202
|
-
if (stories.length > 0 && prd.technicalContracts.dataModels.length === 0) {
|
|
203
|
-
items.push({
|
|
204
|
-
id: 'data-models',
|
|
205
|
-
section: 'technicalContracts',
|
|
206
|
-
message:
|
|
207
|
-
'Describe the main entities and how they relate in technicalContracts.dataModels',
|
|
208
|
-
severity: 'recommended',
|
|
209
|
-
});
|
|
210
|
-
}
|
|
211
|
-
|
|
212
|
-
// Stories with no criteria are already reported as required.
|
|
213
|
-
const vague = stories.filter(
|
|
214
|
-
(story) =>
|
|
215
|
-
story.acceptanceCriteria.length > 0 &&
|
|
216
|
-
story.acceptanceCriteria.length < 2,
|
|
217
|
-
);
|
|
218
|
-
|
|
219
|
-
if (vague.length > 0) {
|
|
220
|
-
items.push({
|
|
221
|
-
id: 'vague-stories',
|
|
222
|
-
section: 'userStories',
|
|
223
|
-
message: `${vague.length} stories need more detailed acceptance criteria`,
|
|
224
|
-
severity: 'recommended',
|
|
225
|
-
storyIds: vague.map((story) => story.id),
|
|
226
|
-
});
|
|
227
|
-
}
|
|
228
|
-
|
|
229
|
-
const withoutSeams = stories.filter(
|
|
230
|
-
(story) => story.status !== 'completed' && !story.testSeams?.length,
|
|
231
|
-
);
|
|
232
|
-
|
|
233
|
-
if (withoutSeams.length > 0) {
|
|
234
|
-
items.push({
|
|
235
|
-
id: 'test-seams',
|
|
236
|
-
section: 'userStories',
|
|
237
|
-
message: `${withoutSeams.length} stories do not say where they are tested (testSeams)`,
|
|
238
|
-
severity: 'recommended',
|
|
239
|
-
storyIds: withoutSeams.map((story) => story.id),
|
|
240
|
-
});
|
|
241
|
-
}
|
|
242
|
-
|
|
243
|
-
const phased = new Set(
|
|
244
|
-
prd.customPhases.flatMap((phase) => phase.userStoryIds),
|
|
245
|
-
);
|
|
246
|
-
const unphased = stories.filter((story) => !phased.has(story.id));
|
|
247
|
-
|
|
248
|
-
if (stories.length > PHASE_THRESHOLD && unphased.length > 0) {
|
|
249
|
-
items.push({
|
|
250
|
-
id: 'phases',
|
|
251
|
-
section: 'customPhases',
|
|
252
|
-
message: `${unphased.length} stories are not in a phase; group them into phases in build order`,
|
|
253
|
-
severity: 'recommended',
|
|
254
|
-
storyIds: unphased.map((story) => story.id),
|
|
255
|
-
});
|
|
256
|
-
}
|
|
257
|
-
|
|
258
|
-
const blocked = stories.filter((story) => story.status === 'blocked');
|
|
259
|
-
|
|
260
|
-
if (blocked.length > 0) {
|
|
261
|
-
items.push({
|
|
262
|
-
id: 'blocked-stories',
|
|
263
|
-
section: 'userStories',
|
|
264
|
-
message: `${blocked.length} stories are blocked and need attention`,
|
|
265
|
-
severity: 'recommended',
|
|
266
|
-
storyIds: blocked.map((story) => story.id),
|
|
267
|
-
});
|
|
268
|
-
}
|
|
269
|
-
|
|
270
|
-
// Parts marked not applicable are not asked for. Open edge cases still
|
|
271
|
-
// count: they were written down, so they need an answer.
|
|
272
|
-
const applicable = items.filter((item) => {
|
|
273
|
-
const topic = CHECK_TOPICS[item.id];
|
|
274
|
-
|
|
275
|
-
return !topic || !isNotApplicable(prd, topic);
|
|
276
|
-
});
|
|
277
|
-
|
|
278
|
-
return {
|
|
279
|
-
ready_to_build: !applicable.some((item) => item.severity === 'required'),
|
|
280
|
-
items: applicable,
|
|
281
|
-
};
|
|
282
|
-
}
|