agent-doc-system 1.0.0 → 1.1.0

package/README.md

@@ -1,152 +1,99 @@
-# agentdoc — portable documentation & software-catalog system
+# AgentDoc
 
-Zero runtime dependencies. One Node runtime. AgentDoc compiles a repository
-into one deterministic graph and routes a path or an entity to the minimum
-context needed to change it safely.
+![AgentDoc — Give coding agents the context they actually need](docs/assets/readme/agentdoc-hero.webp)
 
-It exists to answer one question cheaply and correctly, for an AI coding agent
-or a human reviewer:
+**Give coding agents the context they actually need.**
 
-> I am about to change *this*. What do I need to know, what must I keep
-> consistent, and which command proves it?
+AgentDoc turns your codebase, docs, contracts, and runtime evidence into a context layer your coding agent can query before it changes anything.
 
-It does that while keeping three kinds of claim apart — what the repository
-*claims*, what can be *derived* from code, and what was *observed* running —
-and surfacing their disagreements as conflicts instead of guessing.
+[![npm](https://img.shields.io/npm/v/agent-doc-system.svg)](https://www.npmjs.com/package/agent-doc-system) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![node](https://img.shields.io/badge/node-22%20%7C%2024%20%7C%2026-43853d.svg)](https://nodejs.org/)
 
-## Install the CLI
+## Give this to your coding agent
 
-The CLI is installed once per machine. Requires Node 22 or newer (22, 24 and
-26 are the tested baselines).
+Paste this into your agent **from the repository you want to use AgentDoc on**:
 
-```bash
-npm install -g github:lbframe/agent-doc-system
-
-agentdoc --version
-agentdoc doctor        # machine self-check
+```text
+Set up AgentDoc for this repository and use it as the context layer for your work.
+
+AgentDoc: https://github.com/lbframe/agent-doc-system
+
+1. Read INSTALL_FOR_AGENTS.md and install or upgrade the AgentDoc CLI.
+2. Read skills/agent-doc-system/SKILL.md.
+3. Run agentdoc doctor --project and agentdoc audit.
+4. Use the appropriate CREATE or MIGRATE workflow for this repository.
+5. Do not invent ownership, architecture, authority rules, or product intent. Ask me only for decisions AgentDoc cannot safely derive.
+6. Finish setup with agentdoc validate, agentdoc compile, and agentdoc check.
+7. From now on, use agentdoc query and agentdoc impact before changes, then agentdoc check after changes.
+8. Report anything unresolved or conflicting instead of guessing.
 ```
 
-Unpinned installs track `main`. For reproducible CI, pin a tag or commit:
-`github:lbframe/agent-doc-system#v1.0.0`.
+That is the intended onboarding path: **give the prompt to the agent, let AgentDoc build the context layer, and keep using it during development.**
 
-The install footprint is the CLI only — `bin/`, `core/`, `adapters/`,
-`schemas/`, `templates/`, `evals/`, docs and the agent skill. Nothing is ever
-copied into a project that uses AgentDoc.
+## Why AgentDoc?
 
-### Have an AI agent install it for you
+Coding agents can read code. The hard part is knowing **what matters for this change**.
 
-Paste this into a capable coding agent:
+Important context is scattered across code, documentation, API contracts, architectural decisions, CI rules, and production reality. Agents either load too much or miss something important.
 
-```text
-Install AgentDoc on this machine from:
-https://github.com/lbframe/agent-doc-system
+AgentDoc gives them a map.
 
-Read INSTALL_FOR_AGENTS.md from that repository and follow it completely.
+- **Query the right context** for a file or component.
+- **See the blast radius** before changing code.
+- **Detect drift** between code and documentation.
+- **Surface conflicts** instead of silently guessing.
+- **Verify constraints in CI** before stale knowledge becomes trusted context.
 
-Do not initialize, inspect, migrate, or modify any software project as part of
-this installation task.
+![AgentDoc in action — query, impact, check](docs/assets/readme/agentdoc-in-action.webp)
 
-When finished, verify the AgentDoc CLI and report the installed version.
-```
-
-[`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md) contains the procedure.
-
-## Use it in a project
-
-From the repository root:
+## Three commands, one workflow
 
 ```bash
-cd my-project
-agentdoc doctor --project   # is there a catalog here, and is it healthy
-agentdoc audit              # inventory the repo, classify every fact
+agentdoc query src/payments/webhook.ts
+agentdoc impact src/payments/webhook.ts
+agentdoc check
 ```
 
-Then follow the workflow the audit implies:
-
-| workflow | when | entry point |
-|---|---|---|
-| CREATE | no catalog exists | `agentdoc init`, then `agentdoc scaffold --write` |
-| MIGRATE | established repo, scattered or stale docs | `agentdoc audit`, work the report |
-| VALIDATE | before committing, in CI | `agentdoc validate` → `compile` → `check` |
-| QUERY | before and during a change | `agentdoc query <path-or-ref>` |
-| MAINTAIN | after a change | `agentdoc impact <paths>` |
+`query` tells the agent what it needs to know. `impact` shows what the change can affect. `check` verifies that the repository still agrees with itself.
 
-AgentDoc writes **project data only**: `agentdoc/` (configuration and
-descriptors you own), `docs/` skeleton files, `.agentdoc/graph.json` (the
-compiled artifact), and a CI workflow. The CLI source is never vendored into
-your repository.
+## Why not just AGENTS.md or RAG?
 
-The two directories differ in ownership, not just punctuation:
+![Why AgentDoc](docs/assets/readme/why-agentdoc.webp)
 
-- `agentdoc/` is **authored** — configuration, descriptors and observation
-  sets. Everything in it is a claim you wrote and a reviewer can diff.
-- `.agentdoc/` is **generated** — the compiled graph and other build
-  artifacts. Never edit it by hand; `compile` rewrites it and `check` rejects
-  a stale or edited one.
+AgentDoc is not another documentation file and it is not just semantic search.
 
-## Use it with an AI agent
+It combines **authored intent**, **facts derived from code**, and **runtime observations** without pretending they are the same thing. When sources disagree, AgentDoc surfaces the conflict instead of choosing a convenient answer.
 
-The agent skill is [`skills/agent-doc-system/`](skills/agent-doc-system/SKILL.md).
-Install that directory as a skill in your agent harness. It teaches the agent
-when to use the CLI, the evidence-class model, the working loop, and the
-integrity rules — with deeper material under `skills/agent-doc-system/references/`.
+## From repository knowledge to agent-ready context
 
-## What it is built on
+AgentDoc turns scattered repository knowledge into task-specific context your coding agent can query, verify, and act on.
 
-Most repositories conflate three different kinds of claim, and the confusion
-is the single largest source of wrong agent behaviour:
+![How AgentDoc works](docs/assets/readme/how-agentdoc-works.webp)
 
-| what | who says it | how it fails |
-|---|---|---|
-| what the repository **claims** | authored docs, config, manifests | drifts, is aspirational, is not tested |
-| what can be **derived** from code | imports, manifests, contracts | heuristic, incomplete, wrong about intent |
-| what was **observed** in a running system | schedulers, bindings, live APIs | goes stale, disagrees with intent |
+## Install manually
 
-A claim carries an evidence class, a confidence, and a pointer to its evidence.
-When two classes disagree about the same fact, the disagreement is **surfaced
-as a conflict**, not reconciled. There is no global precedence order, because
-authority depends on the fact: the committed manifest is authoritative for
-*intent*, the live scheduler is authoritative for *what fires*, and the
-canonical contract is authoritative for the *desired wire surface* while a
-live probe is authoritative for *what is deployed today*.
+Requires Node.js 22+.
 
-The default is fail-closed. A fact with no governing authority rule and
-disagreeing evidence is an error, and no gate passes while it stands.
-
-## Documentation
+```bash
+npm install -g agent-doc-system
+agentdoc doctor
+```
 
-| file | covers |
-|---|---|
-| [`skills/agent-doc-system/SKILL.md`](skills/agent-doc-system/SKILL.md) | how an agent uses the system |
-| [INSTALL_FOR_AGENTS.md](INSTALL_FOR_AGENTS.md) | machine installation, for an AI agent |
-| [docs/SPEC.md](docs/SPEC.md) | the normative specification: entities, graph, determinism |
-| [docs/AUTHORITY.md](docs/AUTHORITY.md) | evidence classes, conflict semantics, elections |
-| [docs/PROVENANCE.md](docs/PROVENANCE.md) | evidence records, pointers, secret handling |
-| [docs/QUERY.md](docs/QUERY.md) | the context router, budgets, freshness refusal |
-| [docs/MIGRATION.md](docs/MIGRATION.md) | CREATE and MIGRATE workflows |
-| [docs/CI.md](docs/CI.md) | the drift gate and its failure modes |
-| [docs/ADAPTERS.md](docs/ADAPTERS.md) | writing an adapter, and what must never live in one |
-| [docs/EVALS.md](docs/EVALS.md) | the routing benchmark and pre-registered thresholds |
-| [docs/COMPARISON-KODA.md](docs/COMPARISON-KODA.md) | measured comparison against the reference corpus |
-
-## Fixtures and the golden corpus
-
-- `fixtures/a-node-ts-postgres` — single Node/TypeScript service, REST, Postgres, GitHub Actions.
-- `fixtures/b-go-multi-service` — multi-service Go repository, protobuf contracts, shared library, resources.
-- `fixtures/c-alt-monorepo` — deliberately *not* `apps/`+`packages/`+`workers/`, mixed runtimes, inconsistent pre-existing docs.
-- `examples/koda` — the profile that represents a large, mature, TypeScript+Go monorepo, including the runtime-observation conflicts that motivated the authority model.
-
-## Development
+Then, inside a repository:
 
 ```bash
-node --test tests/*.test.mjs   # unit, adversarial and mode tests
-node evals/run-all.mjs         # aggregate routing evaluation (gate)
-npm run selfcheck              # agentdoc doctor, from the source checkout
+agentdoc audit
 ```
 
-## Licence of the design
+AgentDoc also ships with an Agent Skill at [`skills/agent-doc-system/`](skills/agent-doc-system/SKILL.md).
+
+## Documentation
+
+- [Getting started & migration](docs/MIGRATION.md)
+- [Authority & conflicts](docs/AUTHORITY.md)
+- [CI & verification](docs/CI.md)
+- [Specification](docs/SPEC.md)
+- [Agent Skill](skills/agent-doc-system/SKILL.md)
+
+## License
 
-The architecture, the fail-closed discipline, the provenance model and the
-warning-acceptance mechanism are extracted from a production catalog system
-that proved them at scale. The namespace, schemas, adapters, CLI and authority
-model here are new and neutral.
+[MIT](LICENSE) © 2026 lbframe

package/adapters/ansible.mjs

@@ -0,0 +1,306 @@
+// Ansible adapter: what host provisioning actually installs.
+//
+// Reads the playbooks under a unit root without running anything and without
+// evaluating a single Jinja expression. From every task reachable from a
+// playbook (plays, roles, includes, blocks) it records the host paths the
+// task creates and the services it manages. That inventory is the DERIVED side
+// of a normative requirement whose `satisfiedBy` names this adapter and whose
+// `expects` names a path or a service:
+//
+//   provided   a reachable, unconditional task installs it          deterministic
+//   absent     no reachable task does, and every task is transparent  deterministic
+//
+// Anything weaker is a candidate, which the authority engine never elects: a
+// matching task behind a `when`, or an absence claimed over a tree that holds
+// an opaque task (a shell command, a package install, a templated path, a role
+// that is not in the repository). An absence is only a fact when the adapter
+// could have seen the opposite.
+import { Adapter } from "./registry.mjs";
+import { parseYamlDocuments } from "../core/yaml.mjs";
+import { AgentDocError } from "../core/codes.mjs";
+
+// Modules that create the path they name, and the arguments naming it.
+const PATH_MODULES = {
+  copy: ["dest"],
+  template: ["dest"],
+  unarchive: ["dest", "creates"],
+  get_url: ["dest"],
+  git: ["dest"],
+  synchronize: ["dest"],
+  pip: ["virtualenv"],
+};
+// `file` creates only for these states; `lineinfile`/`blockinfile` only with
+// `create: true`.
+const FILE_CREATING_STATES = new Set(["directory", "touch", "link", "hard"]);
+const SERVICE_MODULES = new Set(["systemd", "systemd_service", "service"]);
+// Commands can do anything; their `creates` is the one thing they promise.
+const COMMAND_MODULES = new Set(["command", "shell", "script", "raw"]);
+// Modules that change no file the adapter would be asked about.
+const INERT_MODULES = new Set([
+  "debug", "set_fact", "assert", "fail", "meta", "pause", "wait_for", "stat", "ping", "setup",
+  "include_vars", "group_by", "add_host", "user", "group", "uri", "slurp", "fetch", "set_stats",
+]);
+// Task keywords, i.e. everything on a task that is not its module.
+const TASK_KEYWORDS = new Set([
+  "name", "when", "loop", "with_items", "with_dict", "with_fileglob", "loop_control", "register", "notify",
+  "become", "become_user", "become_method", "tags", "vars", "environment", "args", "ignore_errors", "changed_when",
+  "failed_when", "until", "retries", "delay", "no_log", "delegate_to", "run_once", "check_mode", "diff",
+  "listen", "timeout", "throttle", "any_errors_fatal", "module_defaults", "collections", "connection",
+]);
+const INCLUDES = new Set(["include_tasks", "import_tasks", "include"]);
+const ROLE_INCLUDES = new Set(["include_role", "import_role"]);
+
+export class AnsibleAdapter extends Adapter {
+  static adapterName = "ansible";
+  constructor() {
+    super({ name: "ansible", version: "1.0.0", kind: "source" });
+  }
+
+  // A unit that holds a playbook is a deployable infrastructure unit.
+  detect(ctx, root) {
+    const pb = playbooks(ctx.repo, root);
+    return pb.length ? { path: pb[0].path, shape: "deployable" } : null;
+  }
+
+  extract(ctx, unit) {
+    const inv = inventory(ctx.repo, unit.root);
+    if (!inv.files.length) return {};
+    for (const r of ctx.requirements || []) {
+      if (r.subject !== ctx.compRef || !r.satisfiedBy.includes("ansible") || !r.expects) continue;
+      const verdict = judge(inv, r.expects);
+      const files = verdict.files.length ? verdict.files : inv.files;
+      ctx.addFact(r.subject, r.key, verdict.value, {
+        evidenceClass: "DERIVED",
+        confidence: verdict.certain ? "deterministic" : "candidate",
+        provRecs: files.map((f) => ctx.prov.add("observed", f, "ansible-extractor", ["ass:pending"])),
+        semantics: "ansible: " + verdict.why,
+      });
+    }
+    return {
+      provisioning: {
+        installs: inv.installs.map((i) => ({ path: i.path, file: i.file, task: i.task, conditional: i.conditional })),
+        services: inv.services.map((s) => ({ name: s.name, file: s.file, task: s.task, conditional: s.conditional })),
+        opaque: inv.opaque,
+      },
+    };
+  }
+}
+
+function judge(inv, expects) {
+  const target = expects.installs || expects.service;
+  const what = expects.installs ? "path " + target : "service " + target;
+  const hits = expects.installs
+    ? inv.installs.filter((i) => i.path === target || i.path.startsWith(target + "/"))
+    : inv.services.filter((s) => s.name === target || s.name === target + ".service");
+  const sure = hits.filter((h) => !h.conditional);
+  if (sure.length) {
+    return { value: "provided", certain: true, files: uniq(sure.map((h) => h.file)), why: what + " installed by " + describe(sure[0]) };
+  }
+  if (hits.length) {
+    return { value: "provided", certain: false, files: uniq(hits.map((h) => h.file)), why: what + " installed only conditionally by " + describe(hits[0]) };
+  }
+  if (inv.opaque.length) {
+    return {
+      value: "absent", certain: false, files: [],
+      why: "no task installs " + what + ", but absence cannot be proven: " + inv.opaque.slice(0, 3).join("; ") +
+        (inv.opaque.length > 3 ? " (+" + (inv.opaque.length - 3) + " more)" : ""),
+    };
+  }
+  return { value: "absent", certain: true, files: [], why: "no reachable task installs " + what };
+}
+
+function describe(h) {
+  return h.file + (h.task ? " (" + h.task + ")" : "");
+}
+
+function uniq(a) {
+  return [...new Set(a)].sort();
+}
+
+function parse(repo, file) {
+  try {
+    return parseYamlDocuments(repo.readText(file), file, { allowSequenceRoot: true }).map((d) => d.doc);
+  } catch (e) {
+    if (e instanceof AgentDocError) return null;
+    throw e;
+  }
+}
+
+function isYaml(f) {
+  return /\.ya?ml$/.test(f);
+}
+
+function playbooks(repo, root) {
+  const out = [];
+  for (const f of repo.walk(root)) {
+    if (!isYaml(f) || /(^|\/)(tasks|handlers|vars|defaults|meta|group_vars|host_vars|templates|files)\//.test(f.slice(root.length))) continue;
+    const docs = parse(repo, f);
+    if (!docs) continue;
+    const plays = docs.flatMap((d) => (Array.isArray(d) ? d : []));
+    if (plays.length && plays.every((p) => p && typeof p === "object" && (p.hosts !== undefined || p.import_playbook !== undefined))) {
+      out.push({ path: f, plays });
+    }
+  }
+  return out.sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+
+// Every task reachable from a playbook under `root`, walked in a fixed order.
+function inventory(repo, root) {
+  const inv = { files: new Set(), installs: [], services: [], opaque: [] };
+  const seen = new Set();
+  const opaque = (file, task, why) => inv.opaque.push(file + (task ? " (" + task + ")" : "") + ": " + why);
+
+  const dirOf = (p) => p.split("/").slice(0, -1).join("/");
+  const join = (dir, rel) => {
+    const parts = (dir ? dir.split("/") : []).concat(rel.split("/"));
+    const out = [];
+    for (const s of parts) {
+      if (s === "" || s === ".") continue;
+      if (s === "..") { if (!out.length) return null; out.pop(); } else out.push(s);
+    }
+    return out.join("/");
+  };
+  const templated = (v) => typeof v === "string" && /\{\{|\{%/.test(v);
+
+  const findRole = (name, fromDir) => {
+    for (const base of [fromDir, root]) {
+      for (const ext of ["yml", "yaml"]) {
+        const p = join(base, "roles/" + name + "/tasks/main." + ext);
+        if (p && repo.exists(p)) return p;
+      }
+    }
+    return null;
+  };
+
+  const walkFile = (file, conditional, kind) => {
+    const key = file + "|" + conditional + "|" + kind;
+    if (seen.has(key)) return;
+    seen.add(key);
+    inv.files.add(file);
+    const docs = parse(repo, file);
+    if (!docs) { opaque(file, null, "not parseable as YAML"); return; }
+    const list = docs.flatMap((d) => (Array.isArray(d) ? d : []));
+    if (kind === "playbook") for (const p of list) walkPlay(file, p, conditional);
+    else walkTasks(file, list, conditional);
+  };
+
+  const walkPlay = (file, play, conditional) => {
+    if (!play || typeof play !== "object") return;
+    if (play.import_playbook !== undefined) {
+      const ref = String(play.import_playbook);
+      const p = !templated(ref) && join(dirOf(file), ref);
+      if (p && repo.exists(p)) walkFile(p, conditional || play.when !== undefined, "playbook");
+      else opaque(file, null, "imported playbook not resolvable in the repository: " + ref);
+      return;
+    }
+    const cond = conditional || play.when !== undefined;
+    for (const section of ["pre_tasks", "roles", "tasks", "post_tasks", "handlers"]) {
+      const items = play[section];
+      if (!Array.isArray(items)) continue;
+      if (section === "roles") {
+        for (const r of items) {
+          const name = typeof r === "string" ? r : r && (r.role || r.name);
+          walkRole(file, String(name), cond || (r && typeof r === "object" && r.when !== undefined));
+        }
+      } else {
+        walkTasks(file, items, cond);
+      }
+    }
+  };
+
+  const walkRole = (file, name, conditional) => {
+    const main = !templated(name) && findRole(name, dirOf(file));
+    if (main) walkFile(main, conditional, "tasks");
+    else opaque(file, null, "role not found in the repository: " + name);
+  };
+
+  const walkTasks = (file, tasks, conditional) => {
+    for (const t of tasks) {
+      if (!t || typeof t !== "object" || Array.isArray(t)) continue;
+      const cond = conditional || t.when !== undefined;
+      const label = typeof t.name === "string" ? t.name : null;
+      if (Array.isArray(t.block)) {
+        walkTasks(file, t.block, cond);
+        // A rescue runs only when the block failed: never an unconditional install.
+        for (const k of ["rescue", "always"]) if (Array.isArray(t[k])) walkTasks(file, t[k], cond || k === "rescue");
+        continue;
+      }
+      const modKey = Object.keys(t).find((k) => !TASK_KEYWORDS.has(k));
+      if (!modKey) continue;
+      const mod = modKey.split(".").pop();
+      const raw = t[modKey];
+      const args = { ...parseFreeForm(raw), ...(t.args && typeof t.args === "object" ? t.args : {}) };
+      // A loop runs the module once per item with a templated argument; the
+      // adapter does not expand it.
+      const looped = t.loop !== undefined || Object.keys(t).some((k) => k.startsWith("with_"));
+
+      if (INCLUDES.has(mod)) {
+        const ref = typeof raw === "string" ? raw.split(/\s+/)[0] : args.file;
+        const p = ref && !templated(ref) && join(dirOf(file), String(ref));
+        if (p && repo.exists(p)) walkFile(p, cond, "tasks");
+        else opaque(file, label, "included task file not resolvable in the repository: " + ref);
+        continue;
+      }
+      if (ROLE_INCLUDES.has(mod)) {
+        walkRole(file, String(args.name), cond);
+        continue;
+      }
+      const record = (list, entry) => list.push({ ...entry, file, task: label, conditional: cond });
+      if (PATH_MODULES[mod] || mod === "file" || mod === "lineinfile" || mod === "blockinfile") {
+        let names = PATH_MODULES[mod] || ["path", "dest", "name"];
+        if (mod === "file" && !FILE_CREATING_STATES.has(String(args.state || "file"))) names = [];
+        if ((mod === "lineinfile" || mod === "blockinfile") && !isTrue(args.create)) names = [];
+        for (const n of names) {
+          const v = args[n];
+          if (v === undefined) continue;
+          if (templated(v) || looped) { opaque(file, label, mod + " " + n + " is templated: " + v); continue; }
+          record(inv.installs, { path: normalisePath(String(v)) });
+        }
+        continue;
+      }
+      if (SERVICE_MODULES.has(mod)) {
+        const n = args.name;
+        if (n === undefined) continue;
+        if (templated(n) || looped) opaque(file, label, mod + " name is templated: " + n);
+        else record(inv.services, { name: String(n) });
+        continue;
+      }
+      if (COMMAND_MODULES.has(mod)) {
+        if (args.creates !== undefined && !templated(args.creates) && !looped) {
+          record(inv.installs, { path: normalisePath(String(args.creates)) });
+        } else {
+          opaque(file, label, mod + " task without a literal `creates`");
+        }
+        continue;
+      }
+      if (INERT_MODULES.has(mod)) continue;
+      opaque(file, label, "module " + modKey + " is not modeled and may change the host");
+    }
+  };
+
+  for (const pb of playbooks(repo, root)) walkFile(pb.path, false, "playbook");
+  const byPath = (a, b) => (a.path + a.file < b.path + b.file ? -1 : a.path + a.file > b.path + b.file ? 1 : 0);
+  return {
+    files: [...inv.files].sort(),
+    installs: inv.installs.sort(byPath),
+    services: inv.services.sort((a, b) => (a.name + a.file < b.name + b.file ? -1 : 1)),
+    opaque: [...new Set(inv.opaque)].sort(),
+  };
+}
+
+// `file: path=/a state=directory` — the key=value shorthand.
+function parseFreeForm(raw) {
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) return raw;
+  if (typeof raw !== "string") return {};
+  const out = {};
+  for (const m of raw.matchAll(/(\w+)=("[^"]*"|'[^']*'|\S+)/g)) out[m[1]] = m[2].replace(/^["']|["']$/g, "");
+  return out;
+}
+
+function isTrue(v) {
+  return v === true || /^(yes|true)$/i.test(String(v));
+}
+
+function normalisePath(p) {
+  return p.length > 1 ? p.replace(/\/+$/, "") : p;
+}

package/adapters/github-actions.mjs

@@ -12,11 +12,11 @@ export class GitHubActionsAdapter extends Adapter {
   constructor() {
     super({ name: "github-actions", version: "1.0.0", kind: "ci" });
   }
-  detect(ctx, root) {
-    const p = root + "/.github/workflows";
-    if (!ctx.repo.isDir(p)) return null;
-    return { path: p, shape: "importable" };
-  }
+  // No detect(): a workflow directory is not a unit marker. It is not evidence
+  // of an importable or deployable artifact, and a marker path is hashed as a
+  // file for provenance, so a directory marker can only fail. GitHub runs only
+  // the repository-root .github/workflows; a nested one (vendored upstream, a
+  // subtree) is inert and is ignored here too.
   contracts(ctx) {
     const dir = ".github/workflows";
     if (!ctx.repo.isDir(dir)) return [];

package/adapters/index.mjs

@@ -20,13 +20,14 @@ import { EventsAdapter } from "./events.mjs";
 import { DeployConfigAdapter } from "./deploy-config.mjs";
 import { ObjectStoreAdapter } from "./object-store.mjs";
 import { CacheAdapter } from "./cache.mjs";
+import { AnsibleAdapter } from "./ansible.mjs";
 
 const REGISTRY = new Map();
 for (const C of [
   GenericAdapter, NodeAdapter, PnpmAdapter, TurborepoAdapter, TypeScriptAdapter,
   GoAdapter, OpenApiAdapter, ProtobufAdapter, GraphQLAdapter, OidcAdapter,
   GitHubActionsAdapter, DockerfileAdapter, WranglerAdapter, DatabaseAdapter,
-  EventsAdapter, DeployConfigAdapter, ObjectStoreAdapter, CacheAdapter,
+  EventsAdapter, DeployConfigAdapter, ObjectStoreAdapter, CacheAdapter, AnsibleAdapter,
 ]) {
   REGISTRY.set(C.prototype.constructor.adapterName, new C());
 }