@webpresso/agent-kit 0.28.0 → 0.29.1

package/dist/esm/audit/blueprint-lifecycle-sql.js

@@ -1,60 +1,185 @@
 /**
- * `wp audit blueprint-lifecycle-sql` — SQL-backed rewrite of the existing
- * blueprint-lifecycle audit.
+ * `wp audit blueprint-lifecycle` — the single, deterministic blueprint-lifecycle
+ * audit.
  *
- * Uses the SQLite replica as the primary source when the DB file exists.
- * Falls back to the markdown-based audit when the DB has not been built yet.
+ * The verdict is a pure function of `markdown@HEAD`: this builds an EPHEMERAL
+ * in-memory SQLite projection from the repo's blueprint markdown
+ * (`buildEphemeralProjection`), runs the relational checks against it, and
+ * discards it. It also runs the structural markdown checks
+ * (`auditBlueprintLifecycle` — type / status-vs-folder / `_overview.md` presence /
+ * linking-frontmatter) and merges both result sets. No persistent on-disk
+ * projection is read, so the audit can never hit a stale/missing/locked DB and
+ * is identical across CLI, the `wp_audit` MCP tool, `wp doctor`, and CI.
  *
- * SQL checks (when DB exists):
+ * Relational checks (against the in-memory projection):
  * 1. Blueprints with status='in-progress' that have 0 tasks (invalid).
  * 2. Blueprints whose `status` column doesn't match the directory segment
- *    derived from `file_path` (e.g. stored in completed/ but status=in-progress).
+ *    derived from `file_path`.
  * 3. Tasks in state 'in-progress' whose dependencies are not all done.
  * 4. Blueprints with progress_pct < 100 but status='completed'.
  */
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { existsSync } from 'node:fs';
-import { migrateLegacyAgentDb } from '#db/legacy-migration.js';
-import { resolveBlueprintProjectionDbPath } from '#db/paths.js';
-// Legacy fallback path — kept for the brief window where a migration may have
-// just-happened (Task 1.1 / F12 / R10 / E12). Worktree-scoped path is canonical.
-const LEGACY_DB_PATH = path.join('.agent', '.blueprints.db');
-export async function auditBlueprintLifecycleSql(cwd) {
-    // F12/R10/E12: trigger one-shot migration before resolving the DB so a stray
-    // legacy file is moved (and gone) before we count rows. After this call the
-    // canonical worktree-scoped path is the single source of truth.
-    migrateLegacyAgentDb(cwd);
-    // Prefer the canonical worktree-scoped path. If the migration failed because
-    // the destination already existed, the warning is already logged; we trust
-    // the canonical DB and never read the legacy file in addition, which would
-    // double-count rows.
-    let dbFile;
+import { getLegalLifecycleTargets, isLegalLifecycleTransition, parseLifecycleBlueprintStatus, } from '#lifecycle/transition-matrix.js';
+import { buildEphemeralProjection } from '#db/ephemeral-projection.js';
+import { loadBudgets } from './_budgets.js';
+/** A task is "terminal" (counts as finished) when it is done OR intentionally dropped. */
+const TERMINAL_TASK_SQL = "('done','dropped')";
+const STALENESS_SCOPE = new Set(['in-progress']);
+const STALENESS_WARNING_PREFIX = '[warn]';
+function isGitHistoryAvailable(cwd) {
     try {
-        dbFile = resolveBlueprintProjectionDbPath(cwd);
+        execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 1_500,
+        });
+        return true;
     }
     catch {
-        dbFile = path.join(cwd, LEGACY_DB_PATH);
+        return false;
     }
