@mstar-harness/engine 3.2.6 → 3.3.0

package/dist/audit.d.ts

@@ -78,6 +78,15 @@ export type ScaffoldAuditPlanOptions = {
         title: string;
         reason: string;
     }[];
+    needsVerification?: readonly {
+        lead: string;
+        how: string;
+        evidence?: string;
+    }[];
+    hardeningChecked?: readonly {
+        kind: "Hardening" | "Checked and clean";
+        text: string;
+    }[];
 };
 /** Result of `scaffoldAuditPlan`. `nextNumber` is the next free plan number
  * (monotonic continuation vs. any pre-existing `NNN-*.md` files). */
@@ -94,7 +103,12 @@ export type ScaffoldAuditPlanResult = {
  * directory already contains `NNN-*.md` files (same-date re-run), the new
  * batch continues after the highest existing number instead of restarting
  * at 001, and the rebuilt index includes the pre-existing plans. Rejected
- * findings render in the "considered and rejected" section.
+ * findings render in the "considered and rejected" section. Security
+ * dispositions (`needsVerification` / `hardeningChecked`) render in their
+ * documented index sections. Policy: a SUPPLIED option is the authoritative
+ * current set and replaces the section (resolved leads can be removed,
+ * revised entries updated); an OMITTED option carries the previous section
+ * over from the existing README so hand-added entries survive the rebuild.
  */
 export declare function scaffoldAuditPlan(outDir: string, findings: readonly AuditFinding[], options?: ScaffoldAuditPlanOptions): ScaffoldAuditPlanResult;
 /** Options for `promoteAuditPlans`. `harnessDir` is required — the snapshot

package/dist/audit.js

@@ -113,38 +113,6 @@ var CONFIG_KEYS = {
   [MSTARC_ENFORCEMENT_KEY]: "enforcement"
 };
 
-// src/path.ts
-function assertSafePathComponent(value, what) {
-  if (value === "" || value === "." || value === ".." || !/^[A-Za-z0-9._-]+$/.test(value)) {
-    throw new Error(`${what} must be a single safe path component ([A-Za-z0-9._-]+; not "", ".", "..", or containing "/" or "\\") — got ${JSON.stringify(value)}`);
-  }
-}
-var GITIGNORE_SNIPPET = `# Morning Star harness (.mstar/)
-# Principle: process stays local; results are shared with the team.
-# Default-ignore everything under .mstar/, then re-include the tracked results.
-.mstar/**
-!.mstar/AGENTS.md
-!.mstar/knowledge/
-!.mstar/knowledge/**
-!.mstar/specs/
-!.mstar/specs/**
-# .mstarc — repo-local harness config (may declare [config] harness_dir=<name>)
-.mstarc
-`;
-var GITIGNORE_SNIPPET_AGENTS = `# Morning Star harness (.agents/) — legacy
-# Default-ignore everything under .agents/, then re-include the tracked results.
-.agents/**
-!.agents/AGENTS.md
-!.agents/knowledge/
-!.agents/knowledge/**
-!.agents/specs/
-!.agents/specs/**
-`;
-var GITIGNORE_PROCESS_ENTRIES = GITIGNORE_SNIPPET.split(`
-`).filter((line) => line.startsWith(".mstar/") || line.startsWith("!.mstar/")).map((line) => line.trim());
-var GITIGNORE_PROCESS_ENTRIES_AGENTS = GITIGNORE_SNIPPET_AGENTS.split(`
-`).filter((line) => line.startsWith(".agents/") || line.startsWith("!.agents/")).map((line) => line.trim());
-
 // src/status.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync, realpathSync } from "node:fs";
 import { dirname as dirname3, join as join3, resolve as resolve3, sep } from "node:path";
@@ -336,6 +304,38 @@ function registerWorkflowEntryLocked(statusPath, entry) {
   return doc;
 }
 
+// src/path.ts
+function assertSafePathComponent(value, what) {
+  if (value === "" || value === "." || value === ".." || !/^[A-Za-z0-9._-]+$/.test(value)) {
+    throw new Error(`${what} must be a single safe path component ([A-Za-z0-9._-]+; not "", ".", "..", or containing "/" or "\\") — got ${JSON.stringify(value)}`);
+  }
+}
+var GITIGNORE_SNIPPET = `# Morning Star harness (.mstar/)
+# Principle: process stays local; results are shared with the team.
+# Default-ignore everything under .mstar/, then re-include the tracked results.
+.mstar/**
+!.mstar/AGENTS.md
+!.mstar/knowledge/
+!.mstar/knowledge/**
+!.mstar/specs/
+!.mstar/specs/**
+# .mstarc — repo-local harness config (may declare [config] harness_dir=<name>)
+.mstarc
+`;
+var GITIGNORE_SNIPPET_AGENTS = `# Morning Star harness (.agents/) — legacy
+# Default-ignore everything under .agents/, then re-include the tracked results.
+.agents/**
+!.agents/AGENTS.md
+!.agents/knowledge/
+!.agents/knowledge/**
+!.agents/specs/
+!.agents/specs/**
+`;
+var GITIGNORE_PROCESS_ENTRIES = GITIGNORE_SNIPPET.split(`
+`).filter((line) => line.startsWith(".mstar/") || line.startsWith("!.mstar/")).map((line) => line.trim());
+var GITIGNORE_PROCESS_ENTRIES_AGENTS = GITIGNORE_SNIPPET_AGENTS.split(`
+`).filter((line) => line.startsWith(".agents/") || line.startsWith("!.agents/")).map((line) => line.trim());
+
 // src/audit.ts
 function violation2(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
@@ -515,8 +515,17 @@ function readPlanFileSummary(filePath) {
   const blocks = parseStatusBlocks(text);
   return { title: title.trim(), fields: blocks.length > 0 ? blocks[0].fields : new Map };
 }
+function extractSecurityDispositionSections(text) {
+  const grab = (heading) => {
+    const match = text.match(new RegExp(`(?:^|\\r?\\n)##[ \\t]+${heading}[ \\t]*\\r?\\n(?:[ \\t]*\\r?\\n)?([\\s\\S]*?)(?=\\r?\\n## |$)`, "i"));
+    if (!match)
+      return [];
+    return match[1].split(/\r?\n/).map((line) => line.replace(/\r$/, "")).filter((line) => line.startsWith("- "));
+  };
+  return { needsVerification: grab("Needs verification"), hardeningChecked: grab("Hardening & checked notes") };
+}
 function renderIndex(params) {
-  const { date, repoName, repoShortSha, rows, rejected } = params;
+  const { date, repoName, repoShortSha, rows, rejected, needsVerification, hardeningChecked } = params;
   const findingsRows = rows.map((r) => `| ${r.num} | ${escapeCell(r.title)} | ${r.category} | ${escapeCell(truncate(r.impact, 80))} | ${r.effort} | ${r.risk} | ${r.confidence} | ${escapeCell(truncate(r.evidence, 80))} |`).join(`
 `);
   const directionRows = rows.filter((r) => r.category === "direction").map((r) => `- ${escapeCell(r.title)} — ${escapeCell(truncate(r.impact, 120))}`).join(`
@@ -537,6 +546,12 @@ function renderIndex(params) {
   if (directionRows !== "") {
     sections.push("", "## Direction", "", directionRows);
   }
+  if (needsVerification.length > 0) {
+    sections.push("", "## Needs verification", "", ...needsVerification);
+  }
+  if (hardeningChecked.length > 0) {
+    sections.push("", "## Hardening & checked notes", "", ...hardeningChecked);
+  }
   sections.push("", "## Execution order & status", "", "| Plan | Title | Priority | Effort | Depends on | Status |", "|------|-------|----------|--------|------------|--------|", executionRows);
   if (rejectedRows !== "") {
     sections.push("", "## Findings considered and rejected", "", rejectedRows);
@@ -550,6 +565,8 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
   const date = options.date ?? new Date().toISOString().slice(0, 10);
   const plannedAt = options.plannedAt ?? { commit: options.repoShortSha ?? "unknown", date };
   mkdirSync3(outDir, { recursive: true });
+  const existingReadme = join4(outDir, "README.md");
+  const carried = existsSync3(existingReadme) ? extractSecurityDispositionSections(readFileSync3(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
   const existing = readdirSync2(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
   let next = existing.reduce((max, f) => Math.max(max, Number(f.slice(0, 3))), 0) + 1;
   const written = [];
@@ -603,12 +620,16 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
       row.dependsOn = finding.dependsOn ?? "none";
     }
   });
+  const needsVerificationLines = options.needsVerification !== undefined ? options.needsVerification.map((nv) => `- ${escapeCell(nv.lead)}: ${escapeCell(nv.how)}${nv.evidence ? ` (${escapeCell(nv.evidence)})` : ""}`) : carried.needsVerification;
+  const hardeningCheckedLines = options.hardeningChecked !== undefined ? options.hardeningChecked.map((hc) => `- ${hc.kind}: ${escapeCell(hc.text)}`) : carried.hardeningChecked;
   writeFileSync3(join4(outDir, "README.md"), renderIndex({
     date,
     repoName: options.repoName ?? "repo",
     repoShortSha: options.repoShortSha ?? "unknown",
     rows,
-    rejected: options.rejected ?? []
+    rejected: options.rejected ?? [],
+    needsVerification: needsVerificationLines,
+    hardeningChecked: hardeningCheckedLines
   }));
   return { outDir: resolve4(outDir), date, files: written, nextNumber: next };
 }