darkprint 0.1.0

package/skill/darkprint/references/dot-and-attractor.md

@@ -0,0 +1,300 @@
+# The DOT, and what a card becomes when it is compiled
+
+Three things live here: how to write `topology.dot` so it loads clean, how a fork is
+guarded so a runner takes the arm the author meant, and what happens to a card when the
+bundle is compiled into a pipeline a runner takes. **This skill compiles nothing**, and no
+published bundle folder carries a compiled graph. The third part is background, and an
+author is entitled to know what their `spec` turns into and which parts of their card never
+leave DarkPrint.
+
+---
+
+## Part 1: writing `topology.dot`
+
+### The shape
+
+```dot
+digraph help_centre_line {
+  rankdir=LR;
+  node [shape=box, style=rounded];
+
+  // One statement per node. The id is the instance; the card is the definition.
+  outline_writer  [card="article-outliner@1.0.0"];
+  draft_writer    [card="article-drafter@1.0.0"];
+
+  // Edges carry data. Pin the ports whenever more than one pair would fit.
+  outline_writer -> editorial_check [label="acceptance criteria", out="criteria", in="criteria"];
+}
+```
+
+### Node ids
+
+`[A-Za-z_][A-Za-z0-9_]*`. No hyphens, no leading digit, never quoted.
+
+- A hyphen or a quoted id is `attractor/bad-node-id` or `attractor/quoted-node-id` (warnings,
+  visible on `/upload`, and they make the bundle look broken).
+- `digraph`, `edge`, `graph`, `node`, `strict`, `subgraph` are statement keywords and cannot
+  open a node statement. The same warning, and the same fix: rename the node.
+- `start`, `Start`, `exit`, `end` are legal here and **no diagnostic warns about them**.
+  Attractor resolves those names as the pipeline's entry and exit, so they collide with the
+  boundary nodes DarkPrint synthesises when it compiles; the exporter renames such a node
+  and records the author's id in a `dp_node` attribute. Avoid them, because the compiled
+  file then no longer says what the topology says.
+
+The card id grammar is the other one: `^(?:namespace/)?[a-z0-9]+(-[a-z0-9]+)*$`. Lowercase,
+hyphens, no underscores. **The two grammars are incompatible for every multi-word name**, so
+always write the pin explicitly:
+
+```dot
+editorial_check [card="editorial-check@1.0.0"];
+```
+
+`card="id@version"` is canonical and always wins. The bare `version="1.0.0"` fallback makes the
+node id double as the card id, which only works for a single lowercase word. Do not use it.
+An unpinned pointer (`card="solver"`, `card="solver@latest"`, `version="1.x"`) is
+`bundle/unpinned-card`, an **error**.
+
+### Attribute syntax
+
+Attributes are **comma**-separated. `[a=1; b=2]` and `[a=1 b=2]` are both
+`attractor/attr-separator`.
+
+Comments are `//` or `/* … */`. A `#` comment is `attractor/hash-comment`.
+
+No string concatenation (`"a" + "b"`), no `<html-like>` literals, and a duration is an integer
+followed by one of `ms s m h d`. Anything else is `attractor/unsupported-value`.
+
+### Never write `type=` on a node
+
+`type` is a **reserved Attractor node attribute** and means *handler override*. DarkPrint's
+node type is an ontology term inside the YAML card and never a DOT attribute. Writing it is
+`attractor/reserved-attribute`, and the value would be read as something entirely different
+from what you meant.
+
+**That is the only reserved node attribute the linter reports.** The rest of Attractor's
+reserved node names (`prompt`, `max_retries`, `llm_model`, `label`, `shape`, `class`,
+`timeout`, `goal_gate`, `fidelity`, `thread_id`, `retry_target`, `fallback_retry_target`,
+`llm_provider`, `reasoning_effort`, `auto_status`, `allow_partial`) pass through the linter
+in silence and are written straight into the compiled file, where they configure the run.
+A `prompt=` on a topology node replaces the card's `spec` at run time with nothing saying
+so. Grep your own DOT for them before you call it finished. The bundle's own node
+attributes are `card`, and optionally `digest` (a prefix of the card digest, checked as
+`bundle/digest-mismatch`).
+
+On an **edge**, `label`, `condition`, `weight`, `fidelity`, `thread_id` and `loop_restart` are
+reserved. `label`, `condition` and `weight` are the three this skill writes deliberately, and
+the next section is about them. `out=` and `in=` are not reserved, which is what lets the
+port pins ride along safely.
+
+### One graph, one file
+
+Only the first graph in the file is read (`attractor/multiple-graphs`, `dot/unsupported`). It
+must be a `digraph`, and every edge `->`; a `graph` or a `--` edge is `dot/not-directed`, an
+**error** that stops the pipeline dead. Do not write `strict digraph`.
+
+Only **one** `.dot` file goes in the bundle. The upload page classifies files by name: the
+first `.dot` or `.gv` is the topology and a second one is demoted with a note.
+
+### Filenames are load-bearing
+
+The upload page, the CLI and the publish route all read roles off filenames, so:
+
+- exactly one `topology.dot`;
+- cards under `cards/`, named `<card-id>@<version>.yaml`;
+- `blueprint.yaml` at the root is the manifest (slug, title, summary, description, category,
+  tags), and `ontology/extensions.yaml` is the local vocabulary when there is one;
+- **never name a card `blueprint.yaml` or `extensions.yaml`.** A card named either is
+  classified as the manifest or the vocabulary, vanishes from the card set, and every node
+  pinning it reports `bundle/missing-card`.
+
+Nothing in the engine requires a card's filename to match its `id` and `version`; the card's
+own fields are its identity. Matching them is a courtesy to whoever opens the folder, and this
+skill always does it.
+
+---
+
+## Part 2: the guard on a fork
+
+A node with two or more outgoing edges is a fork, and a runner takes exactly one arm. Which
+one is decided in a fixed order, from the Attractor spec's edge selection:
+
+1. an edge whose `condition` holds;
+2. an edge whose `label` matches the label the node's own status asked for
+   (`preferred_label`);
+3. an edge to a node id the status suggested as next;
+4. the higher `weight`, default 0;
+5. on a tie, **the target node id that sorts first**.
+
+So two bare edges out of one node are a branch decided by the spelling of the node names.
+The shipped starter learned this the hard way: while `tester -> debugger` and
+`tester -> deployer` carried a label and nothing else, `debugger` beat `deployer` on the
+fourth character and the factory repaired forever without releasing. Every fork this skill
+writes carries a `condition` on every arm, or a `weight` the author chose on purpose.
+
+### The grammar
+
+```
+Condition ::= Clause ( '&&' Clause )*
+Clause    ::= Key Operator Literal
+Key       ::= 'outcome' | 'preferred_label' | 'context.' Path
+Operator  ::= '=' | '!='
+```
+
+`outcome` is the value a runner sets from the node's own status on every pass, and it is
+the key to use for a verdict. `preferred_label` is the label the node asked for, when a
+node writes one. `context.<path>` reads a value the run has stored under a dotted path.
+
+The literal is compared as text, so `outcome=success`, `outcome!=success` and
+`context.retries=2` all parse. Quote a literal with spaces: `preferred_label="ship it"`.
+
+What does **not** parse, and what the linter reports as `attractor/condition-syntax`:
+`||`, `!`, `>`, `<`, `>=`, `<=`, `contains`, `matches`, parentheses, a bare key
+(`tests_pass`), a bare literal (`success`), and the empty string. A runner grades that rule
+as an error and refuses the whole pipeline before the first node runs, so a mistyped guard
+is a blueprint that validates and never executes. Note `condition=""` separately: it is not
+a syntax error to a runner but it is NO condition, so the edge falls back to the order above.
+
+### The shape this skill writes
+
+```dot
+check_step -> fix_step  [label="failure evidence", style=dashed, condition="outcome!=success"];
+check_step -> ship_step [label="approved", condition="outcome=success"];
+```
+
+One key against its own negation is the only total split the grammar can make: there is no
+disjunction, so `partial_success`, `retry`, `fail` and a verdict the check could not reach
+all land on the arm that does not ship, and exactly one arm is ever eligible. A `decision`
+node, whose whole job is to route, follows the same rule with `context.<path>` keys when the
+route is not a plain verdict, and every arm still carries a guard.
+
+`weight` is for a preference among arms that are all allowed: `weight=10` on the arm to
+take when nothing else decides. It is an integer, and the linter checks nothing about it.
+
+Nothing in DarkPrint evaluates a guard. A guarded edge counts exactly as much as an
+unguarded one in every risk reading, because the guard runs on somebody else's machine
+against data the engine never sees. `condition="false"` does not remove an edge from the
+criteria walk.
+
+---
+
+## Part 3: what a card becomes
+
+`darkprint export <dir> --attractor` compiles a resolved bundle into an Attractor DOT and
+writes it to stdout. **This skill does not write that file**, and a published bundle folder
+does not carry one: duplicating the emit rules here would let the two drift, and the
+exporter is the one that gets tested against Attractor's parser on every build.
+
+It is documented because an author writing a `spec` should know it is the thing that will be
+handed to the agent verbatim.
+
+| the card says | the compiled node says |
+|---|---|
+| `spec` | `prompt`, the payload the agent actually receives |
+| `name` | `label` |
+| `model` | `llm_model`, Attractor's reserved model identifier |
+| `params.max_retries` (or `max_iterations`, or `maxIterations`) | `max_retries` |
+| `params.tool_command`, on a `shell-tool` | `tool_command` |
+| `type` and `phases` | `class`, every name prefixed `dp-` |
+| `type: agent` | `shape=box` → the `codergen` handler |
+| `type: validation` | `shape=box` → the `codergen` handler |
+| `type: tool` | `shape=box` → the `codergen` handler |
+| `type: human-gate` | `shape=hexagon` → the `wait.human` handler |
+| `type: human-input` | `shape=hexagon` → the `wait.human` handler |
+| `type: decision` | `shape=diamond` → the `conditional` handler |
+| `type: shell-tool` | `shape=parallelogram` → the `tool` handler |
+| `type: parallel` | `shape=component` → the `parallel` handler |
+| `type: parallel.fan-in` | `shape=tripleoctagon` → the `parallel.fan_in` handler |
+| `type: manager-loop` | `shape=house` → the `stack.manager_loop` handler |
+| edge `label`, `condition`, `weight` | the same three edge attributes, carried verbatim |
+| the manifest's `summary` and `title` | graph `goal` and `label` |
+
+A `__start` and a `__exit` node are **synthesised** rather than borrowed from your graph: your
+entry node is an ordinary card node with a prompt to run, and re-shaping it into a boundary
+would mean that prompt never runs. `card="id@version"` rides along in the compiled file
+untouched, because Attractor ignores attributes it does not reserve.
+
+### What the compiled file cannot say
+
+The compiled DOT opens with a comment listing every attribute Attractor reads that a
+DarkPrint blueprint has no way to set. That list is derived from the engine rather than
+written by hand, so it is the current answer and not a sentence somebody forgot to update.
+Today it covers goal gates, timeouts, the whole retry policy above `max_retries`, fidelity,
+thread ids, the parallel join policy, the manager-loop controls and the graph-level
+defaults, hooks and model stylesheet. Each one falls back to whatever the runner's own
+default is, and nothing warns anybody: a gate nobody wrote is a gate that never fires. An
+author who needs one adds it to the compiled file by hand, and a later export replaces the
+whole file. The same two lists are printed into every published bundle's `README.md`, under
+"What these files leave to the runner".
+
+The other half is what stops at the DarkPrint boundary. A node's `prompt` is everything the
+runner receives from its card, so ports, dependencies, `cannot`, `will_not` and
+`risk_markers` are not enforced by anything in the compiled file. They are enforced by the
+engine, at the moment the bundle is validated, which is a different moment from the moment
+the pipeline runs.
+
+Three consequences for how you write a card:
+
+1. **`spec` is the prompt.** It is delivered to an agent that does not see the rest of the
+   graph, so it has to be self-sufficient, and it must respect the isolation the topology
+   declares. An absent edge with the criteria paraphrased into the prose is a false isolation.
+2. **`model` is what the node runs on unless somebody edits the file.** DarkPrint writes
+   `llm_model` and writes no `model_stylesheet`, so there is no sheet in the compiled graph
+   to override it. Absence is still an answer: a card that names no model emits no
+   `llm_model` at all, and the node takes whatever the runner supplies.
+3. **The iteration cap has one home.** Write it as a top-level key of `params`. The security
+   analyzer and the exporter read it through the same function, so a cap that reads as
+   uncapped would also compile as unbounded. And it is the number Attractor counts, attempts
+   after the first, so `max_retries: 2` is three attempts in all.
+
+---
+
+## Part 4: reading a pipeline back
+
+`darkprint import <pipeline.dot> --as <handle> --out <dir>` is the other direction. It reads
+an Attractor pipeline and writes a **draft** bundle: a `topology.dot` and one card per node,
+in the layout the upload page and `darkprint validate` both accept. The mapping table above
+is run backwards, from the same table, so the two directions cannot drift apart.
+
+| the pipeline says | the card says |
+|---|---|
+| `prompt` | `spec` |
+| `label` | `name` |
+| `llm_model` | `model` |
+| `max_retries` | `params.max_iterations`, the first of the three accepted cap keys, holding the same number |
+| `tool_command` | `params.tool_command`, on a `shell-tool` card |
+| `shape` | `type`, through the table above |
+| `class` | which of a shared shape's two types, and the `phase` list |
+| `card="id@version"` | the card's own `id` and `version` |
+
+### Both flags are required, and neither has a default
+
+`--out` because a bundle is a folder and a folder cannot go down a pipe. `--as` because a
+`prompt` is somebody's writing: every synthesised card carries `author` set to the handle you
+give and `provenance` set to `derived:attractor <the pipeline>`, so a compiled card can be
+told from a written one by reading it or by grepping for the marker. Every card comes out at
+version `0.1.0`. It is a draft and it is meant to be edited before anybody publishes it.
+
+### What a round trip keeps, and what it does not
+
+`tests/attractor-round-trip.test.ts` runs a corpus of pipelines out and back and asserts that
+every attribute an Attractor runner reads survives unchanged. What it does not keep is
+recorded there too, exactly, rather than left to be discovered:
+
+- **Ports, dependencies, `cannot`, `will_not` and `risk_markers` come back empty.** No
+  Attractor file has ever carried them, so an import cannot invent them. You write them.
+- **A node with no `prompt` becomes a card with no `spec`.** Attractor allows it; a DarkPrint
+  card does not. The import says which node, and the bundle does not resolve until you write
+  the missing half.
+- **`shape=box` comes back as `agent` and `shape=hexagon` as `human-gate`** unless the file
+  carries the `class` DarkPrint writes. Attractor selects one handler for `agent` and
+  `validation` alike, and stores nothing that separates them.
+- **Subgraphs are gone**, and with them the classes derived from a subgraph's label.
+- **Every attribute in the compiled file's own disclosure header is dropped**: goal gates,
+  timeouts, the retry policy above `max_retries`, the parallel and manager-loop controls, the
+  graph defaults, hooks and the model stylesheet.
+- **An attribute on an edge to the start or the exit is dropped**, because DarkPrint
+  synthesises both boundary nodes and derives their wiring rather than storing it.
+
+A DarkPrint bundle that goes out through `export` and back through `import` comes home byte
+for byte, the blueprint digest line aside. The losses above are what a *foreign* pipeline
+pays, and they are the price of the two formats not being the same size.

