@besales/ops-framework 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.9
+
+- Added `--phase` and `--include` filters to initiative intake/requirements flows.
+- Added `requirements-review.md` human approval cards for requirement candidates.
+- Added phase metadata to extracted requirement candidates and requirements map rows.
+
 ## 0.1.8
 
 - Added `initiative-intake` for source-doc indexing, source SHA tracking and deterministic requirement candidates.

package/README.md

@@ -232,8 +232,8 @@ Initiatives are the program-level layer above tasks. Use them for MVPs, large fe
 ```bash
 ops-agent initiative-create delivery-os-mvp --title "Delivery OS MVP" --mode fast_mvp
 ops-agent initiative-add-work-package delivery-os-mvp WP-001-foundation --title "Foundation"
-ops-agent initiative-intake delivery-os-mvp docs/delivery-os
-ops-agent initiative-requirements delivery-os-mvp
+ops-agent initiative-intake delivery-os-mvp docs/delivery-os --phase phase-1 --include "06-roadmap.md,04-data-model.md,11-tooling-and-data-flows.md"
+ops-agent initiative-requirements delivery-os-mvp --phase phase-1
 ops-agent initiative-status delivery-os-mvp
 ops-agent initiative-next delivery-os-mvp --materialize-task
 ```
@@ -258,7 +258,9 @@ Raw docs
  -> tasks
 ```
 
-`initiative-intake <initiative> <docs-dir>` indexes supported source documents, writes source SHA hashes and deterministic requirement candidates into `intake/`. `initiative-requirements <initiative>` turns those candidates into `REQ-*` rows in `requirements-map.md` and writes `coverage.md`. Human review is still required before treating candidates as approved or planned.
+`initiative-intake <initiative> <docs-dir>` indexes supported source documents, writes source SHA hashes and deterministic requirement candidates into `intake/`. Use `--include "file-a.md,file-b.md"` to restrict the first pass to the most relevant source files, and `--phase phase-1` to keep candidates whose local heading/source context matches the target phase.
+
+`initiative-requirements <initiative>` turns those candidates into `REQ-*` rows in `requirements-map.md`, writes `requirements-review.md` approval cards and writes `coverage.md`. Human review is still required before treating candidates as approved or planned.
 
 ## Feedback Intake
 

package/bin/initiative.mjs

@@ -70,6 +70,8 @@ export function main() {
         projectRoot: process.cwd(),
         initiativeId: args.positional[0],
         docsDir: args.positional[1],
+        phase: normalizePhaseFilter(getFlag(args, 'phase', null)),
+        include: parseIncludeFilter(getFlag(args, 'include', null)),
         force: args.flags.has('force'),
       });
       printChangeSummary(`Initiative intake written: ${result.initiativeId}`, result.changes);
@@ -81,6 +83,7 @@ export function main() {
       const result = initiativeRequirements({
         projectRoot: process.cwd(),
         initiativeId: args.positional[0],
+        phase: normalizePhaseFilter(getFlag(args, 'phase', null)),
         force: args.flags.has('force'),
       });
       printChangeSummary(`Initiative requirements map written: ${result.initiativeId}`, result.changes);
@@ -221,6 +224,8 @@ export function initiativeIntake({
   projectRoot = process.cwd(),
   initiativeId,
   docsDir,
+  phase = null,
+  include = [],
   force = false,
 } = {}) {
   const initiative = readInitiative({ projectRoot, initiativeId });
@@ -234,12 +239,14 @@ export function initiativeIntake({
   const intakeDir = path.join(initiative.initiativeDir, 'intake');
   const changes = [];
   ensureDirectory(intakeDir, changes);
-  const sources = collectSourceDocuments({ projectRoot, docsDir: absoluteDocsDir });
-  const candidates = collectRequirementCandidates({ projectRoot, sources });
+  const sources = collectSourceDocuments({ projectRoot, docsDir: absoluteDocsDir, include });
+  const candidates = collectRequirementCandidates({ projectRoot, sources, phase });
   writeFileIfAllowed(path.join(intakeDir, 'source-index.json'), JSON.stringify({
     schemaVersion: 1,
     generatedAt: new Date().toISOString(),
     docsDir: path.relative(projectRoot, absoluteDocsDir),
+    phaseFilter: phase,
+    include,
     sources,
   }, null, 2), { force: true, changes });
   writeFileIfAllowed(path.join(intakeDir, 'sources.md'), renderSourcesMarkdown({ docsDir: absoluteDocsDir, projectRoot, sources }), { force, changes });
@@ -258,6 +265,7 @@ export function initiativeIntake({
 export function initiativeRequirements({
   projectRoot = process.cwd(),
   initiativeId,
+  phase = null,
   force = false,
 } = {}) {
   const initiative = readInitiative({ projectRoot, initiativeId });
@@ -265,19 +273,24 @@ export function initiativeRequirements({
   if (!fs.existsSync(candidatesPath)) {
     throw new Error('Missing intake/extracted-requirements.md. Run initiative-intake first.');
   }
-  const candidates = parseRequirementCandidates(fs.readFileSync(candidatesPath, 'utf8'));
+  const candidates = parseRequirementCandidates(fs.readFileSync(candidatesPath, 'utf8'))
+    .filter((candidate) => !phase || candidate.phase === phase);
   const requirements = candidates.map((candidate, index) => ({
     id: `REQ-${String(index + 1).padStart(3, '0')}`,
     status: 'candidate',
     title: summarizeRequirementTitle(candidate.text),
     source: candidate.source,
     sourceHash: candidate.sourceHash,
+    phase: candidate.phase || 'unknown',
     text: candidate.text,
     workPackage: '',
     acceptance: '',
+    decision: 'pending',
+    notes: '',
   }));
   const changes = [];
   writeFileIfAllowed(path.join(initiative.initiativeDir, 'requirements-map.md'), renderRequirementsMap(requirements), { force: true, changes });
+  writeFileIfAllowed(path.join(initiative.initiativeDir, 'requirements-review.md'), renderRequirementsReview(requirements), { force: true, changes });
   writeFileIfAllowed(path.join(initiative.initiativeDir, 'coverage.md'), renderCoverage({ requirements }), { force, changes });
   return {
     initiativeId,
@@ -310,11 +323,12 @@ function materializeWorkPackageTask({ projectRoot, initiativeId, workPackage, ta
   return task;
 }
 
-function collectSourceDocuments({ projectRoot, docsDir }) {
+function collectSourceDocuments({ projectRoot, docsDir, include = [] }) {
   const files = [];
   walkDocs(docsDir, files);
   return files
     .sort()
+    .filter((filePath) => sourceIncluded({ projectRoot, filePath, include }))
     .map((filePath) => {
       const content = fs.readFileSync(filePath, 'utf8');
       return {
@@ -342,17 +356,26 @@ function walkDocs(directory, files) {
   }
 }
 
-function collectRequirementCandidates({ projectRoot, sources }) {
+function collectRequirementCandidates({ projectRoot, sources, phase = null }) {
   const candidates = [];
   const seen = new Set();
   for (const source of sources) {
     const sourcePath = path.join(projectRoot, source.path);
     const lines = fs.readFileSync(sourcePath, 'utf8').split(/\r?\n/);
+    let headingContext = '';
     lines.forEach((line, index) => {
+      const heading = /^#{1,6}\s+(.+)$/.exec(line);
+      if (heading) {
+        headingContext = heading[1].trim();
+      }
       const normalized = normalizeRequirementCandidate(line);
       if (!isRequirementCandidate(normalized)) {
         return;
       }
+      const candidatePhase = inferPhase(`${source.path} ${headingContext} ${normalized}`);
+      if (phase && candidatePhase !== phase) {
+        return;
+      }
       const key = sha256(`${source.path}:${normalized}`).slice(0, 16);
       if (seen.has(key)) {
         return;
@@ -362,6 +385,7 @@ function collectRequirementCandidates({ projectRoot, sources }) {
         id: `RC-${String(candidates.length + 1).padStart(3, '0')}`,
         source: `${source.path}:${index + 1}`,
         sourceHash: source.sha256,
+        phase: candidatePhase,
         text: normalized,
       });
     });
@@ -369,6 +393,14 @@ function collectRequirementCandidates({ projectRoot, sources }) {
   return candidates;
 }
 
+function sourceIncluded({ projectRoot, filePath, include }) {
+  if (!include.length) {
+    return true;
+  }
+  const relative = path.relative(projectRoot, filePath);
+  return include.some((pattern) => relative === pattern || relative.endsWith(pattern) || relative.includes(pattern));
+}
+
 function normalizeRequirementCandidate(line) {
   return line
     .replace(/^#{1,6}\s+/, '')
@@ -409,6 +441,7 @@ function renderRequirementCandidatesMarkdown(candidates) {
       '',
       `- Source: \`${candidate.source}\``,
       `- Source hash: \`${candidate.sourceHash}\``,
