@besales/ops-framework 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.8
+
+- Added `initiative-intake` for source-doc indexing, source SHA tracking and deterministic requirement candidates.
+- Added `initiative-requirements` to create `requirements-map.md` and `coverage.md` from intake candidates.
+- Added generated project scripts for initiative intake and requirements mapping.
+
 ## 0.1.7
 
 - Added the first Initiative Framework layer above tasks for MVPs, large feature trains and multi-phase work.

package/README.md

@@ -184,6 +184,8 @@ Do not commit that `file:` dependency to production projects. It is only for pac
 - `initiative-add-work-package`
 - `initiative-status`
 - `initiative-next`
+- `initiative-intake`
+- `initiative-requirements`
 - `test/self-test`
 
 ## Learning Loop
@@ -230,6 +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-status delivery-os-mvp
 ops-agent initiative-next delivery-os-mvp --materialize-task
 ```
@@ -244,6 +248,18 @@ Initiative
 
 Work packages are materialized as normal tasks, so `brief/research/plan/check/execute/verify/retrospective/learning` still works at the audit boundary. Slices are not separate tasks; they use fast execution, micro-verify and slice evidence inside the work-package task. Create a separate task only when a slice triggers scope, risk, architecture or human-approval escalation.
 
+For source docs, use intake before work-package planning:
+
+```text
+Raw docs
+ -> initiative intake/source-index
+ -> requirements-map.md
+ -> work packages
+ -> 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.
+
 ## Feedback Intake
 
 Feedback is stage-agnostic. Any user question, correction, review note or learning observation during an active task should be captured before it is acted on:

package/bin/initiative.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import {
   getFlag,
@@ -14,6 +15,7 @@ import { resolveProjectContext } from './lib/project-config.mjs';
 
 const INITIATIVE_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const WORK_PACKAGE_ID_PATTERN = /^WP-\d{3}-[a-z0-9][a-z0-9-]*$/;
+const SUPPORTED_SOURCE_EXTENSIONS = new Set(['.md', '.markdown', '.txt', '.json', '.yaml', '.yml']);
 
 export function main() {
   const command = process.argv[2];
@@ -63,7 +65,29 @@ export function main() {
       printInitiativeNext(result);
       return;
     }
-    fail('Usage: ops-agent initiative-create|initiative-add-work-package|initiative-status|initiative-next ...');
+    if (command === 'initiative-intake') {
+      const result = initiativeIntake({
+        projectRoot: process.cwd(),
+        initiativeId: args.positional[0],
+        docsDir: args.positional[1],
+        force: args.flags.has('force'),
+      });
+      printChangeSummary(`Initiative intake written: ${result.initiativeId}`, result.changes);
+      console.log(`- sources: ${result.sources.length}`);
+      console.log(`- requirement candidates: ${result.candidates.length}`);
+      return;
+    }
+    if (command === 'initiative-requirements') {
+      const result = initiativeRequirements({
+        projectRoot: process.cwd(),
+        initiativeId: args.positional[0],
+        force: args.flags.has('force'),
+      });
+      printChangeSummary(`Initiative requirements map written: ${result.initiativeId}`, result.changes);
+      console.log(`- requirements: ${result.requirements.length}`);
+      return;
+    }
+    fail('Usage: ops-agent initiative-create|initiative-add-work-package|initiative-status|initiative-next|initiative-intake|initiative-requirements ...');
   } catch (error) {
     fail(error.message);
   }
@@ -193,6 +217,75 @@ export function initiativeNext({
   };
 }
 
+export function initiativeIntake({
+  projectRoot = process.cwd(),
+  initiativeId,
+  docsDir,
+  force = false,
+} = {}) {
+  const initiative = readInitiative({ projectRoot, initiativeId });
+  if (!docsDir) {
+    throw new Error('Usage: ops-agent initiative-intake <initiative> <docs-dir>');
+  }
+  const absoluteDocsDir = path.resolve(projectRoot, docsDir);
+  if (!fs.existsSync(absoluteDocsDir) || !fs.statSync(absoluteDocsDir).isDirectory()) {
+    throw new Error(`Docs directory not found: ${docsDir}`);
+  }
+  const intakeDir = path.join(initiative.initiativeDir, 'intake');
+  const changes = [];
+  ensureDirectory(intakeDir, changes);
+  const sources = collectSourceDocuments({ projectRoot, docsDir: absoluteDocsDir });
+  const candidates = collectRequirementCandidates({ projectRoot, sources });
+  writeFileIfAllowed(path.join(intakeDir, 'source-index.json'), JSON.stringify({
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    docsDir: path.relative(projectRoot, absoluteDocsDir),
+    sources,
+  }, null, 2), { force: true, changes });
+  writeFileIfAllowed(path.join(intakeDir, 'sources.md'), renderSourcesMarkdown({ docsDir: absoluteDocsDir, projectRoot, sources }), { force, changes });
+  writeFileIfAllowed(path.join(intakeDir, 'extracted-requirements.md'), renderRequirementCandidatesMarkdown(candidates), { force: true, changes });
+  writeFileIfAllowed(path.join(intakeDir, 'open-questions.md'), buildOpenQuestionsMarkdown(), { force, changes });
+  writeFileIfAllowed(path.join(intakeDir, 'assumptions.md'), buildAssumptionsMarkdown(), { force, changes });
+  return {
+    initiativeId,
+    intakeDir,
+    sources,
+    candidates,
+    changes,
+  };
+}
+
+export function initiativeRequirements({
+  projectRoot = process.cwd(),
+  initiativeId,
+  force = false,
+} = {}) {
+  const initiative = readInitiative({ projectRoot, initiativeId });
+  const candidatesPath = path.join(initiative.initiativeDir, 'intake', 'extracted-requirements.md');
+  if (!fs.existsSync(candidatesPath)) {
+    throw new Error('Missing intake/extracted-requirements.md. Run initiative-intake first.');
+  }
+  const candidates = parseRequirementCandidates(fs.readFileSync(candidatesPath, 'utf8'));
+  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,
+    text: candidate.text,
+    workPackage: '',
+    acceptance: '',
+  }));
+  const changes = [];
+  writeFileIfAllowed(path.join(initiative.initiativeDir, 'requirements-map.md'), renderRequirementsMap(requirements), { force: true, changes });
+  writeFileIfAllowed(path.join(initiative.initiativeDir, 'coverage.md'), renderCoverage({ requirements }), { force, changes });
+  return {
+    initiativeId,
+    requirements,
+    changes,
+  };
+}
+
 function materializeWorkPackageTask({ projectRoot, initiativeId, workPackage, taskId, force }) {
   const task = createTask({
     projectRoot,
@@ -217,6 +310,188 @@ function materializeWorkPackageTask({ projectRoot, initiativeId, workPackage, ta
   return task;
 }
 
+function collectSourceDocuments({ projectRoot, docsDir }) {
+  const files = [];
+  walkDocs(docsDir, files);
+  return files
+    .sort()
+    .map((filePath) => {
+      const content = fs.readFileSync(filePath, 'utf8');
+      return {
+        path: path.relative(projectRoot, filePath),
+        bytes: Buffer.byteLength(content),
+        sha256: sha256(content),
+        title: inferSourceTitle(content, filePath),
+      };
+    });
+}
+
+function walkDocs(directory, files) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+      continue;
+    }
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      walkDocs(entryPath, files);
+      continue;
+    }
+    if (entry.isFile() && SUPPORTED_SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+      files.push(entryPath);
+    }
+  }
+}
+
+function collectRequirementCandidates({ projectRoot, sources }) {
+  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/);
+    lines.forEach((line, index) => {
+      const normalized = normalizeRequirementCandidate(line);
+      if (!isRequirementCandidate(normalized)) {
+        return;
+      }
+      const key = sha256(`${source.path}:${normalized}`).slice(0, 16);
+      if (seen.has(key)) {
+        return;
+      }
+      seen.add(key);
+      candidates.push({
+        id: `RC-${String(candidates.length + 1).padStart(3, '0')}`,
+        source: `${source.path}:${index + 1}`,
+        sourceHash: source.sha256,
+        text: normalized,
+      });
+    });
+  }
+  return candidates;
+}
+
+function normalizeRequirementCandidate(line) {
+  return line
+    .replace(/^#{1,6}\s+/, '')
+    .replace(/^[-*]\s+/, '')
+    .replace(/^\d+[.)]\s+/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function isRequirementCandidate(text) {
+  if (text.length < 20 || text.length > 500) {
+    return false;
+  }
+  return /(must|should|required|requirement|user can|user must|system must|needs to|нужно|должен|должна|должны|требован|пользователь может|пользователь должен|система должна|необходимо|важно)/i.test(text);
+}
+
+function renderSourcesMarkdown({ docsDir, projectRoot, sources }) {
+  return [
+    '# Initiative Sources',
+    '',
+    `Docs directory: \`${path.relative(projectRoot, docsDir)}\``,
+    '',
+    '| Source | Title | SHA-256 | Bytes |',
+    '| --- | --- | --- | --- |',
+    ...sources.map((source) => `| \`${source.path}\` | ${escapeTable(source.title)} | \`${source.sha256}\` | ${source.bytes} |`),
+    '',
+  ].join('\n');
+}
+
+function renderRequirementCandidatesMarkdown(candidates) {
+  return [
+    '# Extracted Requirement Candidates',
+    '',
+    'These are deterministic candidates from source docs. Human review is required before planning work packages.',
+    '',
+    ...candidates.map((candidate) => [
+      `## ${candidate.id}`,
+      '',
+      `- Source: \`${candidate.source}\``,
+      `- Source hash: \`${candidate.sourceHash}\``,
+      `- Candidate: ${candidate.text}`,
+      '',
+    ].join('\n')),
+  ].join('\n');
+}
+
+function parseRequirementCandidates(content) {
+  return content.split(/^##\s+/m).slice(1).map((section) => {
+    const [rawId, ...bodyLines] = section.split('\n');
+    const body = bodyLines.join('\n');
+    return {
+      id: rawId.trim(),
+      source: readMarkdownListField(body, 'Source'),
+      sourceHash: readMarkdownListField(body, 'Source hash'),
+      text: readMarkdownListField(body, 'Candidate'),
+    };
+  }).filter((candidate) => candidate.id && candidate.source && candidate.text);
+}
+
+function renderRequirementsMap(requirements) {
+  return [
+    '# Requirements Map',
+    '',
+    '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 || ''} |`),
+    '',
+    '## Requirement Details',
+    '',
+    ...requirements.map((req) => [
+      `### ${req.id}`,
+      '',
+      `- Status: \`${req.status}\``,
+      `- Source: \`${req.source}\``,
+      `- Source hash: \`${req.sourceHash}\``,
+      `- Work package: ${req.workPackage || '(unassigned)'}`,
+      `- Acceptance: ${req.acceptance || '(fill before implementation)'}`,
+      `- Requirement: ${req.text}`,
+      '',
+    ].join('\n')),
+  ].join('\n');
+}
+
+function renderCoverage({ requirements }) {
+  const counts = countBy(requirements, (req) => req.status || 'candidate');
+  return [
+    '# Initiative Coverage',
+    '',
+    `- Total requirements: ${requirements.length}`,
+    `- Candidate: ${counts.candidate || 0}`,
+    `- Approved: ${counts.approved || 0}`,
+    `- Planned: ${counts.planned || 0}`,
+    `- Implemented: ${counts.implemented || 0}`,
+    `- Rejected: ${counts.rejected || 0}`,
+    '',
+    '## Unassigned Requirements',
+    '',
+    ...requirements.filter((req) => !req.workPackage).map((req) => `- ${req.id}: ${req.title}`),
+    ...(requirements.some((req) => !req.workPackage) ? [] : ['- None.']),
+    '',
+  ].join('\n');
+}
+
+function buildOpenQuestionsMarkdown() {
+  return [
+    '# Open Questions',
+    '',
+    '- Add human decisions discovered during initiative intake.',
+    '',
+  ].join('\n');
+}
+
+function buildAssumptionsMarkdown() {
+  return [
+    '# Assumptions',
+    '',
+    '- Add assumptions that were required to interpret source docs.',
+    '',
+  ].join('\n');
+}
+
 function readInitiative({ projectRoot, initiativeId }) {
   assertInitiativeId(initiativeId);
   const context = resolveProjectContext({ cwd: projectRoot });
@@ -407,6 +682,11 @@ function readInlineField(content, field) {
   return match ? match[1].trim() : '';
 }
 
+function readMarkdownListField(content, field) {
+  const match = new RegExp(`^- ${escapeRegExp(field)}:\\s*(.*)$`, 'm').exec(content);
+  return match ? match[1].replace(/^`|`$/g, '').trim() : '';
+}
+
 function readSection(content, heading) {
   const match = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*\\n([\\s\\S]*?)(?=^##\\s+|\\s*$)`, 'm').exec(content);
   return match ? match[1].trim() : '';
@@ -516,6 +796,19 @@ function escapeTable(value) {
   return String(value).replace(/\|/g, '\\|');
 }
 
+function inferSourceTitle(content, filePath) {
+  const heading = /^#\s+(.+)$/m.exec(content);
+  return heading ? heading[1].trim() : path.basename(filePath);
+}
+
+function summarizeRequirementTitle(text) {
+  return text.length > 120 ? `${text.slice(0, 117)}...` : text;
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/bin/initiative.test.mjs

@@ -5,7 +5,9 @@ import { describe, expect, it } from 'vitest';
 import {
   addWorkPackage,
   createInitiative,
+  initiativeIntake,
   initiativeNext,
+  initiativeRequirements,
   initiativeStatus,
 } from './initiative.mjs';
 
@@ -72,6 +74,45 @@ describe('initiative framework', () => {
     expect(workPackage).toContain('Status: in_progress');
     expect(workPackage).toContain('Task: TASK-001-foundation');
   });
+
+  it('indexes source docs and builds a requirements map', () => {
+    const root = makeProject();
+    const docsDir = path.join(root, 'docs', 'delivery-os');
+    fs.mkdirSync(docsDir, { recursive: true });
+    fs.writeFileSync(path.join(docsDir, 'mvp.md'), [
+      '# Delivery OS MVP',
+      '',
+      '- User must create delivery orders from the admin UI.',
+      '- Система должна показывать статус доставки оператору.',
+      '- Nice prose for background context only.',
+    ].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',
+    });
+    const requirements = initiativeRequirements({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+    });
+
+    expect(intake.sources).toHaveLength(1);
+    expect(intake.candidates).toHaveLength(2);
+    expect(requirements.requirements).toHaveLength(2);
+    const initiativeDir = path.join(root, 'ops', 'agent-pipeline', 'initiatives', 'delivery-os-mvp');
+    const sourceIndex = JSON.parse(fs.readFileSync(path.join(initiativeDir, 'intake', 'source-index.json'), 'utf8'));
+    const requirementsMap = fs.readFileSync(path.join(initiativeDir, 'requirements-map.md'), 'utf8');
+    expect(sourceIndex.sources[0].path).toBe('docs/delivery-os/mvp.md');
+    expect(requirementsMap).toContain('REQ-001');
+    expect(requirementsMap).toContain('User must create delivery orders');
+    expect(requirementsMap).toContain('REQ-002');
+  });
 });
 
 function makeProject() {

package/bin/lib/bootstrap-utils.mjs

@@ -125,6 +125,8 @@ export function buildOpsScripts(packageSpec) {
     'agent:initiative-add-work-package': run('initiative-add-work-package'),
     'agent:initiative-status': run('initiative-status'),
     'agent:initiative-next': run('initiative-next'),
+    'agent:initiative-intake': run('initiative-intake'),
+    'agent:initiative-requirements': run('initiative-requirements'),
     'agent:test': run('test/self-test'),
   };
 }

package/bin/lib/bootstrap-utils.test.mjs

@@ -142,6 +142,8 @@ describe('buildOpsScripts', () => {
     expect(scripts['agent:closeout']).toBe('ops-agent closeout');
     expect(scripts['agent:initiative-create']).toBe('ops-agent initiative-create');
     expect(scripts['agent:initiative-next']).toBe('ops-agent initiative-next');
+    expect(scripts['agent:initiative-intake']).toBe('ops-agent initiative-intake');
+    expect(scripts['agent:initiative-requirements']).toBe('ops-agent initiative-requirements');
     expect(scripts['agent:test']).toBe('ops-agent test/self-test');
   });
 });

package/bin/ops-agent.mjs

@@ -38,6 +38,8 @@ const COMMANDS = new Map([
   ['initiative-add-work-package', 'initiative.mjs'],
   ['initiative-status', 'initiative.mjs'],
   ['initiative-next', 'initiative.mjs'],
+  ['initiative-intake', 'initiative.mjs'],
+  ['initiative-requirements', 'initiative.mjs'],
   ['test/self-test', null],
 ]);
 

package/package.json

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