package/skill/darkprint/references/live-preview.md

@@ -0,0 +1,95 @@
+# The live preview
+
+An optional window on the interview. When the author opts in, the blueprint-writing skill
+posts the draft to darkprint.io after every phase, and the page at
+`https://www.darkprint.io/tutorial/live/<token>` draws the graph as it takes shape, in the
+same panel a published blueprint page uses. The site runs nothing: it keeps the last draft it
+received and shows it. Every field below is transcribed from `lib/core/tutorial/live.ts`, the
+one contract the skill, the routes and the page share.
+
+## The three endpoints
+
+| call | body | answers |
+|---|---|---|
+| `POST https://www.darkprint.io/api/tutorial/live` | `{}` | `{ token, url, expiresAt }` |
+| `GET https://www.darkprint.io/api/tutorial/live/<token>` | none | `{ token, revision, updatedAt, expiresAt, draft }`, with `ETag: "<revision>"` and a 304 on `If-None-Match` |
+| `PUT https://www.darkprint.io/api/tutorial/live/<token>` | a `LiveDraft` | `{ revision, updatedAt, expiresAt }` |
+
+The token is 32 URL-safe characters, `[A-Za-z0-9_-]{32}`, and anything else is refused
+before the store is asked. A page lives 24 hours from the moment it was opened, and every
+accepted PUT refreshes that. The contract caps one draft at 512 KiB of JSON. A 400 names the
+field that is wrong in one sentence; fix the payload and send again. The page polls the GET
+itself, so the skill never calls it.
+
+Open once and remember the token from the answer:
+
+```
+curl -fsS -X POST https://www.darkprint.io/api/tutorial/live \
+  -H "content-type: application/json" --data '{}'
+```
+
+When the author arrived with the URL already, the token is its last path segment and the POST
+is skipped; when that URL's origin is not `https://www.darkprint.io`, use its origin in every
+line here, because the page lives where it was opened. Each shell command may run in a fresh
+shell, so set the variable at the head of every command rather than exporting it once. Then,
+at each boundary, the JSON goes on stdin, so nothing is written to disk before the author has
+said yes to the files:
+
+```
+DARKPRINT_LIVE_TOKEN=<token>; \
+curl -fsS -X PUT "https://www.darkprint.io/api/tutorial/live/$DARKPRINT_LIVE_TOKEN" \
+  -H "content-type: application/json" --data-binary @- <<'JSON'
+{ "phase": "nodes", "task": "...", "bundle": { "manifest": { ... }, "dot": "...", "cardFiles": { ... } }, "ledger": { ... } }
+JSON
+```
+
+A failed PUT, whether the network is down or the answer is a 400, is one line to the author,
+and the interview goes on. The folder is the deliverable; the page is a window on it.
+
+## `LiveDraft`, field by field
+
+| field | required | what |
+|---|---|---|
+| `phase` | yes | one of `need`, `reuse`, `nodes`, `ports`, `guards`, `risk`, `written`, `enriched`, `published` |
+| `task` | no | the author's one-sentence answer to Q0.1 |
+| `bundle.manifest` | yes | `slug`, `title`, `summary` as strings and `tags` as an array of strings; `description` and `category` ride along once Q5.3 derives them |
+| `bundle.dot` | yes | the DOT so far; `""` before any node has a name |
+| `bundle.cardFiles` | yes | an object keyed `cards/<id>@<version>.yaml` whose values are the YAML text; `{}` before any card is drafted |
+| `ledger` | no | `settled`, `open`, `blocked`: the three lists of posture rule 4, each an array of strings |
+| `hits` | no | every registry hit considered, each `{ kind, ref, title, score }`: `kind` is `blueprint` or `card`, `ref` is `owner/slug` or `id@version`, `score` is the search module's own number |
+| `publishedRef` | no | `owner/slug` once the author has published, so the page can link to it |
+
+`hits` comes straight off the search answer. A blueprint hit already carries `ref`, `title`
+and `score`; a card hit carries `name` where the draft wants `title`, so copy `name` into it.
+Send every hit shown to the author, including the ones recommended against; the page is
+meant to show the search happening.
+
+**Before Q5.3 has derived the manifest**, send provisional values, because the PUT refuses a
+draft without them: `title` is Q0.1 as a title, `summary` is the Q0.1 sentence, `slug` is the
+title in card-id grammar (`^[a-z0-9]+(-[a-z0-9]+)*$`), `tags` is `[]`. Replace them with the
+derived ones at `risk`.
+
+**The bundle may be partial.** The PUT checks the shape of the JSON and nothing else: a draft
+that `darkprint validate` would refuse with `bundle/port-mismatch` is still accepted, and the
+page draws what the engine can resolve and lists the rest as still to settle. Send the DOT as
+soon as the nodes have names, and each card as soon as it exists in memory. The files on the
+author's disk are written when SKILL.md says and not before; the draft is a copy of what is
+settled so far, never a copy of the folder.
+
+## The phases, and when to send each
+
+| `phase` | send it | the page's label, and what the draft carries by then |
+|---|---|---|
+| `need` | after Q0.6, before searching | "The need": the task sentence and no graph yet |
+| `reuse` | after Phase 1, whether or not anything fit | "Reuse before drawing": the hits considered, with their scores |
+| `nodes` | after Phase 2, once the split is agreed | "The nodes": a DOT with named nodes and no edges |
+| `ports` | after Q3.6, when the ledger closes | "Ports and edges": the derived edges, and the ports still unmatched in `ledger.open` |
+| `guards` | after Q4.7 | "Isolation and guards": the `cannot` entries and the condition on every fork |
+| `risk` | after the show-back, before writing | "Risk and identity": the manifest as derived, the risk markers, the names |
+| `written` | after the files are written and validated | "Folder written": the whole bundle, as it sits on disk |
+| `enriched` | after an enrich merge | "Enriched from the registry": the grown graph, and the hits that fed it |
+| `published` | after the author publishes, with `publishedRef` | "Published to an account": a link to the blueprint's page |
+
+The quoted words are `LIVE_PHASE_LABELS` from the contract, the heading the page prints for
+each phase. What follows each is what the draft carries at that point; the page draws
+whatever of it resolves, and a draft sent twice under the same phase replaces the earlier one.

