@afokapu/atdd-bun 0.10.32 → 0.10.34

package/src/index.ts

@@ -17,5 +17,6 @@ export type { Gap, Journey, JourneyModel, JourneyPath } from "./journey-docs";
 export { checkIntegrity, checkInstalledPackage, formatIntegrity, integrityInit, loosenedPolicy, writeManifest } from "./integrity";
 export type { IntegrityFinding, IntegrityOptions } from "./integrity";
 export { releaseCheck } from "./release";
+export { profileRegistries, renderProfileRegistries, PROFILE_REGISTRY_DIR } from "./profile-registry";
 export { defaultTopology, topologyFor } from "./topology";
 export type { Topology } from "./topology";

package/src/integrity.ts

@@ -18,7 +18,6 @@ const PACKAGE = "@afokapu/atdd-bun";
 const ownRoot = resolve(import.meta.dir, "..");
 export const MANIFEST = "integrity.json";
 export const TEST_FILE = "atdd-bun.integrity.test.ts";
-const SKILLS = [".agents/skills/atdd/SKILL.md", ".claude/skills/atdd/SKILL.md"];
 const WORKFLOW = ".github/workflows/atdd-bun.yml";
 const BLOCK = /<!-- atdd-bun:start[\s\S]*?<!-- atdd-bun:end -->/;
 // Generated files carry the version that wrote them; an upgrade must not read as tampering.