+      `- Phase: \`${candidate.phase || 'unknown'}\``,
       `- Candidate: ${candidate.text}`,
       '',
     ].join('\n')),
@@ -423,6 +456,7 @@ function parseRequirementCandidates(content) {
       id: rawId.trim(),
       source: readMarkdownListField(body, 'Source'),
       sourceHash: readMarkdownListField(body, 'Source hash'),
+      phase: readMarkdownListField(body, 'Phase') || 'unknown',
       text: readMarkdownListField(body, 'Candidate'),
     };
   }).filter((candidate) => candidate.id && candidate.source && candidate.text);
@@ -434,9 +468,9 @@ function renderRequirementsMap(requirements) {
     '',
     'Statuses: `candidate | approved | planned | implemented | rejected`.',
     '',
-    '| ID | Status | Requirement | Source | Work package | Acceptance |',
-    '| --- | --- | --- | --- | --- | --- |',
-    ...requirements.map((req) => `| ${req.id} | ${req.status} | ${escapeTable(req.title)} | \`${req.source}\` | ${req.workPackage || ''} | ${req.acceptance || ''} |`),
+    '| ID | Status | Phase | Requirement | Source | Work package | Acceptance |',
+    '| --- | --- | --- | --- | --- | --- | --- |',
+    ...requirements.map((req) => `| ${req.id} | ${req.status} | ${req.phase || 'unknown'} | ${escapeTable(req.title)} | \`${req.source}\` | ${req.workPackage || ''} | ${req.acceptance || ''} |`),
     '',
     '## Requirement Details',
     '',
@@ -446,14 +480,46 @@ function renderRequirementsMap(requirements) {
       `- Status: \`${req.status}\``,
       `- Source: \`${req.source}\``,
       `- Source hash: \`${req.sourceHash}\``,
+      `- Phase: \`${req.phase || 'unknown'}\``,
       `- Work package: ${req.workPackage || '(unassigned)'}`,
       `- Acceptance: ${req.acceptance || '(fill before implementation)'}`,
+      `- Decision: \`${req.decision || 'pending'}\``,
+      `- Notes: ${req.notes || '(empty)'}`,
       `- Requirement: ${req.text}`,
       '',
     ].join('\n')),
   ].join('\n');
 }
 