package/skill/darkprint/references/ontology.md

@@ -0,0 +1,242 @@
+<!--
+  GENERATED FILE. Do not edit by hand.
+  Rendered from lib/core/ontology/core.ts and lib/core/config.ts by scripts/skill-refs.ts.
+  Regenerate with: npm run generate:skill-refs
+  scripts/generate-skill-refs.test.ts fails the suite if this file drifts.
+-->
+
+# DarkPrint core vocabulary
+
+54 terms. The vocabulary carries no version of its own: it names what an
+Attractor node IS, and Attractor fixes those shapes in its own spec.
+
+Every card field that names a term is resolved against this list. A term that is not
+here is `card/unknown-term` (error). A term of the wrong kind, a `data-type` in the
+`tools` list or a `tool` in `type`, is `card/wrong-term-kind` (error).
+
+A card names no vocabulary version either. There is one vocabulary and every card is
+read against it, so writing `ontology_version:` on a card is `card/retired-field`
+(warning).
+
+## phase: the five, closed
+
+Optional and repeatable. A card may declare none, one, or several. `phase: []`, or the
+field omitted entirely, is a **complete and correct answer**, and the validator emits
+nothing at all about it: an intake step, a retrieval step and a memory store sit in none
+of the five. Phase coverage is descriptive and nothing scores off it, so never invent a
+phase to fill a strip.
+
+This is the one dimension that is never namespaced: `me/triage` as a phase is
+`card/namespaced-phase` (error). Listed in lifecycle order, which is the order coverage
+reports in.
+
+| id | label | meaning |
+| --- | --- | --- |
+| `planning` | Planning | From the request to a plan and the acceptance criteria. |
+| `implementation` | Implementation | From the plan to the artefact. |
+| `testing` | Testing | Runs the checks and produces the evidence. |
+| `debugging` | Debugging | From failure evidence to a targeted fix. |
+| `deployment` | Deployment | Release, publication, delivery. |
+
+## node-type: what does the job
+
+Exactly one per card, in `type`. Three of these are **abstract categories** and a node
+should not be typed with one: they exist so the metrics can ask a subsumption question.
+
+`human-gate` and `human-input` are subsumed by `human-in-the-loop` and carry
+`impliesHuman`. Declaring one of them is the whole of how a card says a person acts at
+the node: there is no second field beside `type` to set, and nothing else on the card
+can say otherwise.
+
+The `orchestration` branch is control flow: `parallel` splits the run, `parallel.fan-in`
+joins it back, `manager-loop` supervises a sub-run and decides whether it repeats. The
+three are named after the Attractor handlers they compile to, so a bundle's `topology.dot`
+reads the same on both sides.
+
+Autonomy is read twice off `type` and the weaker reading is the one that lands in a band.
+How much runs alone: the share of nodes whose `type` is *not* subsumed by
+`human-in-the-loop`. How much of the deciding runs alone: the same share taken over the
+**control points** only, which are the nodes under `evaluative` or `orchestration` plus
+`human-gate`, and it decides a band only from 2 control points up. Bands: > 0.9 closed-loop, ≥ 0.7 conditional, ≥ 0.5 supervised, below that assisted.
+
+| id | label | broader | implies human | governs flow | meaning |
+| --- | --- | --- | --- | --- | --- |
+| `agent` | Agent | — | no | no | A model that reasons and produces non-deterministic output. |
+| `decision` | Decision | `evaluative` | no | yes | A conditional switch that evaluates and routes without producing artefacts. |
+| `evaluative` | Evaluative | — | no | yes | The abstract category of nodes that judge or route rather than produce an artefact. |
+| `human-gate` | Human gate | `human-in-the-loop` | yes | yes | A point where a person must approve or reject. |
+| `human-in-the-loop` | Human in the loop | — | no | no | The abstract category of nodes at which a person acts, and the one the autonomy metric interrogates. |
+| `human-input` | Human input | `human-in-the-loop` | yes | no | A point where a person must supply data or content. |
+| `manager-loop` | Manager loop | `orchestration` | no | yes | Supervises a sub-run, polling the work and deciding whether to act on it and whether to go round again until its stop condition holds. |
+| `orchestration` | Orchestration | — | no | yes | The abstract category of nodes that shape the run itself: how many copies of a step exist, when they converge, whether the whole thing repeats. |
+| `parallel` | Parallel | `orchestration` | no | yes | Splits the run into branches that proceed at the same time, producing nothing itself and deciding only how many copies of the work exist. |
+| `parallel.fan-in` | Parallel fan-in | `orchestration` | no | yes | Waits for the branches a parallel node opened and joins them back into one line, deciding when the run continues rather than what it continues with. |
+| `shell-tool` | Shell tool | `tool` | no | no | A tool node whose instruction is a shell command the runner executes directly. |
+| `tool` | Tool | — | no | no | A deterministic operation: running tests, compiling, formatting, calling an API. |
+| `validation` | Validation | `evaluative` | no | yes | Compares an artefact against criteria and produces a verdict with evidence. |
+
+**The trap.** `tool`'s own description names running tests, which invites typing the
+test runner `tool`. The `criteria-leak` check defines its generator set as the
+predecessors of nodes typed `validation`; type the judge `tool` and that set is empty,
+the check does not run, and the blueprint scores 4 on security because nothing was
+asked, not because nothing was found. The engine says so with
+`analysis/criteria-leak-unanchored` (warning). Whatever decides the run is finished is
+`validation`.
+
+## risk-marker: what it costs
+
+Declared in `risk_markers`. The security score starts at 4 and each distinct marker
+present anywhere in the blueprint is charged **once**, however many nodes carry it:
+`clamp(round(4 − Σ weights), 1, 4)`. Weights are read from `lib/core/config.ts`; a locally
+namespaced marker with no weight counts 0
+and does not move the score.
+
+Three markers are **inferred** from the graph whether or not any card declares them.
+Declaring one the engine would have inferred anyway changes nothing; failing to declare
+one does not hide it.
+
+| id | weight | how it arrives | broader | meaning |
+| --- | --- | --- | --- | --- |
+| `arbitrary-code-execution` | −2.0 | declared | `execution-risk` | The node can run code or shell commands that were not decided in advance. |
+| `criteria-leak` | −2.0 | inferred | `isolation-breach` | The node can see the acceptance criteria its own output will be judged against. |
+| `execution-risk` | — | category | — | The abstract category for markers about running code the blueprint did not fix in advance. |
+| `irreversible-action` | −1.5 | declared | — | The node takes actions that cannot be undone: publishing, sending, deleting. |
+| `isolation-breach` | — | category | — | The abstract category for markers where information or state crosses a boundary the topology was meant to hold. |
+| `secret-access` | −1.0 | declared | — | The node handles credentials, keys or tokens. |
+| `unbounded-loop` | −1.5 | inferred | — | The node sits in a cycle with no iteration cap and no exit condition. |
+| `unchecked-write` | −1.0 | declared | `isolation-breach` | The node writes to disk, a database or a repository with no check upstream. |
+| `unvalidated-external-access` | −1.0 | inferred | — | The node reaches the network, an API or an external resource with no validation node upstream. |
+
+How the three inferred ones are found:
+
+- `unbounded-loop`: every strongly connected component in the graph, unless some card
+  in it declares an iteration cap. The cap is a **top-level** key of `params`, one of
+  `max_iterations`, `maxIterations`, `max_retries`, holding a non-negative
+  integer (`0` counts). Nested inside another object it is not read, and the cycle takes
+  the charge on every member with no obvious cause.
+- `unvalidated-external-access`: a node whose `tools` include anything subsumed by
+  `web-search`, `http-fetch`, `sql` or `ci`, which has at least one successor, and at
+  least one of those successors is not a `validation` node. `messaging`, `git`,
+  `vector-store`, `file-io`, `shell` and `python-sandbox` are deliberately excluded.
+- `criteria-leak`: see below. This is the one the whole design is built around.
+
+### criteria-leak, precisely
+
+Two sets are computed first. **Producers** are nodes declaring an output port whose type
+is subsumed by `acceptance-criteria`. **Judges** are nodes typed `validation`, and
+**generators** are the predecessors of any judge, closed upward through non-judge nodes.
+The marker fires, at −2.0, when:
+
+- **topological**: walking forward from a producer, absorbing at judges, reaches a
+  generator. The criteria reach the node whose work is being judged.
+- **declarative**: one node emits both an `acceptance-criteria` port *and* another port
+  a directly connected judge reads as the artefact under judgement. One node writing the
+  criteria and the work is structurally illegal, off the declarations alone.
+
+And it warns without charging when:
+
+- **content**: the 3-gram Jaccard similarity between a generator's `spec` and a producer's
+  exceeds 0.35
+  (`analysis/criteria-leak-suspected`). An absent edge with the criteria paraphrased into
+  the prose is a false isolation, and this is the half that catches it. Specs under three
+  words are excluded from the comparison entirely.
+- **relayed**: reachable only by walking *through* a judge
+  (`analysis/criteria-relayed-through-judge`). The engine cannot tell an endorsed
+  `judge → fixer → judge` loop from a forbidden `judge → builder → judge` one, so it
+  declines to decide and says which it saw.
+- **out of band**: a `params` key matching `/criteri/i` naming something nothing in the
+  graph produces (`analysis/criteria-out-of-band`). Isolation has stopped being a property
+  of the topology for that node.
+- **unanchored**: one of the two legs is missing: producers with no generators, or
+  generators with no producers (`analysis/criteria-leak-unanchored`). **The check did not
+  run.** A 4 in this state is silence, not a pass. Both sets empty is silent by design.
+
+## data-type: what an edge carries
+
+Every port declares one, in `type`. Compatibility along an edge is directional: a source
+port fits a target port when the types are equal, when either side is `any`, or when the
+**source is narrower** than the target. Never the other way. `code → text` carries;
+`text → code` is `bundle/type-mismatch` (error).
+
+**Do not reach for `any`.** It matches everything, which means every edge passes, no
+`cannot` prohibition can be violated, and the criteria check has nothing to anchor on. A
+bundle typed `any` throughout loads perfectly and checks nothing.
+
+`acceptance-criteria` is load-bearing: it is the port type the entire `criteria-leak`
+machinery anchors on. Criteria typed `text` or `structured` are criteria the engine
+cannot see.
+
+| id | label | broader | meaning |
+| --- | --- | --- | --- |
+| `acceptance-criteria` | Acceptance criteria | `structured` | The conditions an artefact must satisfy, produced in planning and used to judge the result. |
+| `any` | Any | — | The top of the data lattice, which accepts anything and asserts nothing. |
+| `artifact` | Artifact | `binary` | A build output or file bundle produced by the run. |
+| `binary` | Binary | `any` | Opaque bytes the graph moves without reading. |
+| `code` | Code | `text` | Source code in some language, meant to be run or reviewed rather than read as prose. |
+| `event` | Event | `signal` | A notice that something happened, with a name and a time. |
+| `json` | JSON | `structured` | A JSON value, self-describing and machine-parsable. |
+| `markdown` | Markdown | `text` | Text carrying Markdown structure: headings, lists, emphasis. |
+| `plan` | Plan | `structured` | An ordered set of steps a downstream node is expected to carry out. |
+| `report` | Report | `structured` | A finished write-up of what happened or what was found, meant to be read. |
+| `signal` | Signal | `any` | A lightweight message that carries coordination rather than content. |
+| `status` | Status | `signal` | The outcome of a step, in a form the graph can branch on. |
+| `structured` | Structured | `any` | Data with a shape the receiving node can count on. |
+| `table` | Table | `structured` | Rows over a fixed set of columns. |
+| `text` | Text | `any` | Free-form prose with no structure the next node can rely on. |
+
+The lattice, as `broader` draws it:
+
+```
+any
+  binary
+    artifact
+  signal
+    event
+    status
+  structured
+    acceptance-criteria
+    json
+    plan
+    report
+    table
+  text
+    code
+    markdown
+```
+
+## tool: what a node is permitted to do
+
+Declared in `tools`. Note the deliberate id collision: `tool` is both a `node-type` and
+the *kind* of these terms. The field a term appears in decides which is meant, so there
+is no ambiguity to resolve: `type: tool` is the node type and `tools: [shell]` is a
+capability.
+
+`tools` says what the node is permitted to do. `mcp` says which installed server supplies
+it, is free text, and is checked against nothing, because an MCP server is a process somebody
+installed and the vocabulary has no term for one. A node can carry either without the other.
+
+| id | label | broader | meaning |
+| --- | --- | --- | --- |
+| `ci` | CI | `tool-capability` | Triggers or inspects a continuous-integration pipeline. |
+| `file-io` | File I/O | `tool-capability` | Reads and writes files on the local filesystem. |
+| `git` | Git | `tool-capability` | Reads and writes a Git repository: branches, commits, diffs. |
+| `http-fetch` | HTTP fetch | `tool-capability` | Fetches a URL over HTTP and hands back the response. |
+| `human-review` | Human review | `tool-capability` | Routes the work to a person and waits for their verdict. |
+| `messaging` | Messaging | `tool-capability` | Sends messages to a chat or notification channel. |
+| `python-sandbox` | Python sandbox | `tool-capability` | Executes Python in an isolated interpreter. |
+| `shell` | Shell | `tool-capability` | Runs shell commands on the host. |
+| `sql` | SQL | `tool-capability` | Issues SQL statements against a database. |
+| `tool-capability` | Tool capability | — | The root of the tool vocabulary, a capability a node needs from its host. |
+| `vector-store` | Vector store | `tool-capability` | Embeds, stores and retrieves vectors for semantic recall. |
+| `web-search` | Web search | `tool-capability` | Queries a search engine and returns ranked results. |
+
+## Local terms
+
+`node-type`, `risk-marker`, `data-type` and `tool` accept a locally namespaced term
+(`me/my-term`), which must be rooted in an `extensions.yaml` carried by the bundle.
+`phase` never accepts one.
+
+**Do not emit local terms unless the author asks for one and writes the extension.** An
+unrooted local term is silently ignored, which is the worst outcome available: the card
+loads, the field reads as declared, and nothing enforces it.
+