@@ -99,7 +98,6 @@ async function checkGenerated(root: string, packageRoot: string, skipWorkflow =
   if (skipWorkflow) { /* rendered from atdd-bun.yaml, which does not parse: reported by the caller */ }
   else if (!existsSync(workflow)) findings.push({ file: WORKFLOW, detail: "is missing", restore: "bun run atdd-bun ci init --replace" });
   else if (unstamp(await readFile(workflow, "utf8")) !== unstamp(await renderWorkflow(root))) findings.push({ file: WORKFLOW, detail: "was edited; it must match what the package generates (protected_branches decides its push branches)", restore: "bun run atdd-bun ci init --replace" });
-  for (const skill of SKILLS) await same(skill, "templates/agents/atdd/SKILL.md", "bun run atdd-bun agent init --replace");
   await same(relative(root, await testFilePath(root)), "templates/agents/atdd-bun.integrity.test.ts", "bun run atdd-bun integrity init --replace");
   const canonical = (await readFile(join(packageRoot, "templates/agents/AGENTS.block.md"), "utf8")).match(BLOCK)![0];
   for (const file of instructionPaths) {

package/src/profile-registry.ts

@@ -0,0 +1,78 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { concreteProfiles, declaredRuleIds, profileConventions, profileImplementations } from "./enforce";
+
+export const PROFILE_REGISTRY_DIR = "conventions/_profiles";
+type Convention = { rule_id: string; path: string };
+type Relationship = Record<string, unknown> & { source_ref: string; target_ref: string; type: string };
+type Graph = { edges: Relationship[] };
+
+async function filesBelow(root: string, extension: string): Promise<string[]> {
+  const out: string[] = [];
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) out.push(...await filesBelow(path, extension));
+    else if (entry.name.endsWith(extension)) out.push(path);
+  }
+  return out;
+}
+
+async function conventionIndex(root: string): Promise<Map<string, Convention>> {
+  const index = new Map<string, Convention>();
+  for (const base of ["planner-nodes/nodes", "conventions"]) for (const file of await filesBelow(join(root, base), ".convention.yaml")) {
+    const rule_id = (Bun.YAML.parse(await readFile(file, "utf8")) as { rule_id?: unknown }).rule_id;
+    if (typeof rule_id !== "string") continue;
+    const path = relative(root, file).replaceAll("\\", "/");
+    if (index.has(rule_id)) throw new Error(`multiple convention files declare ${rule_id}: ${index.get(rule_id)!.path}, ${path}`);
+    index.set(rule_id, { rule_id, path });
+  }
+  return index;
+}
+
+const sorted = <T>(items: Iterable<T>, compare: (left: T, right: T) => number = (left, right) => String(left).localeCompare(String(right))) => [...items].sort(compare);
+const relationshipKey = (edge: Relationship) => `${edge.source_ref}\u0000${edge.target_ref}\u0000${edge.type}`;
+const scalar = (value: unknown) => value === null ? "null" : typeof value === "string" ? JSON.stringify(value) : typeof value === "number" || typeof value === "boolean" ? String(value) : (() => { throw new Error(`profile registry cannot render non-scalar value ${JSON.stringify(value)}`); })();
+const fields = (value: Record<string, unknown>, indent: string) => sorted(Object.entries(value), ([left], [right]) => left.localeCompare(right)).map(([key, entry]) => `${indent}${key}: ${scalar(entry)}`);
+const render = (profile: string, implementations: string[], conventions: Convention[], relationships: Relationship[]) => [
+  'schema_version: "1.0.0"', `profile: ${scalar(profile)}`,
+  implementations.length ? "implementations:" : "implementations: []", ...implementations.map(implementation => `  - ${scalar(implementation)}`),
+  conventions.length ? "conventions:" : "conventions: []", ...conventions.flatMap(convention => [`  - rule_id: ${scalar(convention.rule_id)}`, `    path: ${scalar(convention.path)}`]),
+  relationships.length ? "relationships:" : "relationships: []", ...relationships.flatMap(edge => { const entries = fields(edge, "    "); return [`  - ${entries[0]!.slice(4)}`, ...entries.slice(1)]; }), "",
+].join("\n");
+
+/** Deterministically project profiles, detector manifests, conventions, and direct graph edges into small registries. */
+export async function renderProfileRegistries(root = resolve(import.meta.dir, "..")): Promise<Map<string, string>> {
+  const conventions = await conventionIndex(root);
+  const graph = Bun.YAML.parse(await readFile(join(root, "relationships.yaml"), "utf8")) as Graph;
+  if (!Array.isArray(graph.edges)) throw new Error("relationships.yaml has no edges list");
+  const rendered = new Map<string, string>();
+  for (const profile of concreteProfiles) {
+    const implementations = sorted(profileImplementations[profile]);
+    const declared = await Promise.all(implementations.map(implementation => declaredRuleIds(implementation, join(root, "detectors"))));
+    const ruleIds = sorted(new Set(declared.flatMap(ids => [...ids])));
+    const missing = ruleIds.filter(id => !conventions.has(id));
+    if (missing.length) throw new Error(`${profile} declares rule IDs without exactly one convention: ${missing.join(", ")}`);
+    const supplementary = profileConventions[profile];
+    const duplicate = supplementary.find(convention => conventions.has(convention.rule_id) || ruleIds.includes(convention.rule_id));
+    if (duplicate) throw new Error(`${profile} duplicates convention ${duplicate.rule_id}`);
+    const selectedConventions = [...ruleIds.map(id => conventions.get(id)!), ...supplementary];
+    const rules = new Set(selectedConventions.map(convention => convention.rule_id));
+    const relationships = sorted(graph.edges.filter(edge => rules.has(edge.source_ref) || rules.has(edge.target_ref)), (left, right) => relationshipKey(left).localeCompare(relationshipKey(right)));
+    rendered.set(`${PROFILE_REGISTRY_DIR}/${profile}.yaml`, render(profile, implementations, selectedConventions, relationships));
+  }
+  return rendered;
+}
+
+/** Write or check the shipped profile registries. `check` reports every stale or unexpected generated file. */
+export async function profileRegistries(options: { root?: string; check?: boolean } = {}) {
+  const root = resolve(options.root ?? resolve(import.meta.dir, "..")), expected = await renderProfileRegistries(root), directory = join(root, PROFILE_REGISTRY_DIR);
+  const actual = existsSync(directory) ? sorted((await readdir(directory)).filter(name => name.endsWith(".yaml")).map(name => `${PROFILE_REGISTRY_DIR}/${name}`)) : [];
+  const files: string[] = [];
+  for (const path of sorted(new Set([...expected.keys(), ...actual]))) if (!expected.has(path) || !existsSync(join(root, path)) || (await readFile(join(root, path), "utf8")) !== expected.get(path)) files.push(path);
+  if (options.check) return { ok: !files.length, message: files.length ? `profile registries have drifted: ${files.join(", ")}; run: atdd-bun profiles registry` : "profile registries are current", files };
+  await mkdir(directory, { recursive: true });
+  for (const path of actual.filter(path => !expected.has(path))) await rm(join(root, path));
+  for (const [path, content] of expected) await writeFile(join(root, path), content);
+  return { ok: true, message: `wrote ${expected.size} profile registries`, files: sorted(expected.keys()) };
+}