-    if (!existsSync(dbFile)) {
-        // DB not yet built — fall back to markdown-based audit
-        const { auditBlueprintLifecycle } = await import('./repo-guardrails.js');
-        return auditBlueprintLifecycle(cwd);
+}
+function readLastGitTouchIso(cwd, filePath) {
+    try {
+        const repoRelativePath = path.isAbsolute(filePath) ? path.relative(cwd, filePath) : filePath;
+        const out = execFileSync('git', ['log', '-1', '--format=%cI', '--', repoRelativePath], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 1_500,
+        }).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+function ageInDays(isoTimestamp, nowMs) {
+    const touchedAtMs = Date.parse(isoTimestamp);
+    if (Number.isNaN(touchedAtMs))
+        return null;
+    return Math.floor((nowMs - touchedAtMs) / 86_400_000);
+}
+function readFrontmatterStatus(markdown) {
+    const frontmatterBody = readFrontmatterBody(markdown);
+    if (!frontmatterBody)
+        return null;
+    const statusMatch = frontmatterBody.match(/^status:\s*(.+)$/m);
+    if (!statusMatch?.[1])
+        return null;
+    return statusMatch[1].trim().replace(/^['"]|['"]$/g, '');
+}
+function readFrontmatterBody(markdown) {
+    const frontmatterMatch = markdown.match(/^---\n([\s\S]*?)\n---/m);
+    return frontmatterMatch?.[1] ?? null;
+}
+function hasHistoricalVerificationGapWaiver(markdown) {
+    const frontmatterBody = readFrontmatterBody(markdown);
+    if (!frontmatterBody)
+        return false;
+    return /^historical_verification_gap_waiver:\s*true\s*$/m.test(frontmatterBody);
+}
+function listBlueprintHistoryEntries(cwd, filePath) {
+    try {
+        const repoRelativePath = path.isAbsolute(filePath) ? path.relative(cwd, filePath) : filePath;
+        let trackedPath = repoRelativePath.replace(/\\/g, '/');
+        const out = execFileSync('git', ['log', '--follow', '--format=commit:%H', '--name-status', '--', trackedPath], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 1_500,
+            maxBuffer: 1024 * 1024,
+        });
+        const history = [];
+        let currentRevision = null;
+        let currentPathAtRevision = null;
+        let nextTrackedPath = trackedPath;
+        const flushEntry = () => {
+            if (!currentRevision || !currentPathAtRevision)
+                return;
+            history.push({ revision: currentRevision, filePath: currentPathAtRevision });
+            trackedPath = nextTrackedPath;
+        };
+        for (const rawLine of out.split('\n')) {
+            const line = rawLine.trim();
+            if (!line)
+                continue;
+            if (line.startsWith('commit:')) {
+                flushEntry();
+                currentRevision = line.slice('commit:'.length).trim();
+                currentPathAtRevision = trackedPath;
+                nextTrackedPath = trackedPath;
+                continue;
+            }
+            const parts = line.split('\t');
+            const status = parts[0]?.trim() ?? '';
+            if (!status.startsWith('R'))
+                continue;
+            const oldPath = parts[1]?.trim().replace(/\\/g, '/');
+            const newPath = parts[2]?.trim().replace(/\\/g, '/');
+            if (oldPath && newPath && newPath === currentPathAtRevision) {
+                nextTrackedPath = oldPath;
+            }
+        }
+        flushEntry();
+        return history;
+    }
+    catch {
+        return [];
     }
-    const { Database } = await import('#db/sqlite.js');
-    const db = new Database(dbFile, { readonly: true });
-    const violations = [];
-    let checked = 0;
+}
+function readHistoricalFile(cwd, revision, filePath) {
+    try {
+        return execFileSync('git', ['show', `${revision}:${filePath}`], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 1_500,
+            maxBuffer: 1024 * 1024,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function readPreviousLifecycleStatusFromGit(cwd, filePath, currentStatus) {
+    const history = listBlueprintHistoryEntries(cwd, filePath);
+    if (history.length < 2)
+        return null;
+    for (const entry of history.slice(1)) {
+        const markdown = readHistoricalFile(cwd, entry.revision, entry.filePath);
+        if (!markdown)
+            continue;
+        const status = readFrontmatterStatus(markdown);
+        if (!status || status === currentStatus)
+            continue;
+        return status;
+    }
+    return null;
+}
+export async function auditBlueprintLifecycleSql(cwd = process.cwd(), options = {}) {
+    const budgets = loadBudgets(cwd);
+    const wipInProgressMax = budgets['blueprint-wip-in-progress-max'].max ?? 3;
+    const staleInProgressDays = budgets['blueprint-stale-in-progress-days'].max_days ?? 14;
+    // Structural markdown checks (type / status-vs-folder / _overview / linking /
+    // optional .omx-plan handoff governance). Run unconditionally and merged —
+    // this is NOT a fallback. Dynamic import keeps the heavy guardrails module off
+    // the hook-runtime hot path until the audit runs.
+    const { auditBlueprintLifecycle } = await import('./repo-guardrails.js');
+    const structural = auditBlueprintLifecycle(cwd, options);
+    const violations = [...structural.violations];
+    const advisoryViolations = [];
+    let checked = structural.checked;
+    const titleNotices = [];
+    const conn = await buildEphemeralProjection(cwd);
+    const { db } = conn;
     try {
         const allBlueprints = db
             .prepare('SELECT slug, status, file_path, progress_pct FROM blueprints')
             .all();
-        if (allBlueprints.length === 0) {
-            const { auditBlueprintLifecycle } = await import('./repo-guardrails.js');
-            const markdownAudit = auditBlueprintLifecycle(cwd);
-            if (markdownAudit.checked > 0) {
-                return markdownAudit;
-            }
-        }
         // -----------------------------------------------------------------------
         // 1. in-progress blueprints with 0 tasks
         // -----------------------------------------------------------------------
@@ -75,12 +200,10 @@ export async function auditBlueprintLifecycleSql(cwd) {
         }
         // -----------------------------------------------------------------------
         // 2. status/directory mismatch
-        //    Derive the directory segment from the file_path and compare to status.
         //    Blueprint file_path convention: blueprints/<status>/<slug>/_overview.md
         // -----------------------------------------------------------------------
         checked += allBlueprints.length;
         for (const row of allBlueprints) {
-            // Derive directory status from the path: second segment after 'blueprints/'
             const segments = row.file_path.replace(/\\/g, '/').split('/');
             const blueprintsIdx = segments.lastIndexOf('blueprints');
             const dirStatus = blueprintsIdx >= 0 ? segments[blueprintsIdx + 1] : null;
@@ -117,27 +240,154 @@ export async function auditBlueprintLifecycleSql(cwd) {
         // -----------------------------------------------------------------------
         const incompleteCompleted = db
             .prepare(`SELECT slug, file_path, progress_pct
-         FROM blueprints
-         WHERE status = 'completed'
-           AND progress_pct IS NOT NULL
-           AND progress_pct < 100`)
+          FROM blueprints
+          WHERE status = 'completed'
+            AND progress_pct IS NOT NULL
+            AND progress_pct < 100`)
             .all();
         checked += incompleteCompleted.length;
         for (const row of incompleteCompleted) {
+            const hasNonTerminalTask = db
+                .prepare(`SELECT COUNT(*) AS open_tasks
+             FROM tasks
+            WHERE blueprint_slug = ?
+              AND status NOT IN ${TERMINAL_TASK_SQL}`)
+                .get(row.slug);
+            if ((hasNonTerminalTask?.open_tasks ?? 0) === 0)
+                continue;
             violations.push({
                 file: row.file_path,
                 message: `Blueprint '${row.slug}' is marked completed but progress_pct is ${row.progress_pct}% (expected 100)`,
             });
         }
+        // -----------------------------------------------------------------------
+        // 5. in-progress blueprints whose tasks are ALL terminal (done|dropped)
+        //    — finished work left in the in-progress lane. terminal = done ∪ dropped
+        //    so a de-scoped task doesn't keep a finished blueprint pinned forever.
+        // -----------------------------------------------------------------------
+        const allTerminalInProgress = db
+            .prepare(`SELECT b.slug, b.file_path, COUNT(t.id) AS total
+         FROM blueprints b
+         JOIN tasks t ON t.blueprint_slug = b.slug
+         WHERE b.status = 'in-progress'
+         GROUP BY b.slug, b.file_path
+         HAVING COUNT(t.id) > 0
+            AND SUM(CASE WHEN t.status IN ${TERMINAL_TASK_SQL} THEN 1 ELSE 0 END) = COUNT(t.id)`)
+            .all();
+        checked += allTerminalInProgress.length;
+        for (const row of allTerminalInProgress) {
+            violations.push({
+                file: row.file_path,
+                message: `Blueprint '${row.slug}' has all ${row.total} tasks done/dropped but is still in 'in-progress/' — move it to completed/ or reopen a task`,
+            });
+        }
+        // -----------------------------------------------------------------------
+        // 6. completed blueprints with a non-terminal task (status untruthful)
+        // -----------------------------------------------------------------------
+        const completedWithOpenTasks = db
+            .prepare(`SELECT b.slug, b.file_path
+         FROM blueprints b
+         WHERE b.status = 'completed'
+           AND EXISTS (
+             SELECT 1 FROM tasks t
+             WHERE t.blueprint_slug = b.slug
+               AND t.status NOT IN ${TERMINAL_TASK_SQL}
+           )`)
+            .all();
+        checked += completedWithOpenTasks.length;
+        for (const row of completedWithOpenTasks) {
+            violations.push({
+                file: row.file_path,
+                message: `Blueprint '${row.slug}' is marked completed but has tasks that are not done/dropped`,
+            });
+        }
+        // -----------------------------------------------------------------------
+        // 7. WIP limit — at most the configured max blueprints in the in-progress lane
+        // -----------------------------------------------------------------------
+        const inProgressCountRows = db
+            .prepare(`SELECT COUNT(*) AS n FROM blueprints WHERE status = 'in-progress'`)
+            .all();
+        const inProgressCount = inProgressCountRows[0]?.n ?? 0;
+        checked += 1;
+        if (inProgressCount > wipInProgressMax) {
+            violations.push({
+                message: `${inProgressCount} blueprints are in-progress — the lane limit is ${wipInProgressMax} (budget: blueprint-wip-in-progress-max); finish or park some before starting more`,
+            });
+        }
+        // -----------------------------------------------------------------------
+        // 8. Staleness — warn (do not fail) when an in-progress blueprint has not
+        //    been touched in git within the configured day budget.
+        // -----------------------------------------------------------------------
+        const staleCandidates = allBlueprints.filter((row) => STALENESS_SCOPE.has(row.status));
+        checked += staleCandidates.length;
+        if (staleCandidates.length > 0) {
+            if (isGitHistoryAvailable(cwd)) {
+                const nowMs = Date.now();
+                for (const row of staleCandidates) {
+                    const lastTouchIso = readLastGitTouchIso(cwd, row.file_path);
+                    if (lastTouchIso === null)
+                        continue;
+                    const ageDays = ageInDays(lastTouchIso, nowMs);
+                    if (ageDays === null || ageDays <= staleInProgressDays)
+                        continue;
+                    advisoryViolations.push({
+                        file: row.file_path,
+                        message: `${STALENESS_WARNING_PREFIX} Blueprint '${row.slug}' is stale: last git touch was ` +
+                            `${lastTouchIso.slice(0, 10)} (${ageDays} days ago), exceeding ` +
+                            `blueprint-stale-in-progress-days=${staleInProgressDays}`,
+                    });
+                }
+            }
+            else {
+                titleNotices.push('staleness check skipped outside git');
+            }
+        }
+        // -----------------------------------------------------------------------
+        // 9. Transition legality — best effort, based on previous lifecycle status
+        //    observed in git history. Missing history fails open by design.
+        // -----------------------------------------------------------------------
+        checked += allBlueprints.length;
+        if (allBlueprints.length === 0) {
+            // Nothing to reconcile against history, so suppress the outside-git notice.
+        }
+        else if (isGitHistoryAvailable(cwd)) {
+            for (const row of allBlueprints) {
+                const currentMarkdown = readFileSync(row.file_path, 'utf8');
+                if (hasHistoricalVerificationGapWaiver(currentMarkdown))
+                    continue;
+                const currentStatus = parseLifecycleBlueprintStatus(row.status);
+                if (!currentStatus)
+                    continue;
+                const previousRaw = readPreviousLifecycleStatusFromGit(cwd, row.file_path, currentStatus);
+                if (!previousRaw)
+                    continue;
+                const previousStatus = parseLifecycleBlueprintStatus(previousRaw);
+                if (!previousStatus)
+                    continue;
+                if (isLegalLifecycleTransition(previousStatus, currentStatus))
+                    continue;
+                violations.push({
+                    file: row.file_path,
+                    message: `Blueprint '${row.slug}' moved from '${previousStatus}' to '${currentStatus}', which is illegal; ` +
+                        `legal targets from '${previousStatus}' are: ${getLegalLifecycleTargets(previousStatus).join(', ') || '(none)'}`,
+                });
+            }
+        }
+        else {
+            titleNotices.push('transition history check skipped outside git');
+        }
+        const title = titleNotices.length === 0
+            ? 'Blueprint lifecycle'
+            : `Blueprint lifecycle — ${titleNotices.join('; ')}`;
         return {
             ok: violations.length === 0,
-            title: 'Blueprint lifecycle (SQL)',
+            title,
             checked,
-            violations,
+            violations: [...violations, ...advisoryViolations],
         };
     }
     finally {
-        db.close();
+        conn.close();
     }
 }
 //# sourceMappingURL=blueprint-lifecycle-sql.js.map

package/dist/esm/audit/blueprint-readme-drift.d.ts

@@ -0,0 +1,6 @@
+import type { RepoAuditResult } from './repo-guardrails.js';
+export interface BlueprintReadmeDriftOptions {
+    fix?: boolean;
+}
+export declare function auditBlueprintReadmeDrift(cwd?: string, options?: BlueprintReadmeDriftOptions): RepoAuditResult;
+//# sourceMappingURL=blueprint-readme-drift.d.ts.map

package/dist/esm/audit/blueprint-readme-drift.js

@@ -0,0 +1,110 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { scanBlueprintDirectory } from '#service/scanner.js';
+import { parseBlueprintDocumentRelativePath } from '#utils/document-paths.js';
+const README_RELATIVE_PATH = 'blueprints/README.md';
+const BEGIN_MARKER = '<!-- BEGIN: blueprint-index (generated by `wp audit blueprint-readme-drift --fix`) -->';
+const END_MARKER = '<!-- END: blueprint-index -->';
+const README_INSERT_HEADING = '## Authoring';
+const README_STALE_MESSAGE = "blueprints/README.md index block is stale — run 'wp audit blueprint-readme-drift --fix'";
+const STATE_ROWS = [
+    ['draft', 'early-stage sketches. Expect churn; move to `planned/` once scoped.'],
+    ['planned', 'committed-to specs, ready to pick up.'],
+    ['in-progress', 'actively being executed. At most 3 active blueprints per lane.'],
+    ['completed', 'execution finished and verified. Kept for reference.'],
+    ['parked', "intentionally paused. Include a reason in the spec's frontmatter."],
+    ['archived', 'superseded or abandoned. Not deleted — the record matters.'],
+];
+function initialCounts() {
+    return {
+        draft: 0,
+        planned: 0,
+        'in-progress': 0,
+        completed: 0,
+        parked: 0,
+        archived: 0,
+    };
+}
+function countBlueprintsByState(cwd) {
+    const counts = initialCounts();
+    const blueprintsRoot = path.join(cwd, 'blueprints');
+    if (!existsSync(blueprintsRoot))
+        return counts;
+    const scanned = scanBlueprintDirectory({
+        baseDir: blueprintsRoot,
+        includeSpecialFolders: true,
+    });
+    for (const blueprint of scanned) {
+        const relativePath = path.relative(blueprintsRoot, blueprint.path).replace(/\\/g, '/');
+        const parsed = parseBlueprintDocumentRelativePath(relativePath);
+        if (!parsed)
+            continue;
+        counts[parsed.state] += 1;
+    }
+    return counts;
+}
+function renderGeneratedBlock(counts) {
+    const lines = [
+        BEGIN_MARKER,
+        '| State | Count | Description |',
+        '| ----- | ----: | ----------- |',
+        ...STATE_ROWS.map(([state, description]) => `| \`${state}/\` | ${counts[state]} | ${description} |`),
+        END_MARKER,
+    ];
+    return `${lines.join('\n')}\n`;
+}
+function replaceExistingBlock(markdown, block) {
+    const start = markdown.indexOf(BEGIN_MARKER);
+    const end = markdown.indexOf(END_MARKER);
+    if (start >= 0 && end >= start) {
+        const afterEnd = end + END_MARKER.length;
+        return `${markdown.slice(0, start)}${block}${markdown.slice(afterEnd)}`;
+    }
+    const insertAt = markdown.indexOf(README_INSERT_HEADING);
+    if (insertAt >= 0) {
+        return `${markdown.slice(0, insertAt).replace(/\n*$/, '\n\n')}${block}${markdown.slice(insertAt)}`;
+    }
+    return `${markdown.replace(/\s*$/, '\n\n')}${block}`;
+}
+function extractExistingBlock(markdown) {
+    const start = markdown.indexOf(BEGIN_MARKER);
+    const end = markdown.indexOf(END_MARKER);
+    if (start < 0 || end < start)
+        return null;
+    return markdown.slice(start, end + END_MARKER.length);
+}
+export function auditBlueprintReadmeDrift(cwd = process.cwd(), options = {}) {
+    const readmePath = path.join(cwd, README_RELATIVE_PATH);
+    if (!existsSync(readmePath)) {
+        return {
+            ok: false,
+            title: 'Blueprint README drift',
+            checked: 1,
+            violations: [{ file: README_RELATIVE_PATH, message: `${README_RELATIVE_PATH} is missing` }],
+        };
+    }
+    const current = readFileSync(readmePath, 'utf8');
+    const expectedBlock = renderGeneratedBlock(countBlueprintsByState(cwd));
+    const currentBlock = extractExistingBlock(current);
+    const updated = replaceExistingBlock(current, expectedBlock);
+    const isInSync = currentBlock !== null && currentBlock.trimEnd() === expectedBlock.trimEnd();
+    if (!isInSync && options.fix) {
+        mkdirSync(path.dirname(readmePath), { recursive: true });
+        writeFileSync(readmePath, updated, 'utf8');
+        return {
+            ok: true,
+            title: 'Blueprint README drift',
+            checked: 1,
+            violations: [],
+        };
+    }
+    return {
+        ok: isInSync,
+        title: 'Blueprint README drift',
+        checked: 1,
+        violations: isInSync
+            ? []
+            : [{ file: README_RELATIVE_PATH, message: README_STALE_MESSAGE }],
+    };
+}
+//# sourceMappingURL=blueprint-readme-drift.js.map

package/dist/esm/audit/no-first-party-mjs.js

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 const IGNORED_PATH_PREFIXES = [
     'node_modules',
@@ -34,10 +34,10 @@ function fail(root, message) {
     };
 }
 function resolveCanonicalRepoRoot(rootDirectory) {
-    const requestedRoot = resolve(rootDirectory);
+    const requestedRoot = realpathSync.native(resolve(rootDirectory));
     let gitRoot;
     try {
-        gitRoot = resolve(execFileSync('git', ['rev-parse', '--show-toplevel'], {
+        gitRoot = realpathSync.native(execFileSync('git', ['rev-parse', '--show-toplevel'], {
             cwd: requestedRoot,
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -63,7 +63,8 @@ function listTrackedFiles(root) {
     return output
         .split('\n')
         .map((line) => line.trim())
-        .filter(Boolean);
+        .filter(Boolean)
+        .filter((relativePath) => existsSync(join(root, relativePath)));
 }
 export function auditNoFirstPartyMjs(rootDirectory = process.cwd()) {
     const canonical = resolveCanonicalRepoRoot(rootDirectory);