@minionry/minion 0.7.36

package/dist/server/services/plan/progress-log.js

@@ -0,0 +1,101 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { validateIssuePath } from './issue-writer.js';
+export async function ensureOutputDirs(pmDir, boardDir) {
+    if (boardDir) {
+        const boardOutDir = join(boardDir, 'out');
+        if (!existsSync(boardOutDir))
+            await mkdir(boardOutDir, { recursive: true });
+        return;
+    }
+    if (pmDir) {
+        const outDir = join(pmDir, 'out');
+        if (!existsSync(outDir))
+            await mkdir(outDir, { recursive: true });
+    }
+}
+export async function appendProgressEntry(pmDir, boardDir, issues, waveStart, warn, browserActivity) {
+    if (!pmDir)
+        return;
+    const progressPath = boardDir ? join(boardDir, 'progress.md') : join(pmDir, 'progress.md');
+    const durationMin = Math.round((Date.now() - waveStart) / 60_000);
+    const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 16);
+    const { completed, failed } = await partitionByOnDiskStatus(pmDir, issues);
+    const lines = [
+        '',
+        `## ${timestamp} — Wave [${issues.map(i => i.id).join(', ')}]`,
+        '',
+        `- **Duration**: ${durationMin} min`,
+        `- **Completed**: ${completed.length}/${issues.length}${completed.length > 0 ? ` (${completed.join(', ')})` : ''}`,
+    ];
+    if (failed.length > 0) {
+        lines.push(`- **Failed**: ${failed.join(', ')}`);
+    }
+    lines.push(...renderBrowserActivitySection(issues, browserActivity));
+    lines.push('');
+    await writeProgressLines(progressPath, lines, warn);
+}
+function renderBrowserActivitySection(issues, browserActivity) {
+    if (!browserActivity || browserActivity.size === 0)
+        return [];
+    const out = [];
+    let any = false;
+    for (const issue of issues) {
+        const entry = browserActivity.get(issue.id);
+        if (!entry || entry.calls === 0)
+            continue;
+        if (!any) {
+            out.push('', '### Browser activity', '');
+            any = true;
+        }
+        const toolList = entry.tools.slice(0, 8).join(', ');
+        const truncated = entry.tools.length > 8 ? `, +${entry.tools.length - 8} more` : '';
+        out.push(`- **${issue.id}** — ${entry.calls} call(s): ${toolList}${truncated}`);
+        if (entry.finalUrl) {
+            out.push(`  - Final URL: ${entry.finalUrl}`);
+        }
+        out.push('  - Screenshot: see latest frame in BrowserView');
+    }
+    return out;
+}
+export async function appendProgressNote(pmDir, boardDir, note, warn) {
+    if (!pmDir)
+        return;
+    const progressPath = boardDir ? join(boardDir, 'progress.md') : join(pmDir, 'progress.md');
+    const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 16);
+    await writeProgressLines(progressPath, ['', `- ${timestamp} — ${note}`, ''], warn);
+}
+async function partitionByOnDiskStatus(pmDir, issues) {
+    const completed = [];
+    const failed = [];
+    for (const issue of issues) {
+        try {
+            const content = await readFile(validateIssuePath(issue.path, pmDir), 'utf-8');
+            const statusMatch = content.match(/^status:\s*(\S+)/m);
+            if (statusMatch?.[1] === 'done')
+                completed.push(issue.id);
+            else
+                failed.push(issue.id);
+        }
+        catch {
+            failed.push(issue.id);
+        }
+    }
+    return { completed, failed };
+}
+async function writeProgressLines(filePath, lines, warn) {
+    try {
+        if (existsSync(filePath)) {
+            await appendFile(filePath, `\n${lines.join('\n')}`, 'utf-8');
+        }
+        else {
+            await writeFile(filePath, `# Board Progress\n${lines.join('\n')}`, 'utf-8');
+        }
+    }
+    catch (err) {
+        warn(`Warning: failed to write progress log: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/server/services/plan/prompt-builder.js

@@ -0,0 +1,142 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { join } from 'node:path';
+import { specsDirOrDefault } from '../space-layout.js';
+export function buildCoordinatorPrompt(options) {
+    const { issues, workingDir, pmDir, boardDir, existingDocs, resolveOutputPath } = options;
+    const outDir = resolveOutDir(workingDir, pmDir, boardDir);
+    const teamName = `pm-wave-${Date.now()}`;
+    const issueBlocks = issues.map(issue => buildIssueBlock(issue, existingDocs, resolveOutputPath)).join('\n\n---\n\n');
+    const teammateSpawns = issues.map(issue => buildTeammateSpawn(issue, teamName, pmDir, existingDocs, resolveOutputPath)).join('\n\n');
+    return assembleCoordinatorPrompt({ issues, workingDir, pmDir, outDir, teamName, issueBlocks, teammateSpawns });
+}
+function resolveOutDir(workingDir, pmDir, boardDir) {
+    if (boardDir)
+        return join(boardDir, 'out');
+    if (pmDir)
+        return join(pmDir, 'out');
+    return join(specsDirOrDefault(workingDir), 'out');
+}
+function buildIssueBlock(issue, existingDocs, resolveOutputPath) {
+    const criteria = issue.acceptanceCriteria
+        .map(c => `- [${c.checked ? 'x' : ' '}] ${c.text}`)
+        .join('\n');
+    const files = issue.filesToModify.length > 0
+        ? `\nFiles to modify:\n${issue.filesToModify.map(f => `- ${f}`).join('\n')}`
+        : '';
+    const predecessorDocs = resolvePredecessorDocs(issue, existingDocs);
+    const predecessorSection = predecessorDocs.length > 0
+        ? `\nPredecessor outputs to read:\n${predecessorDocs.map(d => `- ${d}`).join('\n')}`
+        : '';
+    return `### ${issue.id}: ${issue.title}
+
+**Type**: ${issue.type} | **Priority**: ${issue.priority} | **Estimate**: ${issue.estimate ?? 'unestimated'}
+
+**Description**:
+${issue.description}
+
+**Acceptance Criteria**:
+${criteria || 'No specific criteria defined.'}
+
+**Technical Notes**:
+${issue.technicalNotes || 'None'}
+${files}${predecessorSection}
+
+**Output file**: ${resolveOutputPath(issue)}`;
+}
+function buildTeammateSpawn(issue, teamName, pmDir, existingDocs, resolveOutputPath) {
+    const predecessorDocs = resolvePredecessorDocs(issue, existingDocs);
+    const predInstr = predecessorDocs.length > 0
+        ? `Read these predecessor output docs before starting: ${predecessorDocs.join(', ')}. `
+        : '';
+    const outputFile = resolveOutputPath(issue);
+    const fileOwnership = issue.filesToModify.length > 0
+        ? `\n> FILE OWNERSHIP: You own these files exclusively: ${issue.filesToModify.join(', ')}. Other teammates own all other files.`
+        : '';
+    return `Spawn teammate **${issue.id.toLowerCase()}** using the **Agent** tool with \`team_name: "${teamName}"\` and \`name: "${issue.id.toLowerCase()}"\`:
+> ${predInstr}Work on issue ${issue.id}: ${issue.title}.
+> Read the full spec at ${pmDir ? join(pmDir, issue.path) : issue.path}.
+> Execute all acceptance criteria.
+> Write all output and results to ${outputFile} — this is the handoff artifact for downstream issues.
+> After writing output, update the issue front matter: change \`status: in_progress\` to \`status: done\`.
+> The orchestrator manages STATE.md. Stay within this issue's scope.${fileOwnership}`;
+}
+function assembleCoordinatorPrompt(args) {
+    const { issues, workingDir, pmDir, outDir, teamName, issueBlocks, teammateSpawns } = args;
+    const issueCount = issues.length;
+    const plural = issueCount > 1 ? 's' : '';
+    const checklist = issues.map(i => `- [ ] ${i.id.toLowerCase()}`).join('\n');
+    const teammateNames = issues.map(i => `- \`${i.id.toLowerCase()}\``).join('\n');
+    return `You are the team lead coordinating ${issueCount} issue${plural} using Agent Teams.
+
+## Project Directory
+Working directory: ${workingDir}
+Plan directory: ${pmDir || specsDirOrDefault(workingDir)}
+
+## Issues to Execute
+
+${issueBlocks}
+
+## Execution Protocol — Agent Teams
+
+All team coordination uses exactly two tools:
+- **Agent** — spawn teammates (include \`team_name\` and \`name\` in each call)
+- **SendMessage** — message teammates after they are spawned
+
+### Step 1: Spawn all teammates in one message
+
+Send a single message containing ${issueCount} **Agent** tool calls. Include \`team_name: "${teamName}"\` and a unique \`name\` in each call. The team starts automatically when the first teammate is spawned — the \`team_name\` parameter handles all setup.
+
+${teammateSpawns}
+
+### Step 2: Wait for every teammate to finish
+
+After spawning, idle notifications arrive automatically as messages — you will be notified when each teammate finishes. Between notifications, you have nothing to do. Simply state that you are waiting and let the system deliver notifications to you.
+
+Your first action after spawning all teammates: output a brief status message listing all teammates and confirming you are waiting for their idle notifications. Then wait.
+
+Track completion against this checklist — proceed to Step 3 only after all are checked:
+${checklist}
+
+Exact teammate names for SendMessage (messages to any other name are silently dropped):
+${teammateNames}
+
+When you receive an idle notification from a teammate:
+- Check off that teammate in the checklist above
+- Verify their output file exists on disk using the **Read** tool
+
+If 15 minutes pass without an idle notification from a specific teammate, send them a progress check via **SendMessage** using the exact name from the list above. After 5 more minutes with no response, check their output file and issue status on disk — if the output exists and status is \`done\`, mark them complete. Otherwise, update the issue status based on whatever partial work exists, then continue.
+
+Staying active until all teammates finish is essential — when the lead exits, all teammate processes stop and their in-progress work is lost. When unsure whether a teammate is still working, keep waiting.
+
+### Step 3: Verify outputs
+
+Once every teammate has completed or been handled:
+1. Verify each output file exists in ${outDir}/ using **Read** or **Glob**
+2. Verify each issue's front matter status is \`done\`
+3. For any missing output or status update, write it yourself
+4. The orchestrator manages STATE.md separately — focus on output files and issue front matter only
+
+### Step 4: Clean up and exit
+
+After all outputs are verified:
+- Send each remaining active teammate a shutdown message via **SendMessage**
+- Then exit — the orchestrator handles the next wave
+
+## Coordination Rules
+
+- The team starts implicitly when you spawn the first teammate with \`team_name\`. Cleanup happens automatically when all teammates exit or the lead exits.
+- Wait for idle notifications from all ${issueCount} teammates before exiting — this ensures all work is saved to disk.
+- Each teammate writes its output to disk (the handoff artifact for downstream issues). Research kept only in conversation is lost when the teammate exits.
+- Each teammate updates its issue front matter status to \`done\` when finished.
+- One issue per teammate — each teammate stays within its assigned scope.
+- Use only the exact teammate names listed above for SendMessage.`;
+}
+function resolvePredecessorDocs(issue, existingDocs) {
+    return issue.blockedBy
+        .map(bp => {
+        const blockerId = bp.replace(/^backlog\//, '').replace(/\.md$/, '');
+        return existingDocs.find(d => d.toLowerCase().includes(blockerId.toLowerCase()));
+    })
+        .filter(Boolean);
+}

package/dist/server/services/plan/quality-delta.js

@@ -0,0 +1,274 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { extname, join, relative, resolve } from 'node:path';
+import { getPersistence } from '../websocket/quality-handlers.js';
+import { QualityPersistence } from '../websocket/quality-persistence.js';
+import { indexDismissals, isActiveFinding, runQualityScan } from '../websocket/quality-service.js';
+import { attributeToTrackedDirectories, detectEcosystem } from '../websocket/quality-tools.js';
+import { SOURCE_EXTENSIONS } from '../websocket/quality-types.js';
+import { resolveIsCodeTask } from './issue-classification.js';
+export const QUALITY_DELTA_DIRNAME = 'quality';
+export const QUALITY_DELTA_MAX_FINDINGS = 200;
+export const WORKTREE_NOT_CHECKED_REASON = 'worktree boards are not checked yet';
+export function qualityGateSkipReason(issue, gate) {
+    if (gate === 'off')
+        return "quality_gate is 'off'";
+    if (issue.reviewGate === 'none')
+        return "review_gate is 'none'";
+    if (!resolveIsCodeTask(issue))
+        return 'document issue';
+    return null;
+}
+export function unavailableQualityDelta(issueId, gate, reason, now = new Date()) {
+    return { issueId, recordedAt: now.toISOString(), gate, available: false, reason };
+}
+function isInside(dir, path) {
+    return path === dir || path.startsWith(`${dir}/`);
+}
+function rootRelative(root, absolute) {
+    return relative(root, absolute).split('\\').join('/');
+}
+function uncheckableReason(absolute) {
+    if (!existsSync(absolute))
+        return 'no such file';
+    try {
+        if (!statSync(absolute).isFile())
+            return 'not a file';
+    }
+    catch {
+        return 'not readable';
+    }
+    const ext = extname(absolute).toLowerCase();
+    if (!SOURCE_EXTENSIONS.has(ext)) {
+        return `not a source file the analyzers read (${ext || 'no extension'})`;
+    }
+    return null;
+}
+function noEcosystemReason(dirPath) {
+    const where = dirPath === '.' ? 'the working directory' : `'${dirPath}'`;
+    return `no ecosystem detected in ${where} — no package.json, pyproject.toml, setup.py, requirements.txt, Cargo.toml, go.mod, Package.swift or build.gradle there, so no analyzer can run on it`;
+}
+function trackedDirectories(root) {
+    return QualityPersistence.isSetUp(root) ? getPersistence(root).loadConfig() : [];
+}
+async function scanDirectory(root, dirPath, dir, files, signal) {
+    if (!QualityPersistence.isSetUp(root)) {
+        return (await runQualityScan(dir, { files, signal })).findings;
+    }
+    const persistence = getPersistence(root);
+    const results = await runQualityScan(dir, {
+        files,
+        signal,
+        baseline: persistence.loadBaseline(dirPath),
+        dismissals: indexDismissals(dirPath, persistence.loadSuppressionsFor(dirPath)),
+    });
+    return results.findings;
+}
+async function scanPaths(deps, paths) {
+    const root = resolve(deps.spaceRoot);
+    const { admitted, unchecked } = admitPaths(root, paths);
+    const checked = [];
+    const findings = [];
+    for (const { path: dirPath, files } of attributeToTrackedDirectories(root, trackedDirectories(root), [...admitted])) {
+        const dir = resolve(root, dirPath);
+        const relPaths = files.map((file) => rootRelative(root, resolve(dir, file)));
+        if (detectEcosystem(dir).every((eco) => eco === 'unknown')) {
+            const reason = noEcosystemReason(dirPath);
+            for (const path of relPaths)
+                unchecked.push({ path, reason });
+            continue;
+        }
+        const scanned = await scanDirectory(root, dirPath, dir, files, deps.signal);
+        checked.push(...relPaths);
+        for (const finding of scanned) {
+            if (!isActiveFinding(finding))
+                continue;
+            findings.push({ finding, path: rootRelative(root, resolve(dir, finding.file)) });
+        }
+    }
+    return { checked, unchecked, findings };
+}
+function admitPaths(root, paths) {
+    const admitted = new Set();
+    const unchecked = [];
+    for (const path of paths) {
+        const absolute = resolve(root, path);
+        if (!isInside(root, absolute)) {
+            unchecked.push({ path, reason: 'outside the working directory — only files inside it are checked' });
+            continue;
+        }
+        const reason = uncheckableReason(absolute);
+        if (reason)
+            unchecked.push({ path: rootRelative(root, absolute), reason });
+        else
+            admitted.add(absolute);
+    }
+    return { admitted, unchecked };
+}
+function listedPaths(issue) {
+    const paths = [];
+    for (const entry of issue.filesToModify) {
+        const path = entry.trim().replace(/^`(.*)`$/, '$1');
+        if (!path || /^Output:/i.test(path))
+            continue;
+        if (!paths.includes(path))
+            paths.push(path);
+    }
+    return paths;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export async function captureQualityBaseline(deps, issue, now = new Date()) {
+    const root = resolve(deps.spaceRoot);
+    const missing = [];
+    const present = [];
+    for (const path of listedPaths(issue)) {
+        const absolute = resolve(root, path);
+        if (isInside(root, absolute) && !existsSync(absolute))
+            missing.push(rootRelative(root, absolute));
+        else
+            present.push(path);
+    }
+    try {
+        const outcome = await scanPaths(deps, present);
+        const fingerprints = new Set();
+        for (const { finding } of outcome.findings) {
+            if (finding.fingerprint !== undefined)
+                fingerprints.add(finding.fingerprint);
+        }
+        return {
+            available: true,
+            baseline: {
+                capturedAt: now.toISOString(),
+                checked: outcome.checked,
+                missing,
+                unchecked: outcome.unchecked,
+                fingerprints: [...fingerprints],
+            },
+        };
+    }
+    catch (error) {
+        return { available: false, reason: `baseline scan failed: ${errorMessage(error)}` };
+    }
+}
+function isIntroduced(finding, path, baseline, created) {
+    if (created.has(path))
+        return true;
+    return finding.fingerprint === undefined || !baseline.has(finding.fingerprint);
+}
+const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3 };
+function toDeltaFinding(finding, path) {
+    return {
+        severity: finding.severity,
+        category: finding.category,
+        path,
+        line: finding.line,
+        title: finding.title,
+        ...(finding.suggestion ? { suggestion: finding.suggestion } : {}),
+        fingerprint: finding.fingerprint ?? '',
+    };
+}
+export async function computeQualityDelta(deps, args, now = new Date()) {
+    const { issue, gate, baseline, writtenFiles } = args;
+    if (!baseline.available)
+        return unavailableQualityDelta(issue.id, gate, baseline.reason, now);
+    const root = resolve(deps.spaceRoot);
+    const paths = new Map();
+    for (const path of [...listedPaths(issue), ...writtenFiles]) {
+        const absolute = resolve(root, path);
+        if (!paths.has(absolute))
+            paths.set(absolute, path);
+    }
+    let outcome;
+    try {
+        outcome = await scanPaths(deps, [...paths.values()]);
+    }
+    catch (error) {
+        return unavailableQualityDelta(issue.id, gate, `delta scan failed: ${errorMessage(error)}`, now);
+    }
+    const known = new Set(baseline.baseline.fingerprints);
+    const createdFiles = baseline.baseline.missing.filter((path) => existsSync(resolve(root, path)));
+    const created = new Set(createdFiles);
+    const introducedAll = outcome.findings
+        .filter(({ finding, path }) => isIntroduced(finding, path, known, created))
+        .sort((a, b) => SEVERITY_RANK[a.finding.severity] - SEVERITY_RANK[b.finding.severity]);
+    const listed = introducedAll.slice(0, QUALITY_DELTA_MAX_FINDINGS);
+    return {
+        issueId: issue.id,
+        recordedAt: now.toISOString(),
+        gate,
+        available: true,
+        baselineAt: baseline.baseline.capturedAt,
+        checked: outcome.checked,
+        unchecked: outcome.unchecked,
+        createdFiles,
+        introducedCount: introducedAll.length,
+        introduced: listed.map(({ finding, path }) => toDeltaFinding(finding, path)),
+        truncated: introducedAll.length > listed.length,
+    };
+}
+export function qualityDeltaDir(boardDir) {
+    return join(boardDir, QUALITY_DELTA_DIRNAME);
+}
+export function persistQualityDelta(boardDir, record, epochMs = Date.now()) {
+    const dir = qualityDeltaDir(boardDir);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${record.issueId}-${epochMs}.json`);
+    writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, 'utf-8');
+    return path;
+}
+const DELTA_FILE_RE = /^(.+)-(\d+)\.json$/;
+export function readLatestQualityDeltas(boardDir) {
+    const dir = qualityDeltaDir(boardDir);
+    const newest = new Map();
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return new Map();
+    }
+    for (const name of names) {
+        const match = name.match(DELTA_FILE_RE);
+        if (!match)
+            continue;
+        const epochMs = Number(match[2]);
+        const current = newest.get(match[1]);
+        if (!current || epochMs > current.epochMs)
+            newest.set(match[1], { epochMs, name });
+    }
+    const records = new Map();
+    for (const [issueId, { name }] of newest) {
+        try {
+            const record = JSON.parse(readFileSync(join(dir, name), 'utf-8'));
+            if (record && typeof record === 'object' && record.issueId === issueId)
+                records.set(issueId, record);
+        }
+        catch {
+        }
+    }
+    return records;
+}
+const SEVERITIES = ['critical', 'high', 'medium', 'low'];
+export function summarizeQualityDelta(record) {
+    const { recordedAt, gate } = record;
+    if (!record.available)
+        return { available: false, recordedAt, gate, reason: record.reason };
+    const introduced = Object.fromEntries(SEVERITIES.map((severity) => [severity, 0]));
+    for (const finding of record.introduced) {
+        if (finding.severity in introduced)
+            introduced[finding.severity] += 1;
+    }
+    return {
+        available: true,
+        recordedAt,
+        gate,
+        introducedCount: record.introducedCount,
+        introduced,
+        truncated: record.truncated,
+        uncheckedCount: record.unchecked.length,
+    };
+}

package/dist/server/services/plan/readiness-planner.js

@@ -0,0 +1,34 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+const TERMINAL_STATUSES = new Set(['done', 'cancelled']);
+export function buildCompletionReason(issues, epicScope) {
+    const nonEpic = issues.filter(i => i.type !== 'epic');
+    const done = nonEpic.filter(i => TERMINAL_STATUSES.has(i.status)).length;
+    const blocked = nonEpic.filter(i => i.status === 'todo').length;
+    if (done === nonEpic.length)
+        return epicScope ? 'All epic issues are done' : 'All issues are done';
+    if (blocked > 0)
+        return `${done}/${nonEpic.length} issues done, ${blocked} blocked by incomplete dependencies`;
+    return epicScope ? 'All epic issues are done or blocked' : 'All work is done or blocked';
+}
+export function detectDeadState(issues) {
+    const nonEpic = issues.filter(i => i.type !== 'epic');
+    const stuck = nonEpic.filter(i => !TERMINAL_STATUSES.has(i.status) && i.status !== 'todo');
+    if (stuck.length === 0)
+        return null;
+    const stuckIds = stuck.map(i => `${i.id} (${i.status})`).join(', ');
+    const issueByPath = new Map(issues.map(i => [i.path, i]));
+    const blockedByStuck = nonEpic.filter(i => {
+        if (i.status !== 'todo')
+            return false;
+        return i.blockedBy.some(bp => {
+            const blocker = issueByPath.get(bp);
+            return blocker && !TERMINAL_STATUSES.has(blocker.status);
+        });
+    });
+    const blockedIds = blockedByStuck.map(i => i.id).join(', ');
+    return `Board stuck: ${stuckIds} cannot progress${blockedIds ? `. Blocking: ${blockedIds}` : ''}`;
+}
+export function hasBlockedIssues(issues) {
+    return issues.some(i => i.type !== 'epic' && !TERMINAL_STATUSES.has(i.status) && i.status !== 'todo');
+}