package/src/setup.ts

@@ -2,7 +2,7 @@ import { ciInit, ciStatus } from "./ci";
 import { hooksStatus, installHooks } from "./hooks";
 import { agentInit, agentStatus } from "./agent";
 import { integrityInit, integrityStatus } from "./integrity";
-import { concreteProfiles } from "./enforce";
+import { defaultProfiles } from "./enforce";
 import { existsSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -14,7 +14,7 @@ import { join } from "node:path";
 export async function policyInit(root = process.cwd()) {
   const file = join(root, "atdd-bun.yaml");
   if (existsSync(file)) return { ok: true, message: `${file} kept` };
-  await writeFile(file, `# Generated by atdd-bun init. The profiles this repository enforces; trim the list before the first commit to\n# adopt gradually. Once committed, removing a profile or the list is reported by the integrity check.\nprofiles: [${concreteProfiles.join(", ")}]\n`);
+  await writeFile(file, `# Generated by atdd-bun init. The profiles this repository enforces; trim the list before the first commit to\n# adopt gradually. Once committed, removing a profile or the list is reported by the integrity check.\nprofiles: [${defaultProfiles.join(", ")}]\n`);
   return { ok: true, message: file };
 }
 
@@ -33,10 +33,10 @@ export async function initializeRepository(root = process.cwd(), replace = false
 
   const existingAgent = await agentStatus(root);
   const agent = replace || !existingAgent.ok ? await agentInit(root, replace) : existingAgent;
-  if (!agent.ok) return { ok: false, message: `agent skill: ${agent.message}` };
+  if (!agent.ok) return { ok: false, message: `agent instructions: ${agent.message}` };
 
   const existingIntegrity = await integrityStatus(root);
   const integrity = replace || !existingIntegrity.ok ? await integrityInit(root, replace) : existingIntegrity;
   if (!integrity.ok) return { ok: false, message: `integrity test: ${integrity.message}` };
-  return { ok: true, message: `hooks: ${hooks.message}\nCI workflow: ${ci.message}\nagent skill: ${agent.message}\nintegrity test: ${integrity.message}\npolicy: ${policy.message}` };
+  return { ok: true, message: `hooks: ${hooks.message}\nCI workflow: ${ci.message}\nagent instructions: ${agent.message}\nintegrity test: ${integrity.message}\npolicy: ${policy.message}` };
 }

package/templates/agents/AGENTS.block.md

@@ -1,11 +1,9 @@
 <!-- atdd-bun:start — generated by @afokapu/atdd-bun {{VERSION}}; run `atdd-bun agent init --replace` to refresh -->
-## ATDD lifecycle
+## ATDD
 
-Before changing code, tests, or `plan/`, follow `.agents/skills/atdd/SKILL.md`: PLAN → RED → GREEN → SMOKE → REFACTOR → TRACE, passing each stage's `atdd-bun` gate before starting the next.
+For each task, read `conventions/atdd-bun.profiles/atdd-bun.profiles.presets.convention.yaml` in `node_modules/@afokapu/atdd-bun` and propose the governing profile(s). If the human has not selected them, ask them to choose; do not activate or deactivate profiles yourself. Then read the matching `conventions/_profiles/<profile>.yaml` registry and only the convention files it identifies as relevant.
 
-`atdd-bun.yaml` controls which profiles are active (`profiles:`; absent, every profile runs) and their settings. Turn a profile on or off only when the user asks. Adding one is always allowed; removing one loosens the gate, so the integrity check reports it until a human approves it on the base branch.
+Follow the applicable conventions and their gates. Enter at the stage that fits the task; do not assume a linear lifecycle.
 
-When the work reaches a stage whose profiles are not active yet, ask the user what they want to do and propose the matching preset from the package convention `atdd-bun.profiles.presets`.
-
-Never modify the toolkit itself (`node_modules/@afokapu/atdd-bun`, or the files atdd-bun generates); change only the configuration it offers, and loosen it only when the user asks. The integrity test and CI fail if the toolkit is modified.
+Never modify the toolkit itself (`node_modules/@afokapu/atdd-bun`) or its generated files. Change only its configuration, and loosen it only when the user asks.
 <!-- atdd-bun:end -->

package/templates/agents/atdd/SKILL.md

@@ -1,20 +0,0 @@
----
-name: atdd
-description: Use before writing or changing code, tests, or plan/ files in this repository. New intent is decomposed and delivered through the ATDD lifecycle PLAN → RED → GREEN → SMOKE → REFACTOR → TRACE, each stage gated by atdd-bun. Skip PLAN only when the change fits an acceptance that already exists.
----
-<!-- Generated by @afokapu/atdd-bun {{VERSION}}. Do not edit; run `atdd-bun agent init --replace`. -->
-
-Conventions live in `node_modules/@afokapu/atdd-bun/` (`planner-nodes/nodes/`, `conventions/`). Read the ones a stage names; do not restate them. Finish each stage by passing its gate before starting the next.
-
-Technology and architecture choices already made are the accepted ADRs listed in `docs/architecture/decisions/index.adoc`. Follow them in PLAN and GREEN; a new choice gets its own ADR under `docs/architecture/decisions/` (`planner.docs.*`).
-
-1. PLAN — Decompose the intent into wagon → WMBT → acceptance → train/interlocking → journey → contract under `plan/`, following `planner.decomposition.*`; every WMBT declares a SMOKE acceptance. Gate: `bun run atdd-bun planner`.
-2. RED — For each acceptance, write a test headed `// URN: test:{wagon}:{feature}:{ACC-ID}` and `// Phase: RED` that fails for the missing behaviour (`tester.bun.red-*`). Gate: `bun run atdd-bun tester`.
-3. GREEN — Write the least code that passes; each source file carries `URN: component:{wagon}:{feature}:{Name}:{side}:{layer}` and a `Tested-By:` block (`coder.bun.green-*`). Gate: `bun test`.
-4. SMOKE — Prove the SMOKE acceptance through the real entry point with no mocks or spies, asserting only on observable output: HTTP, markup, stdout, exit code (`tester.bun.smoke-*`, `planner.smoke.*`). Gate: `bun run atdd-bun tester`.
-5. REFACTOR — With tests green, reduce complexity, fix layering, and remove security faults until the rules pass, without changing behaviour (`coder.bun.complexity-*`, `quality-*`, `composition-*`, `design-*`, `security-*`). Gate: `bun run atdd-bun coder security`.
-6. TRACE — Every acceptance has a test, every test resolves to a declared acceptance, every source file resolves to its tests. Gate: `bun run atdd-bun traceability`, then `bun run atdd-bun all`.
-
-When a gate fails, open `<rule_id>.convention.yaml` for the reported rule ID and fix the artifact. Never skip, suppress, or edit a convention to get green.
-
-Never edit `node_modules/@afokapu/atdd-bun`, the files atdd-bun generates (this skill, `AGENTS.md` block, `.github/workflows/atdd-bun.yml`, `atdd-bun.integrity.test.ts`), or loosen `atdd-bun.yaml`. `atdd-bun.integrity.test.ts` fails if you do, and CI repeats the check on a clean install. If one of them needs to change, stop and ask the human.