+function renderRequirementsReview(requirements) {
+  return [
+    '# Requirements Review',
+    '',
+    'Human approval pack. Review each requirement before planning work packages.',
+    '',
+    'Allowed decisions: `approve | defer | reject | rewrite`.',
+    '',
+    '## Pending Requirement Decisions',
+    '',
+    ...requirements.map((req) => [
+      `### ${req.id}: ${req.title}`,
+      '',
+      `- Source: \`${req.source}\``,
+      `- Source hash: \`${req.sourceHash}\``,
+      `- Phase: \`${req.phase || 'unknown'}\``,
+      `- Suggested status: \`${req.status}\``,
+      `- Requirement: ${req.text}`,
+      `- Proposed work package: ${req.workPackage || '(unassigned)'}`,
+      `- Acceptance: ${req.acceptance || '(fill before implementation)'}`,
+      `- Decision: \`${req.decision || 'pending'}\``,
+      `- Human notes: ${req.notes || '(empty)'}`,
+      '',
+      'Decision to set in `requirements-map.md`: `approve | defer | reject | rewrite`',
+      '',
+    ].join('\n')),
+  ].join('\n');
+}
+
 function renderCoverage({ requirements }) {
   const counts = countBy(requirements, (req) => req.status || 'candidate');
   return [
@@ -474,6 +540,39 @@ function renderCoverage({ requirements }) {
   ].join('\n');
 }
 
+function parseIncludeFilter(value) {
+  if (!value) {
+    return [];
+  }
+  return String(value).split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+function normalizePhaseFilter(value) {
+  if (!value) {
+    return null;
+  }
+  return normalizePhaseLabel(value);
+}
+
+function inferPhase(text) {
+  return normalizePhaseLabel(text) || 'unknown';
+}
+
+function normalizePhaseLabel(text) {
+  const value = String(text || '').toLowerCase();
+  if (/future|later|deferred|not in phase 1|не делаем|отложен/.test(value)) {
+    return 'future';
+  }
+  const match = /phase\s*[- ]?(\d+)|фаз[аы]\s*[- ]?(\d+)/i.exec(value);
+  if (match) {
+    return `phase-${match[1] || match[2]}`;
+  }
+  if (/\bmvp\b|meeting loop/.test(value)) {
+    return 'phase-1';
+  }
+  return null;
+}
+
 function buildOpenQuestionsMarkdown() {
   return [
     '# Open Questions',

package/bin/initiative.test.mjs

@@ -112,6 +112,51 @@ describe('initiative framework', () => {
     expect(requirementsMap).toContain('REQ-001');
     expect(requirementsMap).toContain('User must create delivery orders');
     expect(requirementsMap).toContain('REQ-002');
+    expect(requirementsMap).toContain('| REQ-001 | candidate | phase-1 |');
+    const review = fs.readFileSync(path.join(initiativeDir, 'requirements-review.md'), 'utf8');
+    expect(review).toContain('### REQ-001: User must create delivery orders from the admin UI.');
+    expect(review).toContain('Decision to set in `requirements-map.md`: `approve | defer | reject | rewrite`');
+  });
+
+  it('filters source docs and requirements by include and phase', () => {
+    const root = makeProject();
+    const docsDir = path.join(root, 'docs', 'delivery-os');
+    fs.mkdirSync(docsDir, { recursive: true });
+    fs.writeFileSync(path.join(docsDir, 'phase1.md'), [
+      '# Phase 1',
+      '',
+      '- System must import meeting transcripts.',
+    ].join('\n'));
+    fs.writeFileSync(path.join(docsDir, 'future.md'), [
+      '# Phase 3',
+      '',
+      '- System must send Telegram digests.',
+    ].join('\n'));
+    createInitiative({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      title: 'Delivery OS MVP',
+    });
+
+    const intake = initiativeIntake({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      docsDir: 'docs/delivery-os',
+      phase: 'phase-1',
+      include: ['phase1.md'],
+    });
+    const requirements = initiativeRequirements({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      phase: 'phase-1',
+    });
+
+    expect(intake.sources).toHaveLength(1);
+    expect(intake.sources[0].path).toBe('docs/delivery-os/phase1.md');
+    expect(intake.candidates).toHaveLength(1);
+    expect(intake.candidates[0].phase).toBe('phase-1');
+    expect(requirements.requirements).toHaveLength(1);
+    expect(requirements.requirements[0].text).toContain('meeting transcripts');
   });
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@besales/ops-framework",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "type": "module",
   "bin": {
     "ops-agent": "bin/ops-agent.mjs"