avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/avorelo-workstream-preflight.js

@@ -0,0 +1,918 @@
+"use strict";
+
+// Avorelo Workstream Preflight v1
+// ---------------------------------------------------------------------------
+// Internal-only workflow guard. Given a proposed workstream description, it
+// returns a deterministic decision about whether the work is safe to start,
+// already tracked, parallel-owned, blocked by an open PR, or needs an audit.
+//
+// Architecture boundary (hard):
+//   - deterministic-first, local-first, source-of-truth driven
+//   - read-only against roadmap / ownership / follow-up files
+//   - NO model calls, NO network calls, NO GitHub API calls
+//   - NO runtime / hook / dashboard / redaction / routing / verify imports
+//   - compact text output by default; stable JSON with --json
+//
+// It CONSUMES (read-only) the governance sources owned by other PRs. It does
+// NOT reimplement capability hygiene (#212), dogfood freshness (#212),
+// artifact/receipt hygiene (#212), the roadmap ledger or follow-up register
+// (#213). It only reads them and renders a preflight verdict.
+//
+// The ONLY runtime dependencies are the Node core `fs` and `path` modules.
+
+const fs = require("fs");
+const path = require("path");
+
+const SCHEMA_VERSION = "avorelo.workstreamPreflight.v1";
+
+const DECISIONS = Object.freeze({
+  SAFE_TO_START: "safe_to_start",
+  PARALLEL_OWNED: "parallel_owned",
+  BLOCKED_BY_OPEN_PR: "blocked_by_open_pr",
+  NEEDS_AUDIT: "needs_audit",
+  ALREADY_TRACKED: "already_tracked",
+  ALREADY_SHIPPED: "already_shipped",
+  UNCLEAR: "unclear",
+});
+
+// Repo root resolved relative to this file so the tool works regardless of cwd.
+const REPO_ROOT = path.resolve(__dirname, "..");
+
+// Source-of-truth files (read-only). Relative paths are also used as evidenceRefs.
+const SOURCES = Object.freeze({
+  ownershipRegistry: "docs/internal/capability-ownership-registry.md",
+  integrationChecklist: "docs/internal/feature-integration-checklist.md",
+  roadmapLedgerMd: "docs/internal/roadmap-state-ledger.md",
+  roadmapLedgerJson: "artifacts/roadmap/roadmap-state-ledger.v1.json",
+  followUpRegisterMd: "docs/internal/follow-up-debt-register.md",
+  followUpRegisterJson: "artifacts/roadmap/follow-up-debt-register.v1.json",
+  roadmapLedgerDogfood: "artifacts/roadmap/avorelo-roadmap-ledger-dogfood.v1.json",
+  // Consumed read-only by the proof-plan layer (registry-backed validator selection).
+  validationRegistry: "artifacts/roadmap/validation-registry.v1.json",
+  packageJson: "package.json",
+});
+
+// Stable schema for the registry-backed proof plan attached to every decision.
+const PROOF_PLAN_SCHEMA_VERSION = "avorelo.preflightProofPlan.v1";
+
+// Decision-keyed safe next action for the proof plan. Advisory only.
+const PROOF_PLAN_NEXT_ACTION = Object.freeze({
+  safe_to_start: "Proceed in a clean isolated worktree; rerun guard before commit/push.",
+  already_shipped: "Do not rebuild; inspect existing merged feature before proposing changes.",
+  already_tracked: "Continue only if this session owns the tracked follow-up; otherwise stop and report.",
+  blocked_by_open_pr: "Do not duplicate; inspect the active PR or ask user to assign ownership.",
+  parallel_owned: "Do not touch owner's files; coordinate with owning workstream.",
+  needs_audit: "Stop implementation until audit scope is explicit.",
+  unclear: "Clarify scope or add source-of-truth before implementation.",
+});
+
+// ---------------------------------------------------------------------------
+// Deterministic mapping tables (local, static, no I/O).
+// ---------------------------------------------------------------------------
+
+// Known open-PR domains. Matching any phrase => blocked_by_open_pr.
+const OPEN_PR_DOMAINS = [
+  {
+    pr: 166,
+    domain: "public-web/articles",
+    ownerDomain: "Public Narrative",
+    riskLevel: "medium",
+    phrases: [
+      "public articles",
+      "public article",
+      "articles",
+      "knowledge hub",
+      "public launch hub",
+      "public launch articles",
+      "launch hub",
+    ],
+  },
+  {
+    pr: 77,
+    domain: "tool-output-redaction",
+    ownerDomain: "Tool-Output Redaction (open PR)",
+    riskLevel: "high",
+    phrases: [
+      "secret redaction",
+      "tool output redaction",
+      "posttooluse redaction",
+      "post tool use redaction",
+      "output redaction",
+      "redaction",
+    ],
+  },
+  {
+    pr: 34,
+    domain: "smart-routing",
+    ownerDomain: "Smart-Routing Checks (open PR)",
+    riskLevel: "high",
+    phrases: ["smart routing", "routing checks", "routing check", "smart route", "routing"],
+  },
+  {
+    pr: 29,
+    domain: "verify-policy",
+    ownerDomain: "Verify Policy Runtime Contract (open PR)",
+    riskLevel: "high",
+    phrases: [
+      "verify policy",
+      "verify runtime",
+      "verify runtime policy",
+      "suggest lighter run",
+      "suggest_lighter_run",
+    ],
+  },
+];
+
+// Known parallel-owned domains (owned by parallel sessions / PR #212 hygiene pack).
+// Matching any phrase => parallel_owned.
+const PARALLEL_OWNED_DOMAINS = [
+  {
+    key: "capability-hygiene",
+    ownerDomain: "Capability Inventory and Contracts",
+    phrases: ["capability hygiene", "over skilling", "overskilling", "over-skilling"],
+  },
+  {
+    key: "dogfood-freshness",
+    ownerDomain: "Capability Inventory and Contracts",
+    phrases: ["dogfood freshness", "dogfood evidence freshness", "evidence freshness"],
+  },
+  {
+    key: "artifact-receipt-hygiene",
+    ownerDomain: "Proof Evidence",
+    phrases: [
+      "artifact receipt hygiene",
+      "artifact and receipt hygiene",
+      "receipt hygiene",
+      "local artifact hygiene",
+      "artifact hygiene",
+    ],
+  },
+];
+
+// Known needs-audit domains: runtime/product-surface wiring that must be audited
+// before implementation. Matching any phrase => needs_audit.
+const NEEDS_AUDIT_DOMAINS = [
+  {
+    key: "run-contract-dashboard",
+    ownerDomain: "Dashboard / Status Aggregation",
+    phrases: ["wire run contract into dashboard", "run contract dashboard", "dashboard wiring", "dashboard"],
+  },
+  {
+    key: "run-contract-next-run",
+    ownerDomain: "Next-Run Continuity",
+    phrases: [
+      "wire run contract into next run",
+      "run contract next run",
+      "next run wiring",
+      "next-run wiring",
+      "next run continuity wiring",
+    ],
+  },
+  {
+    key: "safe-run-controller",
+    ownerDomain: "Action Policy",
+    phrases: ["safe run controller", "safe-run-controller integration", "run controller integration"],
+  },
+  {
+    key: "runtime-hook-wiring",
+    ownerDomain: "Action Policy",
+    phrases: ["runtime hook wiring", "hook wiring", "runtime hook", "hook controller", "runtime controller"],
+  },
+  {
+    key: "browser-proof-runtime",
+    ownerDomain: "Proof Evidence",
+    phrases: ["browser proof runtime", "live browser proof", "browser proof qa"],
+  },
+  {
+    key: "deploy-publish-runtime",
+    ownerDomain: "Action Policy",
+    phrases: ["deploy controller", "publish controller", "deploy publish runtime", "runtime wiring"],
+  },
+];
+
+// Safe internal-governance work. Matching any phrase => safe_to_start.
+const SAFE_INTERNAL_DOMAINS = [
+  "roadmap ownership reconciliation",
+  "ownership reconciliation",
+  "internal docs consistency",
+  "ownership registry cleanup",
+  "registry cleanup",
+  "follow up debt reconciliation",
+  "follow-up debt reconciliation",
+  "validator docs for governance",
+  "validator docs",
+  "governance docs",
+  "internal docs",
+];
+
+// Baseline areas this internal guard workstream must never touch.
+const BASELINE_FORBIDDEN_AREAS = Object.freeze([
+  "runtime",
+  "hooks / controllers",
+  "dashboard",
+  "public web / articles / design",
+  "secret redaction runtime",
+  "smart routing",
+  "verify policy runtime",
+  "next-run wiring",
+  "safe-run-controller",
+  "billing / pricing / version / deploy / publish",
+  "package.json / package-lock",
+]);
+
+// ---------------------------------------------------------------------------
+// Source loading (read-only, fail-open).
+// ---------------------------------------------------------------------------
+
+function readJsonSafe(relPath) {
+  try {
+    const abs = path.join(REPO_ROOT, relPath);
+    if (!fs.existsSync(abs)) return null;
+    return JSON.parse(fs.readFileSync(abs, "utf8"));
+  } catch (_err) {
+    return null;
+  }
+}
+
+function loadSources() {
+  const ledger = readJsonSafe(SOURCES.roadmapLedgerJson);
+  const register = readJsonSafe(SOURCES.followUpRegisterJson);
+  // Read-only consumption of the Validation Registry catalogue (#217) and the
+  // package.json script map. Both are fail-open: a missing/corrupt source must
+  // never break the preflight decision, only the proof plan availability.
+  const registry = readJsonSafe(SOURCES.validationRegistry);
+  const pkg = readJsonSafe(SOURCES.packageJson);
+  return {
+    features: ledger && Array.isArray(ledger.features) ? ledger.features : [],
+    followUps: register && Array.isArray(register.followUps) ? register.followUps : [],
+    ledgerPresent: !!ledger,
+    registerPresent: !!register,
+    registry: registry || null,
+    registryEntries: registry && Array.isArray(registry.entries) ? registry.entries : null,
+    registryPresent: !!registry,
+    pkgScripts: pkg && pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {},
+  };
+}
+
+function repoFileExists(relPath) {
+  try {
+    return fs.existsSync(path.join(REPO_ROOT, relPath));
+  } catch (_err) {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Matching helpers (pure).
+// ---------------------------------------------------------------------------
+
+function normalize(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()
+    .replace(/\s+/g, " ");
+}
+
+function stripVersion(phrase) {
+  return phrase.replace(/\bv\d+\b/g, "").replace(/\s+/g, " ").trim();
+}
+
+function matchAny(normInput, phrases) {
+  for (const p of phrases) {
+    const np = normalize(p);
+    if (np && normInput.includes(np)) return p;
+  }
+  return null;
+}
+
+function slugify(text) {
+  return normalize(text).replace(/\s+/g, "-").slice(0, 60).replace(/^-+|-+$/g, "");
+}
+
+// ---------------------------------------------------------------------------
+// Core decision (deterministic, precedence-ordered).
+// ---------------------------------------------------------------------------
+
+function classify(rawInput, sourcesOverride) {
+  const input = String(rawInput == null ? "" : rawInput).trim();
+  const normInput = normalize(input);
+  const sources = sourcesOverride || loadSources();
+
+  const base = {
+    schemaVersion: SCHEMA_VERSION,
+    input,
+    decision: DECISIONS.UNCLEAR,
+    matchedDomains: [],
+    matchedFeatures: [],
+    matchedFollowUps: [],
+    blockedByOpenPRs: [],
+    parallelOwned: false,
+    ownerDomain: null,
+    riskLevel: "unknown",
+    safeBranchName: input ? `avorelo-${slugify(input)}-v1` : null,
+    requiredValidators: [],
+    forbiddenAreas: BASELINE_FORBIDDEN_AREAS.slice(),
+    safeNextAction: null,
+    confidence: "estimated",
+    evidenceRefs: [],
+  };
+
+  // Empty / too-vague input => unclear immediately.
+  if (!input || normInput.split(" ").filter(Boolean).length === 0) {
+    base.safeNextAction =
+      "Describe the proposed workstream in concrete terms (domain, files, intent) and re-run preflight.";
+    return base;
+  }
+
+  // 1) blocked_by_open_pr — highest precedence (hard external conflict).
+  for (const d of OPEN_PR_DOMAINS) {
+    const hit = matchAny(normInput, d.phrases);
+    if (hit) {
+      return Object.assign(base, {
+        decision: DECISIONS.BLOCKED_BY_OPEN_PR,
+        matchedDomains: [d.domain],
+        blockedByOpenPRs: [d.pr],
+        ownerDomain: d.ownerDomain,
+        riskLevel: d.riskLevel,
+        confidence: "measured",
+        requiredValidators: validatorsForOpenPr(d),
+        evidenceRefs: [SOURCES.roadmapLedgerJson, SOURCES.followUpRegisterJson],
+        safeNextAction: `Reconcile open PR #${d.pr} (${d.domain}) before starting new ${d.domain} work; do not open a parallel change to this domain.`,
+      });
+    }
+  }
+
+  // 2) parallel_owned — owned by a parallel session / hygiene pack.
+  for (const d of PARALLEL_OWNED_DOMAINS) {
+    const hit = matchAny(normInput, d.phrases);
+    if (hit) {
+      const followUp = findParallelFollowUp(sources.followUps, d.key);
+      return Object.assign(base, {
+        decision: DECISIONS.PARALLEL_OWNED,
+        matchedDomains: [d.key],
+        matchedFollowUps: followUp ? [followUp.followUpId] : [],
+        parallelOwned: true,
+        ownerDomain: d.ownerDomain,
+        riskLevel: "medium",
+        confidence: followUp ? "measured" : "inferred",
+        requiredValidators: ["npm run validate:follow-up-debt"],
+        evidenceRefs: [SOURCES.followUpRegisterJson, SOURCES.followUpRegisterMd],
+        safeNextAction:
+          "Continue only in the owning parallel workstream (Capability & Evidence Hygiene Pack), not here. Do not duplicate.",
+      });
+    }
+  }
+
+  // 3) needs_audit — runtime / product-surface wiring.
+  for (const d of NEEDS_AUDIT_DOMAINS) {
+    const hit = matchAny(normInput, d.phrases);
+    if (hit) {
+      const followUp = findNeedsAuditFollowUp(sources.followUps, normInput);
+      return Object.assign(base, {
+        decision: DECISIONS.NEEDS_AUDIT,
+        matchedDomains: [d.key],
+        matchedFollowUps: followUp ? [followUp.followUpId] : [],
+        ownerDomain: d.ownerDomain,
+        riskLevel: d.key === "safe-run-controller" ? "critical" : "high",
+        confidence: followUp ? "measured" : "inferred",
+        requiredValidators: ["npm run validate:run-contract", "runtime audit (separate workstream)"],
+        evidenceRefs: [SOURCES.followUpRegisterJson, SOURCES.roadmapLedgerJson],
+        safeNextAction:
+          "Open a separate runtime audit before any implementation; this touches runtime/product surface and must not be wired here.",
+      });
+    }
+  }
+
+  // 4) already_shipped — matches a merged feature in the roadmap ledger.
+  const feature = matchFeature(normInput, sources.features);
+  if (feature) {
+    return Object.assign(base, {
+      decision: DECISIONS.ALREADY_SHIPPED,
+      matchedFeatures: [feature.featureId],
+      matchedDomains: feature.ownerDomain ? [feature.ownerDomain] : [],
+      ownerDomain: feature.ownerDomain || null,
+      riskLevel: "low",
+      confidence: "measured",
+      requiredValidators: ["npm run validate:roadmap-state", "npm run validate:capability-ownership"],
+      evidenceRefs: [SOURCES.roadmapLedgerJson, SOURCES.roadmapLedgerMd],
+      safeNextAction: `"${feature.featureName}" (PR #${feature.pr}) is already merged and owned by ${feature.ownerDomain}. Extend via its owner; do not rebuild.`,
+    });
+  }
+
+  // 5) already_tracked — matches a non-blocking follow-up already registered.
+  const followUp = matchTrackedFollowUp(normInput, sources.followUps);
+  if (followUp) {
+    return Object.assign(base, {
+      decision: DECISIONS.ALREADY_TRACKED,
+      matchedFollowUps: [followUp.followUpId],
+      matchedDomains: followUp.ownerDomain ? [followUp.ownerDomain] : [],
+      ownerDomain: followUp.ownerDomain || null,
+      riskLevel: followUp.riskLevel || "low",
+      confidence: "measured",
+      requiredValidators: ["npm run validate:follow-up-debt"],
+      evidenceRefs: [SOURCES.followUpRegisterJson, SOURCES.followUpRegisterMd],
+      safeNextAction: `Already tracked as follow-up "${followUp.title}" (status: ${followUp.status}). Advance it per the register; do not open a duplicate workstream.`,
+    });
+  }
+
+  // 6) safe_to_start — internal governance with no overlap.
+  const safeHit = matchAny(normInput, SAFE_INTERNAL_DOMAINS);
+  if (safeHit) {
+    return Object.assign(base, {
+      decision: DECISIONS.SAFE_TO_START,
+      matchedDomains: ["internal-governance"],
+      ownerDomain: "Internal Governance",
+      riskLevel: "low",
+      confidence: "inferred",
+      requiredValidators: [
+        "npm run validate:capability-ownership",
+        "npm run validate:roadmap-state",
+        "npm run validate:follow-up-debt",
+      ],
+      evidenceRefs: [SOURCES.ownershipRegistry, SOURCES.roadmapLedgerJson, SOURCES.followUpRegisterJson],
+      safeNextAction:
+        "Safe to start. Begin with ownership registry and roadmap ledger checks; keep changes internal and read-only against runtime/public surfaces.",
+    });
+  }
+
+  // 7) unclear — fallback.
+  return Object.assign(base, {
+    decision: DECISIONS.UNCLEAR,
+    confidence: "estimated",
+    safeNextAction:
+      "Not matched against any known domain, feature, or follow-up. Narrow the description (which subsystem, which files) and re-run, or run a manual ownership check.",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point: classify, then attach a registry-backed proof plan.
+//
+// The proof plan is ADVISORY. It recommends which validators/checks should be
+// run to prove the work is safe to proceed — it NEVER runs a validator, never
+// claims a validator passed, and never invents a validator. Every registry-
+// backed item is sourced from the Validation Registry (#217). The classification
+// decision is computed first and is never changed by the proof plan.
+// ---------------------------------------------------------------------------
+
+function preflight(rawInput, sourcesOverride) {
+  const sources = sourcesOverride || loadSources();
+  const result = classify(rawInput, sources);
+  result.proofPlan = buildProofPlan(result, sources);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Deterministic, registry-backed proof-plan selection.
+// ---------------------------------------------------------------------------
+
+function buildProofPlan(result, sources) {
+  const decision = result.decision;
+  const safeNextAction = PROOF_PLAN_NEXT_ACTION[decision] || PROOF_PLAN_NEXT_ACTION.unclear;
+  const registryRef = SOURCES.validationRegistry;
+
+  // --- fail-open: no usable registry -> decision preserved, plan not_available.
+  const rawEntries =
+    sources && Array.isArray(sources.registryEntries)
+      ? sources.registryEntries
+      : sources && sources.registry && Array.isArray(sources.registry.entries)
+      ? sources.registry.entries
+      : null;
+
+  const byId = new Map();
+  if (rawEntries) {
+    for (const e of rawEntries) {
+      if (
+        e &&
+        typeof e.validatorId === "string" &&
+        typeof e.command === "string" &&
+        !byId.has(e.validatorId)
+      ) {
+        byId.set(e.validatorId, e);
+      }
+    }
+  }
+
+  if (!rawEntries || byId.size === 0) {
+    return {
+      schemaVersion: PROOF_PLAN_SCHEMA_VERSION,
+      status: "not_available",
+      required: [],
+      recommended: [],
+      notRequired: [],
+      notes: [
+        "Validation Registry is missing, unreadable, or has no usable entries; proof plan unavailable. The preflight decision above is unaffected — do not block solely because the proof plan is unavailable.",
+      ],
+      safeNextAction,
+      evidenceRefs: [registryRef],
+    };
+  }
+
+  const pkgScripts = (sources && sources.pkgScripts) || {};
+  const normInput = normalize(result.input);
+  const has = (s) => normInput.includes(normalize(s));
+
+  // Deterministic signal flags derived from the workstream description.
+  const sig = {
+    registry: has("validation registry") || has("validator") || has("run matrix") || has("proof plan"),
+    roadmap:
+      has("roadmap") ||
+      has("ledger") ||
+      has("follow up") ||
+      has("debt") ||
+      has("stale pr") ||
+      has("open workstream"),
+    governance:
+      has("governance") ||
+      has("ownership") ||
+      has("source of truth") ||
+      has("internal docs") ||
+      has("reconciliation") ||
+      has("preflight") ||
+      has("workstream"),
+    context: has("context compiler") || has("project knowledge") || has("context") || has("memory"),
+    capability: has("capability") || has("capability kernel") || has("capability contract") || has("skill contract"),
+    sessionCollision:
+      has("session collision") ||
+      has("force push") ||
+      has("dirty tree") ||
+      has("worktree") ||
+      has("branch") ||
+      has("push"),
+    activation: has("activation") || has("always on") || has("activate") || has("run entry"),
+    publicWeb:
+      has("public web") ||
+      has("article") ||
+      has("landing") ||
+      has("pricing") ||
+      has("signup") ||
+      has("visual") ||
+      has("design") ||
+      has("public"),
+    runtime:
+      has("runtime") ||
+      has("hook") ||
+      has("controller") ||
+      has("redaction") ||
+      has("routing") ||
+      has("verify") ||
+      has("policy"),
+  };
+
+  const required = [];
+  const recommended = [];
+  const notRequired = [];
+  const notes = [];
+  const seen = new Set();
+
+  // Add a registry-backed validator. Returns false (and adds nothing) if the
+  // validator does not exist in the registry — we never invent validators.
+  function addReg(list, validatorId, reason) {
+    const e = byId.get(validatorId);
+    if (!e) return false;
+    if (seen.has(validatorId)) return false;
+    seen.add(validatorId);
+    list.push({ validatorId, command: e.command, reason, source: "validation-registry" });
+    return true;
+  }
+
+  // Add a non-registry check that is verified to exist (npm script or repo test).
+  function addVerified(list, validatorId, command, reason, source) {
+    if (seen.has(validatorId)) return false;
+    seen.add(validatorId);
+    list.push({ validatorId, command, reason, source });
+    return true;
+  }
+
+  const governanceContext = sig.governance || sig.roadmap || sig.registry || sig.capability || sig.context;
+
+  // Rule 1 — minimal governance checks for internal governance/source-of-truth work.
+  if (governanceContext) {
+    addReg(
+      required,
+      "capability-ownership",
+      "Confirm one owner per decision domain before extending governance source-of-truth."
+    );
+  }
+  if (sig.registry) {
+    addReg(
+      required,
+      "validation-registry",
+      "Confirm the Validation Registry catalogue is well-formed before relying on it for a proof plan."
+    );
+  }
+  if (sig.roadmap || sig.governance) {
+    addReg(
+      required,
+      "roadmap-ownership-reconciliation",
+      "Confirm roadmap ledger, debt register, and ownership registry reconcile before workstream/PR tracking changes."
+    );
+  }
+
+  // Rule 2 — roadmap / ledger / follow-up / debt / open-workstream work.
+  if (sig.roadmap) {
+    addReg(required, "roadmap-state", "Confirm the roadmap feature inventory is well-formed.");
+    addReg(required, "follow-up-debt", "Confirm follow-up/debt items are well-formed and deduplicated.");
+  }
+
+  // Rule 4 — context compiler / context / project knowledge / memory.
+  if (sig.context) {
+    addReg(
+      required,
+      "context-compiler",
+      "Confirm source-of-truth context selection, authority ranking, and claim-safety filtering behave as specified."
+    );
+  }
+
+  // Rule 5 — capability / capability kernel / capability-or-skill contract.
+  if (sig.capability) {
+    addReg(required, "capability-contracts", "Confirm capability manifests carry required contract fields.");
+    addReg(required, "capability-ownership", "Confirm a single, non-duplicate owner for the capability domain.");
+  }
+
+  // Rule 6 — session collision / branch / push / worktree (not in registry).
+  if (sig.sessionCollision && !sig.activation) {
+    if (!addReg(recommended, "session-collision-guard", "Re-check branch/worktree collision state before push.")) {
+      if (pkgScripts["validate:session-collision-guard"]) {
+        addVerified(
+          recommended,
+          "session-collision-guard",
+          "npm run validate:session-collision-guard",
+          "Re-check branch/worktree collision state before push (registry has no entry; npm script verified present).",
+          "package-script"
+        );
+      }
+    }
+  }
+
+  // Rule 7 — activation / always-on / activate / run entry.
+  if (sig.activation) {
+    if (!addReg(required, "session-collision-guard", "Confirm no session collision before activation-adjacent work.")) {
+      if (pkgScripts["validate:session-collision-guard"]) {
+        addVerified(
+          required,
+          "session-collision-guard",
+          "npm run validate:session-collision-guard",
+          "Activation work shares branches/worktrees; confirm no session collision before proceeding.",
+          "package-script"
+        );
+      }
+    }
+    if (repoFileExists("tests/workstream-preflight.test.js")) {
+      addVerified(
+        required,
+        "workstream-preflight",
+        "node --test tests/workstream-preflight.test.js",
+        "Confirm preflight classification still holds for activation-adjacent work.",
+        "repo-check"
+      );
+    }
+    notes.push(
+      "Activation work may be active in another session; use an isolated worktree and do not touch activation-owned files."
+    );
+  }
+
+  // Rule 8 — public-web / article / landing / pricing / signup / visual / design.
+  if (sig.publicWeb) {
+    notes.push(
+      "Public/design work requires current public-web source-of-truth and visual QA; this proof plan is NOT design or launch approval and must not be treated as such."
+    );
+    addReg(
+      recommended,
+      "public-narrative",
+      "Claim-safety check for public language. Does not prove the site is deployed, design-approved, or production-ready."
+    );
+  }
+
+  // Rule 9 — runtime / hook / controller / redaction / routing / verify / policy.
+  if (sig.runtime) {
+    addReg(
+      required,
+      "capability-ownership",
+      "Governance ownership check only; runtime wiring needs a separate audit, not this proof plan."
+    );
+    notes.push(
+      "Runtime-adjacent work (runtime/hook/controller/redaction/routing/verify/policy) requires a separate runtime/security audit before implementation; this proof plan does not authorize runtime changes."
+    );
+  }
+
+  // Rule 10 — no specific mapping: generic safe checks only.
+  if (required.length === 0 && recommended.length === 0) {
+    addReg(
+      recommended,
+      "capability-ownership",
+      "Generic ownership safety check; proceed only if scope is clear and Session Collision Guard is safe."
+    );
+  }
+
+  return {
+    schemaVersion: PROOF_PLAN_SCHEMA_VERSION,
+    status: "available",
+    required,
+    recommended,
+    notRequired,
+    notes,
+    safeNextAction,
+    evidenceRefs: [registryRef],
+  };
+}
+
+// --- match helpers against loaded sources ---
+
+function validatorsForOpenPr(d) {
+  switch (d.pr) {
+    case 166:
+      return ["npm run validate:public-narrative"];
+    case 29:
+      return ["npm run validate:run-contract"];
+    default:
+      return ["npm run validate:capability-ownership"];
+  }
+}
+
+function findParallelFollowUp(followUps, key) {
+  const keyTokens = {
+    "capability-hygiene": "capability-hygiene",
+    "dogfood-freshness": "dogfood-evidence-freshness",
+    "artifact-receipt-hygiene": "artifact-receipt-hygiene",
+  }[key];
+  return (
+    followUps.find(
+      (f) => f.parallelSessionOwned === true && keyTokens && String(f.followUpId).includes(keyTokens)
+    ) || followUps.find((f) => f.parallelSessionOwned === true && key && String(f.followUpId).includes(key)) || null
+  );
+}
+
+function findNeedsAuditFollowUp(followUps, normInput) {
+  return (
+    followUps.find((f) => {
+      if (f.status !== "needs-audit") return false;
+      const t = normalize(f.title);
+      // crude overlap: share a distinctive token like dashboard / next run / controller
+      return (
+        (normInput.includes("dashboard") && t.includes("dashboard")) ||
+        (normInput.includes("next run") && t.includes("next-run")) ||
+        (normInput.includes("next run") && t.includes("next run")) ||
+        (normInput.includes("controller") && t.includes("controller")) ||
+        (normInput.includes("browser proof") && t.includes("browser-proof"))
+      );
+    }) || null
+  );
+}
+
+function matchFeature(normInput, features) {
+  for (const f of features) {
+    const candidates = [stripVersion(normalize(f.featureName)), stripVersion(normalize(f.featureId))];
+    for (const c of candidates) {
+      const words = c.split(" ").filter(Boolean);
+      if (words.length >= 2 && normInput.includes(c)) return f;
+    }
+  }
+  return null;
+}
+
+function matchTrackedFollowUp(normInput, followUps) {
+  for (const f of followUps) {
+    if (f.parallelSessionOwned === true) continue; // parallel handled earlier
+    if (f.status === "needs-audit" || f.status === "blocked") continue; // handled earlier
+    const t = normalize(f.title);
+    const tokens = t.split(" ").filter((w) => w.length >= 4);
+    // require at least 2 distinctive tokens to co-occur to avoid loose matches
+    const overlap = tokens.filter((w) => normInput.includes(w));
+    if (overlap.length >= 2) return f;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Rendering.
+// ---------------------------------------------------------------------------
+
+function formatText(result) {
+  const lines = [];
+  lines.push(`Workstream Preflight: ${result.decision}`);
+  lines.push(`Reason: ${reasonFor(result)}`);
+  lines.push(`Safe next action: ${result.safeNextAction}`);
+  // compact detail line
+  const detail = [];
+  if (result.ownerDomain) detail.push(`owner=${result.ownerDomain}`);
+  detail.push(`risk=${result.riskLevel}`);
+  if (result.blockedByOpenPRs.length) detail.push(`openPRs=${result.blockedByOpenPRs.join(",")}`);
+  if (result.safeBranchName) detail.push(`branch=${result.safeBranchName}`);
+  detail.push(`confidence=${result.confidence}`);
+  lines.push(detail.join("  "));
+  appendProofPlanText(lines, result.proofPlan);
+  return lines.join("\n");
+}
+
+// Compact proof-plan rendering. Full plan (reasons, notes, evidence) lives in
+// --json; the text view caps visible validators to stay terminal-friendly.
+function appendProofPlanText(lines, plan, cap = 4) {
+  if (!plan) return;
+  if (plan.status !== "available") {
+    lines.push("Proof plan: not_available (Validation Registry unavailable; decision unaffected)");
+    lines.push(`Proof next action: ${plan.safeNextAction}`);
+    return;
+  }
+  lines.push("Proof plan: available");
+  const fmt = (items) => {
+    const ids = items.map((i) => i.validatorId);
+    const shown = ids.slice(0, cap).join(", ");
+    const extra = ids.length > cap ? ` (+${ids.length - cap} more — see --json)` : "";
+    return shown + extra;
+  };
+  if (plan.required.length) lines.push(`- Required: ${fmt(plan.required)}`);
+  if (plan.recommended.length) lines.push(`- Recommended: ${fmt(plan.recommended)}`);
+  if (!plan.required.length && !plan.recommended.length) lines.push("- Required: none");
+  lines.push(`Proof next action: ${plan.safeNextAction}`);
+}
+
+function reasonFor(result) {
+  switch (result.decision) {
+    case DECISIONS.BLOCKED_BY_OPEN_PR:
+      return `${result.matchedDomains[0]} work is represented by open PR #${result.blockedByOpenPRs[0]}.`;
+    case DECISIONS.PARALLEL_OWNED:
+      return `${result.matchedDomains[0]} is owned by a parallel session (Capability & Evidence Hygiene Pack) / tracked as parallel-owned.`;
+    case DECISIONS.NEEDS_AUDIT:
+      return `this touches runtime/product surface (${result.matchedDomains[0]}) and requires an audit first.`;
+    case DECISIONS.ALREADY_SHIPPED:
+      return `this matches a merged feature already recorded in the roadmap ledger (${result.matchedFeatures[0]}).`;
+    case DECISIONS.ALREADY_TRACKED:
+      return `this matches a follow-up already in the debt register (${result.matchedFollowUps[0]}).`;
+    case DECISIONS.SAFE_TO_START:
+      return "internal governance work does not overlap open PRs or runtime-sensitive domains.";
+    default:
+      return "input did not match any known domain, merged feature, or tracked follow-up.";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI.
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  let json = false;
+  const rest = [];
+  for (const a of argv) {
+    if (a === "--json") json = true;
+    else if (a === "--help" || a === "-h") return { help: true };
+    else rest.push(a);
+  }
+  return { json, input: rest.join(" ").trim() };
+}
+
+function helpText() {
+  return [
+    "Avorelo Workstream Preflight v1 (internal)",
+    "",
+    "Usage:",
+    '  node scripts/avorelo-workstream-preflight.js "<proposed workstream>"',
+    '  node scripts/avorelo-workstream-preflight.js --json "<proposed workstream>"',
+    "",
+    "Decisions: safe_to_start | parallel_owned | blocked_by_open_pr | needs_audit |",
+    "           already_tracked | already_shipped | unclear",
+    "",
+    "Read-only. No network, no model, no GitHub API calls.",
+  ].join("\n");
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(helpText() + "\n");
+    return 0;
+  }
+  const result = preflight(args.input);
+  if (args.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else {
+    process.stdout.write(formatText(result) + "\n");
+  }
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  PROOF_PLAN_SCHEMA_VERSION,
+  PROOF_PLAN_NEXT_ACTION,
+  DECISIONS,
+  SOURCES,
+  REPO_ROOT,
+  OPEN_PR_DOMAINS,
+  PARALLEL_OWNED_DOMAINS,
+  NEEDS_AUDIT_DOMAINS,
+  SAFE_INTERNAL_DOMAINS,
+  BASELINE_FORBIDDEN_AREAS,
+  preflight,
+  classify,
+  buildProofPlan,
+  formatText,
+  loadSources,
+  normalize,
+  parseArgs,
+  main,
+};