@afokapu/atdd-bun 0.10.49 → 0.10.51

package/README.md

@@ -61,6 +61,7 @@ registerEnforcementTest({ root: import.meta.dir + "/..", profiles: ["traceabilit
 | `interlocking` | train/interlocking binding, infrastructure and route coverage |
 | `htmx` | htmx source/test conventions and Playwright browser specs (`*.e2e.ts`) |
 | `design` | design-system layering, token-only styling and responsiveness |
+| `flow` | optional ATDD Flow companion conventions for durable seats, tasks and threads |
 | `all` | every activated profile; what the hooks and CI run |
 
 `planner-nodes/ENFORCEMENT_SCOPE.yaml` says which canonical planner rules have a Bun realization.
@@ -80,6 +81,16 @@ profiles: [traceability, planner]
 by name (`bun run atdd-bun coder`) to see what remains. An unknown name or an empty list is an
 error, never a silent run of nothing.
 
+### Flow profile compatibility
+
+`flow` is the canonical optional profile name. For a compatible upgrade, a legacy explicit
+`workflow` entry in `atdd-bun.yaml`, or a direct `bun run atdd-bun workflow`, normalizes to
+`flow`; it does not make unrelated names valid. `flow` requires `@afokapu/atdd-bun` **0.10.45 or
+newer**. If a checkout reports that `flow` is unknown, it is running a stale toolkit: run
+`bun update @afokapu/atdd-bun`, then use the repository-local command
+`bun run atdd-bun flow --root .` (never a PATH-global `atdd-bun`). Keep `flow` in newly edited
+configuration.
+
 With no `profiles:` field, every profile runs, but none is governed yet. The first explicit list is
 the adoption that establishes the governed set, so a brownfield repository can declare
 `profiles: [docs]` in an ordinary pull request. From then on, the integrity check reports, against
@@ -111,6 +122,27 @@ release: { enabled: false }
 
 When enabled without overrides, a primary checkout at `~/Github/<repo>` uses linked worktrees at `~/Github/worktrees/<repo>/<branch>`. The defaults use `primary_directory: .` (the current primary checkout) and `root: ../worktrees/{repo}`; `{repo}` expands to the primary checkout's directory name. Repositories that need another layout can set either field explicitly.
 
+## Exact-base finding ratchet (opt-in)
+
+Strict enforcement is the default: `bun run atdd-bun all` still fails for every finding. A consumer may opt into an exact-base comparison for one explicit profile set:
+
+```yaml
+# atdd-bun.yaml
+ratchet:
+  mode: report       # or reject-new
+  profiles: [coder, tester]
+```
+
+Run it only against a full reviewed base SHA:
+
+```sh
+bun run atdd-bun coder tester --ratchet --base <40-character-reviewed-main-sha>
+```
+
+The command runs the same installed detectors against an isolated exact base and the clean candidate, emits a redacted JSON `carried`/`new`/`resolved` fingerprint report, and never writes or accepts a baseline. `report` records debt without changing command success; `reject-new` exits non-zero only when the candidate adds a finding absent from the equivalent base. The declared `ratchet.profiles` must exactly match the command's effective profiles. Base and candidate profile/context digests must match or comparison fails closed; profile/config adoption is separately governed. Use debt-remediation branches to remove carried findings. Direct implementation profiles can opt in only through this explicit policy and do not alter configured merge profiles or `profiles:`.
+
+Fingerprints are SHA-256 of a versioned rule, normalized repository-relative path, and semantic subject where supplied; line/column, rendered evidence, source text, absolute paths, and runtime data are excluded. Ratchet findings are unrelated to Bun `test.failing()` or JUnit/behavioral-test baselines.
+
 ## Docs-site theme
 
 A repository that publishes its AsciiDoc docs as a site does not need its own theme.

package/integrity.json

@@ -1,9 +1,9 @@
 {
-  "version": "0.10.49",
+  "version": "0.10.51",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "PLANNER_PORT.md": "fb5935bac8b7ac18994de21e43ace3a5ef8cd55f85b0e3349fca261280054f11",
-    "README.md": "5b46af2c4be56303b3ef4b136e443c55d008f29705850265492328c196a3d7e2",
+    "README.md": "16cac8c84aa9b11018b4b1cc2984faa74c06bee1d7ce1360fb234154bbce2d9f",
     "bunfig.toml": "b9fc65eca9014c5179380259d70e76385a6a80788fa9a2df5fb3eaa5554fd2fe",
     "conventions/_profiles/architecture.yaml": "f1808768b720a4e476047e4a0912002ca673946562cea9aeef5d0c214828d93a",
     "conventions/_profiles/coder.yaml": "3fb191556a64c9ebcf249516afa189afca24da9b22fd40b2fc66908196cdfb78",
@@ -1195,9 +1195,9 @@
     "relationships.yaml": "5860a308ebc3ee7fa8172fc2c6633984000ab3003f0ae4b6fa28db48879eda22",
     "src/agent.ts": "39ca8b3183063c60e00eb96e5629d0397aeb83cc82d4c4bc32c01715c906649b",
     "src/ci.ts": "67e54d2cbfc44a9e42837d5e750af526d6255c539d3c452a4d5fca3226c0d9ac",
-    "src/cli.ts": "cbc50f1e7fc7d0935f78230b7da6e232ed7ee6f04828e015c599fb6f6edcbfa2",
+    "src/cli.ts": "8f5d69bdd5940c7213f8b7c342fd94c1dc9387d56dad7458ce6e9286d88181d3",
     "src/docs-capability.ts": "bdeeb414649049b1cd4fa8008cada3a576318be51c43bec91bfa46a8e250c270",
-    "src/enforce.ts": "4738f4be630e9087415a12f8e0cbbf63ced02da027c665cf0dc5a514d4dc6d94",
+    "src/enforce.ts": "7e6b3a1fc7c90f8e1836ab3e4655778fb569a63be5e7c199de44024fc003e6be",
     "src/hooks.ts": "0b4ca8c857e637bbd144e737e78eda924e3cba7b038c0abe5e6916d200d73068",
     "src/index.ts": "4081f8b08d1d3ee9e15a9964143e53d9cfb94a5616ab3e58a180d24cc16dc381",
     "src/integrity.ts": "f5ad22759eec675454df82cdcf791b1f081951f08ca5084ebdcb8cd82aa1ecef",
@@ -1206,6 +1206,7 @@
     "src/planner-schema-validator.ts": "ce529c0936171075e93c7539b3655fe895a98dd2973ebda5775958e6ebc316d9",
     "src/planner-validators.ts": "99adeb65f579af923c11f21a8f55cfb9993b007fd8df59c5f764696b55379cfc",
     "src/profile-registry.ts": "5a7761d324181ae27deb51f198d63648a4c99e858b4de98b54d35e6cf8a39fe7",
+    "src/ratchet.ts": "c4ebf34350bc3909db93754f2c92de065325763859bd3040dfaf3d6b204ef33e",
     "src/register.ts": "6a2f1c6b8df0dc9c8f45df8ec9fac2be29044e048b08c8ffe423410e94dadedd",
     "src/release.ts": "7b0fe444ee81f476f53b9c21b6c347ef588ee616c60211419cf984132be768ba",
     "src/setup.ts": "38233265afedc63499bbef3b5403889651add335a70efd3813254ba53f4fc4fe",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.10.49",
+  "version": "0.10.51",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"

package/src/cli.ts

@@ -1,5 +1,10 @@
 #!/usr/bin/env bun
-import { enforce, profileNames, type Profile } from "./enforce";
+import { enforce, enabledProfiles, flowCompatibilityDiagnostic, normalizeProfileName, profileNames, type Profile } from "./enforce";
+import { compareFindings, contextDigest, parseRatchetPolicy } from "./ratchet";
+import { existsSync } from "node:fs";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
 import { finishWorktree, hookEvents, hooksStatus, installHooks, runHook, startWorktree, uninstallHooks, worktreeStatus } from "./hooks";
 import { ciInit, ciStatus } from "./ci";
 import { agentInit, agentStatus } from "./agent";
@@ -14,7 +19,7 @@ const args = process.argv.slice(2);
 const usage = {
   command: "atdd-bun",
   usage: [
-    "atdd-bun [profile ...] [--root <path>]",
+    "atdd-bun [profile ...] [--root <path>] [--ratchet --base <full-sha>]",
     "atdd-bun init [--replace]",
     "atdd-bun hooks <install|uninstall|status> [--replace]",
     "atdd-bun worktree <start|finish|status>",
@@ -109,20 +114,69 @@ if (args[0] === "release") {
 const valueAfter = (flag: string) => args[args.indexOf(flag) + 1];
 const root = args.includes("--root") ? valueAfter("--root") : process.cwd();
 if (args.includes("--root") && !root) fail("--root requires a path");
+if (args.includes("--base") && !valueAfter("--base")) fail("--base requires a full commit SHA");
 const positional: string[] = [];
 for (let index = 0; index < args.length; index += 1) {
   const arg = args[index];
-  if (arg === "--root" || arg === "--profile") { index += 1; continue; }
+  if (arg === "--root" || arg === "--profile" || arg === "--base") { index += 1; continue; }
   if (!arg.startsWith("-")) positional.push(arg);
 }
 const profileValue = args.includes("--profile") ? valueAfter("--profile") : undefined;
 if (args.includes("--profile") && !profileValue) fail("--profile requires one or more comma-separated profiles");
 const requested = profileValue ? profileValue.split(",").filter(Boolean) : positional.length ? positional : ["all"];
-const invalid = requested.find(profile => !profileNames.includes(profile as Profile));
+const normalizedRequested = requested.map(normalizeProfileName);
+const invalid = normalizedRequested.find(profile => !profileNames.includes(profile as Profile));
 if (invalid) fail("unknown command or profile: " + invalid);
-const violations = await enforce({ root, profiles: requested as Profile[] });
-for (const violation of violations) {
-  console.error([violation.file, violation.line, violation.col].join(":") + " " + violation.rule_id + " — " + violation.evidence);
+if (requested.includes("workflow")) console.error(flowCompatibilityDiagnostic);
+const printViolations = (violations: Awaited<ReturnType<typeof enforce>>) => {
+  for (const violation of violations) console.error([violation.file, violation.line, violation.col].join(":") + " " + violation.rule_id + " — " + violation.evidence);
+};
+const configAt = async (directory: string) => {
+  const file = join(directory, "atdd-bun.yaml");
+  return existsSync(file) ? Bun.YAML.parse(await readFile(file, "utf8")) as Record<string, unknown> : {};
+};
+const git = async (directory: string, gitArgs: string[]) => {
+  const child = Bun.spawn({ cmd: ["git", ...gitArgs], cwd: directory, stdout: "pipe", stderr: "pipe" });
+  return { code: await child.exited, out: (await new Response(child.stdout).text()).trim(), err: (await new Response(child.stderr).text()).trim() };
+};
+const stable = (items: string[]) => [...new Set(items)].sort();
+if (!args.includes("--ratchet")) {
+  const violations = await enforce({ root, profiles: normalizedRequested as Profile[] });
+  printViolations(violations);
+  if (violations.length) console.error("\nUse the rule ID and evidence above to correct the affected artifact. Run atdd-bun help for commands and profiles.");
+  process.exitCode = violations.length ? 1 : 0;
+} else {
+  const base = valueAfter("--base");
+  if (!base || !/^[0-9a-f]{40}$/i.test(base)) fail("--ratchet requires --base <full-40-character-sha>");
+  const candidateRoot = resolve(root), candidateConfig = await configAt(candidateRoot), policy = parseRatchetPolicy(candidateConfig);
+  if (!policy) fail("--ratchet requires an explicit atdd-bun.yaml ratchet policy");
+  const candidateProfiles = normalizedRequested.includes("all") ? await enabledProfiles(candidateRoot) : normalizedRequested;
+  if (stable(policy.profiles).join(",") !== stable(candidateProfiles).join(",")) fail("ratchet.profiles must exactly equal the selected profiles");
+  if ((await git(candidateRoot, ["status", "--porcelain"])).out) fail("--ratchet requires a porcelain-clean candidate worktree");
+  const resolved = await git(candidateRoot, ["rev-parse", "--verify", `${base}^{commit}`]);
+  if (resolved.code || resolved.out.toLowerCase() !== base.toLowerCase()) fail(`ratchet base ${base} is unavailable or not a full exact commit`);
+  if ((await git(candidateRoot, ["merge-base", "--is-ancestor", base, "HEAD"])).code !== 0) fail("ratchet base must be an ancestor of candidate HEAD");
+  const scratch = await mkdtemp(join(tmpdir(), "atdd-ratchet-"));
+  try {
+    const added = await git(candidateRoot, ["worktree", "add", "--detach", "--no-checkout", scratch, base]);
+    if (added.code) { console.error(`could not materialize ratchet base: ${added.err || added.out}`); process.exitCode = 1; }
+    else {
+      const checkedOut = await git(scratch, ["checkout", "--detach", base]);
+      if (checkedOut.code) { console.error(`could not checkout ratchet base: ${checkedOut.err || checkedOut.out}`); process.exitCode = 1; }
+      else {
+        const baseConfig = await configAt(scratch), baseProfiles = normalizedRequested.includes("all") ? await enabledProfiles(scratch) : normalizedRequested;
+        if (stable(baseProfiles).join(",") !== stable(candidateProfiles).join(",") || contextDigest(baseConfig, baseProfiles) !== contextDigest(candidateConfig, candidateProfiles)) { console.error("ratchet base and candidate profile/context differ; use a separately governed adoption path"); process.exitCode = 1; }
+        else {
+          const [baseFindings, candidateFindings] = await Promise.all([enforce({ root: scratch, profiles: candidateProfiles as Profile[] }), enforce({ root: candidateRoot, profiles: candidateProfiles as Profile[] })]);
+          const normalize = (findings: Awaited<ReturnType<typeof enforce>>, directory: string) => findings.map(finding => ({ ...finding, file: relative(directory, finding.file).replaceAll("\\", "/") }));
+          const delta = compareFindings(normalize(baseFindings, scratch), normalize(candidateFindings, candidateRoot));
+          console.log(JSON.stringify({ schema: "atdd-bun.ratchet-report/v1", mode: policy.mode, base, candidate: (await git(candidateRoot, ["rev-parse", "HEAD"])).out, profiles: stable(candidateProfiles), context: contextDigest(candidateConfig, candidateProfiles), ...delta }, null, 2));
+          if (policy.mode === "reject-new" && delta.new.length) process.exitCode = 1;
+        }
+      }
+    }
+  } finally {
+    await git(candidateRoot, ["worktree", "remove", "--force", scratch]);
+    await rm(scratch, { recursive: true, force: true });
+  }
 }
-if (violations.length) console.error("\nUse the rule ID and evidence above to correct the affected artifact. Run atdd-bun help for commands and profiles.");
-process.exitCode = violations.length ? 1 : 0;

package/src/enforce.ts

@@ -60,6 +60,16 @@ export const optionalProfiles: ConcreteProfile[] = ["flow"];
 export const defaultProfiles = concreteProfiles.filter(profile => !optionalProfiles.includes(profile));
 /** Profile names accepted by the CLI and public integrations. */
 export const profileNames = [...concreteProfiles, "all"] as Profile[];
+/** Retired spellings accepted only to migrate old configuration and invocations to their canonical profile. */
+export const legacyProfileAliases = { workflow: "flow" } as const;
+
+/** Normalize a supported retired spelling without making it part of the canonical profile registry. */
+export function normalizeProfileName(name: string): string {
+  return legacyProfileAliases[name as keyof typeof legacyProfileAliases] ?? name;
+}
+
+/** Guidance for a repository that was configured during the workflow → flow rename. */
+export const flowCompatibilityDiagnostic = "Legacy profile workflow is normalized to canonical flow. If this checkout reports flow as unknown, it is using @afokapu/atdd-bun older than 0.10.45; run bun update @afokapu/atdd-bun, then invoke the project-local CLI with bun run atdd-bun flow --root . (not a PATH-global atdd-bun).";
 
 /**
  * The profiles the operator has activated: `profiles:` in atdd-bun.yaml, or every built-in profile when absent. A legacy
@@ -72,9 +82,10 @@ export async function enabledProfiles(root = process.cwd()): Promise<ConcretePro
   const listed = existsSync(file) ? (Bun.YAML.parse(await readFile(file, "utf8")) as { profiles?: unknown } | null)?.profiles : undefined;
   if (listed === undefined) return defaultProfiles;
   if (!Array.isArray(listed) || !listed.length) throw new Error("atdd-bun.yaml profiles must be a non-empty list of profile names");
-  const unknown = listed.filter(name => !concreteProfiles.includes(name));
+  const normalized = listed.map(name => typeof name === "string" ? normalizeProfileName(name) : name);
+  const unknown = normalized.filter(name => typeof name !== "string" || !concreteProfiles.includes(name as ConcreteProfile));
   if (unknown.length) throw new Error(`atdd-bun.yaml profiles lists unknown profile(s): ${unknown.join(", ")}; known: ${concreteProfiles.join(", ")}`);
-  return [...new Set(listed as ConcreteProfile[])];
+  return [...new Set(normalized as ConcreteProfile[])];
 }
 
 const packageRoot = resolve(import.meta.dir, "..");

package/src/ratchet.ts

@@ -0,0 +1,54 @@
+/** Pure v1 primitives for the opt-in exact-base finding ratchet. No baseline is written or accepted. */
+export type RatchetMode = "report" | "reject-new";
+export type RatchetPolicy = { mode: RatchetMode; profiles: string[] };
+export type FindingIdentity = {
+  rule_id: string;
+  file: string;
+  subject?: string;
+  line?: number;
+  col?: number;
+  evidence?: string;
+  source_line?: string;
+};
+
+const canonical = (value: unknown): string => {
+  if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (typeof value === "object") return `{${Object.entries(value as Record<string, unknown>).filter(([, entry]) => entry !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`).join(",")}}`;
+  throw new Error(`cannot canonicalize ${typeof value}`);
+};
+const sha256 = (value: unknown) => new Bun.CryptoHasher("sha256").update(canonical(value)).digest("hex");
+const normalizedPath = (path: string) => {
+  const normalized = path.replaceAll("\\", "/").replace(/^\.\//, "");
+  if (!normalized || normalized.startsWith("/") || /^[A-Za-z]:\//.test(normalized) || normalized.split("/").includes("..")) throw new Error(`ratchet finding path must be normalized and repository-relative: ${path}`);
+  return normalized;
+};
+
+/** Stable semantic identity: presentation position and rendered evidence deliberately do not participate. */
+export function findingFingerprint(finding: FindingIdentity): string {
+  const path = normalizedPath(finding.file), subject = finding.subject ?? path;
+  if (!finding.rule_id || !subject) throw new Error("ratchet finding requires rule_id and semantic subject");
+  return sha256({ format: "atdd-bun.finding-fingerprint/v1", rule_id: finding.rule_id, path, subject });
+}
+
+/** The selected profiles and every policy key except ratchet itself must agree across exact base and candidate. */
+export function contextDigest(config: Record<string, unknown>, profiles: string[]): string {
+  const { ratchet: _ratchet, ...policy } = config;
+  return sha256({ format: "atdd-bun.ratchet-context/v1", profiles: [...profiles].sort(), policy });
+}
+
+export function parseRatchetPolicy(config: Record<string, unknown>): RatchetPolicy | null {
+  if (config.ratchet === undefined) return null;
+  const value = config.ratchet;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("atdd-bun.yaml ratchet must be a mapping");
+  const mode = (value as Record<string, unknown>).mode, profiles = (value as Record<string, unknown>).profiles;
+  if (mode !== "report" && mode !== "reject-new") throw new Error("atdd-bun.yaml ratchet.mode must be report or reject-new");
+  if (!Array.isArray(profiles) || !profiles.length || !profiles.every(profile => typeof profile === "string")) throw new Error("atdd-bun.yaml ratchet.profiles must be a non-empty list of profile names");
+  return { mode, profiles: [...new Set(profiles)].sort() };
+}
+
+export function compareFindings(base: FindingIdentity[], candidate: FindingIdentity[]) {
+  const baseSet = new Set(base.map(findingFingerprint)), candidateSet = new Set(candidate.map(findingFingerprint));
+  const list = (source: Set<string>, absent: Set<string>) => [...source].filter(item => !absent.has(item)).sort();
+  return { carried: [...baseSet].filter(item => candidateSet.has(item)).sort(), new: list(candidateSet, baseSet), resolved: list(baseSet, candidateSet) };
+}