@mrciphersmith/keryx 0.3.28 → 0.3.30

package/dist/core.js

@@ -21627,6 +21627,7 @@ init_validator();
 var exports_service2 = {};
 __export(exports_service2, {
   AC_CHECK_TOKEN_BUDGET: () => AC_CHECK_TOKEN_BUDGET,
+  AC_KINDS: () => AC_KINDS,
   CONFIRMATION_CAVEAT: () => CONFIRMATION_CAVEAT,
   REVIEW_GATE_CONFIG_PATH: () => REVIEW_GATE_CONFIG_PATH,
   acCheckCacheKey: () => acCheckCacheKey,
@@ -21636,10 +21637,13 @@ __export(exports_service2, {
   assertAcIntact: () => assertAcIntact,
   baseBranchCondition: () => baseBranchCondition,
   batchAcCheckItems: () => batchAcCheckItems,
+  buildAcKindReport: () => buildAcKindReport,
+  classifyAcCriterionNotCheckable: () => classifyAcCriterionNotCheckable,
   classifyNotCheckable: () => classifyNotCheckable,
   computeAcFacts: () => computeAcFacts,
   confirmPreconditionError: () => confirmPreconditionError,
   createFlowService: () => createFlowService,
+  describeAcKind: () => describeAcKind,
   evaluatedVerdict: () => evaluatedVerdict,
   extractCriterionTokens: () => extractCriterionTokens,
   factsOnlyVerdict: () => factsOnlyVerdict,
@@ -21649,12 +21653,16 @@ __export(exports_service2, {
   parseAcceptanceCriteria: () => parseAcceptanceCriteria,
   readAcCheckCache: () => readAcCheckCache,
   readAcCheckEnabled: () => readAcCheckEnabled,
+  readAcKindRecords: () => readAcKindRecords,
   readFlow: () => readFlow,
   renderAcCheckAdvisoryNotice: () => renderAcCheckAdvisoryNotice,
   renderAcCheckReport: () => renderAcCheckReport,
+  renderAcKindDistribution: () => renderAcKindDistribution,
+  reportFromRecords: () => reportFromRecords,
   resolveFlowDir: () => resolveFlowDir,
   selectMatchedHunks: () => selectMatchedHunks,
   statusLabel: () => statusLabel,
+  stripVerifyMarker: () => stripVerifyMarker,
   summarizeVerdicts: () => summarizeVerdicts,
   validateCriterionName: () => validateCriterionName,
   writeAcCheckCache: () => writeAcCheckCache
@@ -23979,6 +23987,161 @@ async function readRequireConfirmationDefault(cwd) {
     return false;
   }
 }
+// src/flow/ac-kinds.ts
+var AC_KINDS = ["exec", "invariant", "judged", "none", "unclassified"];
+var AC_LINE = /^\s*[-*]\s*(AC\d+)\s*:\s?(.*)$/i;
+var MARKER_OPEN = "[verify:";
+function maskCodeSpans(text) {
+  return text.replace(/`[^`]*`/g, (span) => " ".repeat(span.length));
+}
+function scanMarkers(text) {
+  const masked = maskCodeSpans(text);
+  let occurrences = 0;
+  let lastStart = -1;
+  for (let at = masked.indexOf(MARKER_OPEN);at !== -1; at = masked.indexOf(MARKER_OPEN, at + MARKER_OPEN.length)) {
+    occurrences += 1;
+    lastStart = at;
+  }
+  const end = text.trimEnd().length;
+  return { occurrences, lastStart, trailing: occurrences > 0 && end > lastStart && text[end - 1] === "]", end };
+}
+function stripVerifyMarker(text) {
+  const scan = scanMarkers(text);
+  if (!scan.trailing || scan.occurrences !== 1)
+    return text;
+  return text.slice(0, scan.lastStart).trimEnd();
+}
+var KIND_WORDS = "exec, invariant, judged or none";
+function unclassified(error) {
+  return error === undefined ? { record: { kind: "unclassified" } } : { record: { kind: "unclassified" }, error };
+}
+function parseAcKindText(text) {
+  const scan = scanMarkers(text);
+  if (scan.occurrences === 0)
+    return unclassified();
+  if (scan.occurrences > 1) {
+    return unclassified("a second [verify: \u2026] marker \u2014 a criterion carries exactly one, as the last thing on its line");
+  }
+  if (!scan.trailing) {
+    return unclassified("the [verify: \u2026] marker must be the last thing on the line and close with `]`");
+  }
+  const payload = text.slice(scan.lastStart + MARKER_OPEN.length, scan.end - 1).trim();
+  if (payload.length === 0)
+    return unclassified(`an empty [verify: \u2026] marker \u2014 expected ${KIND_WORDS}`);
+  const word = /^[A-Za-z]+/.exec(payload)?.[0] ?? "";
+  const rest = payload.slice(word.length).trim();
+  switch (word) {
+    case "judged":
+      return rest.length === 0 ? { record: { kind: "judged" } } : unclassified("`judged` takes no arguments \u2014 write [verify: judged]");
+    case "exec":
+    case "invariant": {
+      if (rest.length === 0)
+        return unclassified(`\`${word}\` requires a backticked command, e.g. [verify: ${word} \`bun test path/to.test.ts\`]`);
+      const command = /^`([^`]*)`$/.exec(rest);
+      if (command === null)
+        return unclassified(`\`${word}\` requires exactly one backticked command after the kind, e.g. [verify: ${word} \`bun test path/to.test.ts\`]`);
+      const check = (command[1] ?? "").trim();
+      if (check.length === 0)
+        return unclassified(`\`${word}\` has an empty backticked command`);
+      return { record: { kind: word, check } };
+    }
+    case "none": {
+      if (rest.length === 0)
+        return unclassified("`none` requires a reason after an em dash, e.g. [verify: none \u2014 <reason>]");
+      const reason = /^\u2014\s*([\s\S]*)$/.exec(rest);
+      if (reason === null)
+        return unclassified("`none` requires its reason after an em dash (\u2014), e.g. [verify: none \u2014 <reason>]");
+      const why = (reason[1] ?? "").trim();
+      if (why.length === 0)
+        return unclassified("`none` has an empty reason after the em dash");
+      return { record: { kind: "none", reason: why } };
+    }
+    default:
+      return unclassified(`unknown verification kind "${word.length > 0 ? word : payload}" \u2014 expected ${KIND_WORDS}`);
+  }
+}
+function parseAcKinds(content) {
+  const criteria = [];
+  const errors = [];
+  for (const line of content.split(/\r?\n/)) {
+    const match = AC_LINE.exec(line);
+    if (!match?.[1])
+      continue;
+    const id = match[1].toUpperCase();
+    const rawText = (match[2] ?? "").trim();
+    const parsed = parseAcKindText(rawText);
+    if (parsed.error !== undefined)
+      errors.push({ id, message: parsed.error });
+    criteria.push({ id, text: stripVerifyMarker(rawText), rawText, record: parsed.record });
+  }
+  return { criteria, errors };
+}
+function emptyCounts() {
+  return { exec: 0, invariant: 0, judged: 0, none: 0, unclassified: 0 };
+}
+function buildAcKindReport(flowId, content) {
+  const parsed = parseAcKinds(content);
+  const criteria = {};
+  for (const criterion of parsed.criteria) {
+    if (!(criterion.id in criteria))
+      criteria[criterion.id] = criterion.record;
+  }
+  return { report: reportFromRecords(flowId, criteria), errors: parsed.errors };
+}
+function reportFromRecords(flowId, criteria) {
+  const counts = emptyCounts();
+  for (const record of Object.values(criteria))
+    counts[record.kind] += 1;
+  return {
+    flowId,
+    criteria,
+    counts,
+    runnable: counts.exec + counts.invariant,
+    total: Object.keys(criteria).length
+  };
+}
+function renderAcKindDistribution(report) {
+  const { counts } = report;
+  const percent = report.total === 0 ? 0 : Math.round(report.runnable / report.total * 100);
+  const tail = [`${counts.none} accepted as unverifiable`, `${counts.judged} judged`, ...counts.unclassified > 0 ? [`${counts.unclassified} unclassified`] : []];
+  return [
+    `acceptance kinds: exec ${counts.exec}  invariant ${counts.invariant}  judged ${counts.judged}  none ${counts.none}  unclassified ${counts.unclassified}   (${report.total} criteria)`,
+    `coverage: ${report.runnable}/${report.total} runnable (${percent}%)  \xB7  ${tail.join("  \xB7  ")}`
+  ];
+}
+function describeAcKind(record) {
+  switch (record.kind) {
+    case "exec":
+    case "invariant":
+      return `${record.kind} \`${record.check}\``;
+    case "none":
+      return `none \u2014 ${record.reason}`;
+    default:
+      return record.kind;
+  }
+}
+function readAcKindRecords(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return;
+  const out = {};
+  for (const [id, raw] of Object.entries(value)) {
+    if (typeof raw !== "object" || raw === null)
+      return;
+    const record = raw;
+    const kind = record["kind"];
+    if ((kind === "exec" || kind === "invariant") && typeof record["check"] === "string")
+      out[id] = { kind, check: record["check"] };
+    else if (kind === "judged")
+      out[id] = { kind };
+    else if (kind === "none" && typeof record["reason"] === "string")
+      out[id] = { kind, reason: record["reason"] };
+    else if (kind === "unclassified")
+      out[id] = { kind };
+    else
+      return;
+  }
+  return out;
+}
 // src/flow/check-ac.ts
 import { createHash as createHash8 } from "crypto";
 import { chmod as chmod4, mkdir as mkdir9, readFile as readFile21 } from "fs/promises";
@@ -23992,11 +24155,11 @@ function estimateTokens(text) {
 // src/flow/check-ac.ts
 init_service2();
 init_fs();
-var AC_LINE = /^\s*[-*]\s*(AC\d+)\s*:\s?(.*)$/i;
+var AC_LINE2 = /^\s*[-*]\s*(AC\d+)\s*:\s?(.*)$/i;
 function parseAcceptanceCriteria(content) {
   const out = [];
   for (const line of content.split(/\r?\n/)) {
-    const match = AC_LINE.exec(line);
+    const match = AC_LINE2.exec(line);
     if (match?.[1]) {
       out.push({ id: match[1].toUpperCase(), text: (match[2] ?? "").trim() });
     }
@@ -24043,6 +24206,9 @@ function classifyNotCheckable(criterionText) {
     reason: `not-checkable: every clause of this criterion names a condition no diff records (${labels.join(", ")}) \u2014 assigned without asking Jev.`
   };
 }
+function classifyAcCriterionNotCheckable(criterion) {
+  return classifyNotCheckable(stripVerifyMarker(criterion.text));
+}
 function extractCriterionTokens(text) {
   const tokens = new Set;
   for (const match of text.matchAll(/`([^`]+)`/g)) {
@@ -24060,7 +24226,7 @@ function extractCriterionTokens(text) {
   return [...tokens];
 }
 function computeAcFacts(criterion, diffText, changedFiles) {
-  const tokens = extractCriterionTokens(criterion.text);
+  const tokens = extractCriterionTokens(stripVerifyMarker(criterion.text));
   const tokensPresent = tokens.filter((token) => diffText.includes(token) || changedFiles.some((file) => file.includes(token)));
   const tokensAbsent = tokens.filter((token) => !tokensPresent.includes(token));
   const testFiles = changedFiles.filter((file) => /\.(test|spec)\.[a-z]+$/i.test(file));
@@ -24086,7 +24252,7 @@ var AC_CHECK_TOKEN_BUDGET = 64000;
 function questionFor(criterion) {
   return {
     type: "noul",
-    instructions: `Given the deterministic facts and the redacted diff evidence above, does this change LIKELY SATISFY this frozen ` + `acceptance criterion? Criterion ${criterion.id}: ${redactSensitiveText(criterion.text)}`
+    instructions: `Given the deterministic facts and the redacted diff evidence above, does this change LIKELY SATISFY this frozen ` + `acceptance criterion? Criterion ${criterion.id}: ${redactSensitiveText(stripVerifyMarker(criterion.text))}`
   };
 }
 var MAX_MATCHED_HUNKS_PER_ITEM = 8;
@@ -24431,6 +24597,10 @@ function renderJournal(createdAt) {
 }
 
 // src/flow/service.ts
+async function deriveAcKinds(cwd, dir, flowId) {
+  const { report } = buildAcKindReport(flowId, await readFile23(acPath(cwd, dir), "utf8"));
+  return { ...report.criteria };
+}
 function recordAttempt(task, outcome, at, detail) {
   const attempts = task.attempts ?? { count: 0, log: [] };
   attempts.count += 1;
@@ -24628,6 +24798,7 @@ function createFlowService(deps) {
           throw new Error("Cannot freeze: acceptance-criteria.md must contain at least one real `- ACn:` criterion.");
         }
         flow.acChecksum = await acChecksum(cwd, dir);
+        flow.acKinds = await deriveAcKinds(cwd, dir, flow.id);
         flow.status = "ready";
         return save(cwd, dir, flow, "frozen", `${criteria.length} criteria; checksum recorded`);
       });
@@ -24772,10 +24943,15 @@ function createFlowService(deps) {
           detail = `${normalizedCriterion}: "${previousText ?? "(new)"}" -> "${normalizedText}" (${reason.trim()})`;
         }
         flow.acChecksum = await acChecksum(cwd, dir);
+        flow.acKinds = await deriveAcKinds(cwd, dir, flow.id);
         flow.acConfirmed = {};
         return save(cwd, dir, flow, "ac-updated", detail);
       });
     },
+    async acKinds({ cwd, id }) {
+      const { dir, flow } = await load(cwd, id);
+      return buildAcKindReport(flow.id, await readFile23(acPath(cwd, dir), "utf8"));
+    },
     async acReseal({ cwd, id, reason }) {
       if (!reason?.trim()) {
         throw new Error('flow ac reseal requires --reason "<why the checksum is stale>"');
@@ -24794,6 +24970,7 @@ function createFlowService(deps) {
           throw new Error(`flow ac reseal: refusing \u2014 ${evidence.reason}. ` + "Reseal only re-seals a stale checksum over an unchanged file; it is not a way to " + 'accept an edit. If the criteria really changed, use `keryx flow ac update <id> --reason "..."`, ' + "which re-seals AND voids the prior confirmations.");
         }
         flow.acChecksum = current;
+        flow.acKinds = await deriveAcKinds(cwd, dir, flow.id);
         return save(cwd, dir, flow, "ac-resealed", reason);
       });
     },
@@ -37931,6 +38108,12 @@ var HELP_GROUPS = [
     group: "Automation",
     summary: "Read-only report over already-recorded spend, confirmations, signatures and gate outcomes."
   },
+  {
+    kind: "cli",
+    name: "product",
+    group: "Automation",
+    summary: "The product's intent as a derived index, and the intents closed in code that nobody looked back at."
+  },
   {
     kind: "cli",
     name: "hooks",
@@ -37967,6 +38150,12 @@ var HELP_GROUPS = [
     group: "Automation",
     summary: "Show the last governance report, or run one in the background."
   },
+  {
+    kind: "slash",
+    name: "/product",
+    group: "Automation",
+    summary: "Intents closed in code that nobody looked back at, with their outcome criteria."
+  },
   {
     kind: "cli",
     name: "acp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.28",
+  "version": "0.3.30",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:scripts": "tsc --project tsconfig.scripts.json --noEmit",
     "test": "bun test",
-    "test:core": "bun test src/cli src/core src/impact-evidence/ src/shell-source-audits.test.ts src/acp/ src/assets/ src/bundle/ src/capability/ src/commands/ src/contracts/ src/ctx/ src/eval/ src/flow/ src/forgetting/ src/gdgraph/ src/gdskills/ src/governance/ src/health/ src/integrations/ src/job/ src/learning/ src/lib/ src/mcp/ src/memory/ src/metrics/ src/retention/ src/review/ src/rules/ src/sac/ src/security/ src/stack/ src/standard/ src/sync/ src/testing/ src/trigger/ src/wiki/ scripts/",
+    "test:core": "bun test src/cli src/core src/impact-evidence/ src/shell-source-audits.test.ts src/acp/ src/assets/ src/bundle/ src/capability/ src/commands/ src/contracts/ src/ctx/ src/eval/ src/flow/ src/forgetting/ src/gdgraph/ src/gdskills/ src/governance/ src/product/ src/health/ src/integrations/ src/job/ src/learning/ src/lib/ src/mcp/ src/memory/ src/metrics/ src/retention/ src/review/ src/rules/ src/sac/ src/security/ src/stack/ src/standard/ src/sync/ src/testing/ src/trigger/ src/wiki/ scripts/",
     "test:client:terminal": "bun test src/tui/ src/commands/shell",
     "test:client:streaming": "bun test src/harness/provider/",
     "test:client:cancel-resume": "bun test src/harness/run/ src/harness/resume/ src/harness/session/ src/session/ src/bus/ src/commands/sessions",

package/src/gdskills/bundled/rules/core/requirements-package-standard.mdc

@@ -62,11 +62,26 @@ document changes.
 - problem;
 - goal;
 - users;
-- requirements;
-- success criteria;
+- requirements, each carrying a verification field (see Verification Field below);
+- success criteria, split into two lists (see Success Contract below);
 - risks;
 - recommendation.
 
+### Success Contract
+
+The PRD's success criteria are two lists, never one:
+
+- **Release criteria** are checkable when the work ships: a test, a command, a
+  file, a count. Each is something a release can be blocked on.
+- **Outcome criteria** are what should be true some time after release: adoption,
+  a measured change, a behavior seen in use. Each outcome criterion either names
+  the observation that would confirm it (what is looked at, where, and when) or
+  declares `not measured — <reason>`.
+
+An outcome criterion with neither an observation nor a `not measured — <reason>`
+is not a criterion. A list whose every entry is `not measured` is acceptable: it
+is honest. A PRD with no outcome list at all is not.
+
 ## Specification Contract
 
 `specification.md` must state:
@@ -79,6 +94,21 @@ document changes.
 - integration points;
 - acceptance criteria.
 
+### Verification Field
+
+Every requirement in the PRD (each `R<n>` under Requirements) carries one verification field, in the
+same vocabulary a flow criterion's trailing marker uses:
+
+```markdown
+Verification: exec `<command>`            # a command whose exit code decides it
+Verification: invariant `<command>`       # a command that must keep passing
+Verification: judged                      # a person reads the evidence
+Verification: none — <reason>             # honestly unverifiable, with the reason
+```
+
+`exec` and `invariant` name a backticked command; `none` names its reason after
+an em dash. A requirement with no field is a defect, not a `none`.
+
 ## Verification Contract
 
 Before finishing:
@@ -88,6 +118,11 @@ Before finishing:
 - verify README links to all package files;
 - verify schemas are referenced from specification when present;
 - verify status is honest: `draft`, `spec ready`, `implemented`, or `future`;
+- verify every PRD requirement carries a `Verification:` field, and
+  fail the package when one does not, naming that requirement;
+- verify the PRD has both a release-criteria list and an outcome-criteria list,
+  and fail the package when the outcome list is missing (an outcome list whose
+  entries are all `not measured — <reason>` passes);
 - update `docs/requirements/roadmap.md` when the package represents a module or
   standard capability.
 

package/src/gdskills/bundled/skills/planning/docpack-orchestrator/SKILL.md

@@ -109,10 +109,8 @@ Add optional files only when justified:
 Write concise Markdown with explicit headings. Required contracts:
 
 - README: purpose, status, document index, scope, related modules.
-- PRD: problem, goal, users, requirements, success criteria, risks,
-  recommendation.
-- Specification: identity, structure, manifest/config, CLI/skill surface, data
-  contracts, integrations, acceptance criteria.
+- PRD: problem, goal, users, requirements (each `R<n>` carries a `Verification:` field: `exec`/`invariant` with a backticked command, `judged`, or `none — <reason>`), success criteria (a release list and an outcome list; an outcome criterion names its observation or declares `not measured — <reason>`), risks, recommendation.
+- Specification: identity, structure, manifest/config, CLI/skill surface, data contracts, integrations, acceptance criteria.
 
 When updating existing docs, preserve useful content and bump versions.
 
@@ -125,6 +123,7 @@ Run a local verification pass:
 - README links to every package file;
 - schema files are valid JSON;
 - specification references schemas when present;
+- every PRD requirement has a `Verification:` field (a package with a requirement that omits it FAILS, naming that requirement); the PRD has a release list and an outcome list (no outcome list FAILS; an outcome list whose entries are all `not measured — <reason>` passes);
 - roadmap is updated for new module/standard capabilities;
 - no implementation status is overstated.
 
@@ -154,6 +153,7 @@ Do not emit the Final Response until all of these hold:
 - Every Markdown file in the package carries a `Version`, and every file you changed has a bumped one.
 - `README.md` links to every file in the package; the specification links to each schema it defines.
 - Every `schemas/*.json` parses as valid JSON.
+- Every specification requirement carries a `Verification:` field, and the PRD carries both a release list and an outcome list; a package missing either was reported as `verification: fail`, naming the requirement.
 - `docs/requirements/roadmap.md` is updated when the package represents a new module or capability, or the report states why it does not.
 - No implementation claim appears that code does not support; anything unbuilt is marked planned or future.
 - `docpack-review` has been run in Phase 5 and reports zero blockers. Remaining warnings appear verbatim in `remaining_gaps`.