darkprint 0.1.0

package/skill/darkprint/references/preflight.md

@@ -0,0 +1,206 @@
+# Pre-flight
+
+The checklist you walk your own output against **before** you run the validator, so that
+nothing it prints surprises you. It is not a substitute for running it: `SKILL.md`'s
+"After writing" names the three ways, and you take the first one available.
+
+Work down it in order. Anything marked **error** means the bundle will not load and will
+not publish, and you fix it. Anything marked *warning* the author will see, on the upload
+page or in the validator's output, so **predict it out loud** before they do: an author
+surprised by the upload screen has been failed by the interview.
+
+---
+
+## 1. The DOT parses
+
+- [ ] `digraph`, not `graph`. Every edge `->`, never `--`. `dot/not-directed` **error**
+- [ ] one graph in the file. *`attractor/multiple-graphs`, `dot/unsupported`*
+- [ ] not `strict digraph`. *`attractor/strict-graph`*
+- [ ] `//` or `/* */` comments only. *`attractor/hash-comment`*
+- [ ] attributes comma-separated. *`attractor/attr-separator`*
+- [ ] node ids match `[A-Za-z_][A-Za-z0-9_]*`, unquoted, not a statement keyword.
+      *`attractor/bad-node-id`, `attractor/quoted-node-id`*
+- [ ] no node named `start`, `Start`, `exit` or `end`. **No diagnostic**: the exporter renames
+      such a node and records the original in `dp_node`, so the compiled file stops saying
+      what the topology says. Check by eye
+- [ ] **no `type=` on any node.** *`attractor/reserved-attribute`*, and it is the only reserved
+      node attribute the linter reports
+- [ ] no other reserved Attractor node attribute either (`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`). **No diagnostic**: each is written straight into the
+      compiled file and configures the run silently. Grep for them yourself
+- [ ] no node declared twice with different attributes. *`dot/duplicate-node`*
+- [ ] no self-loops. *`dot/self-loop`*
+
+## 2. Every node finds its card
+
+- [ ] every node carries `card="<id>@<MAJOR.MINOR.PATCH>"`. `bundle/unpinned-card` **error**
+- [ ] every pin names a card file the bundle actually carries. `bundle/missing-card` **error**
+- [ ] every card file is instantiated by some node. *`bundle/orphan-card`*
+- [ ] no two card files declare the same `id@version` with different content.
+      `bundle/digest-mismatch` **error**
+- [ ] a card reused from the registry is byte for byte the file the registry serves for that
+      `id@version`. Same check, same error, on publish
+- [ ] exactly one `.dot`; `blueprint.yaml` at the root is the manifest; no card named
+      `blueprint.yaml` or `extensions.yaml`
+
+## 3. Every card validates
+
+- [ ] YAML parses. `card/parse-error` **error**. The one that bites in practice: a plain
+      scalar containing `": "` is read as a nested mapping. `description: Where it failed: the
+      line and the text` fails with *"nested mappings are not allowed in compact mappings"*.
+      **Quote any value containing a colon-space**, or write it as a `>-` folded block
+- [ ] `id` matches `^(?:ns/)?[a-z0-9]+(-[a-z0-9]+)*$`. `card/bad-id` **error**
+- [ ] `name`, `action`, `spec` present and non-blank; `inputs` and `outputs` **present**, even
+      when empty. `card/missing-field` **error**
+- [ ] `version` is full semver. `card/bad-version` **error**
+- [ ] `type` is one concrete `node-type`, never `human-in-the-loop`, `evaluative` or
+      `orchestration`. `card/unknown-term`, `card/wrong-term-kind` **error**
+- [ ] every node where a person acts carries a `type` subsumed by `human-in-the-loop`, and
+      no node where nobody acts does. `type` is the only field that says it. Writing a
+      `requires_human` key is `card/retired-field`, a **warning**, and it is ignored
+- [ ] every `shell-tool` carries a non-blank `params.tool_command`. Missing is
+      *`card/missing-field`*, blank is *`card/bad-type`*, and either way the node fails on its
+      first execution
+- [ ] every `phase` entry is one of the five, never namespaced, never repeated.
+      `card/unknown-phase`, `card/namespaced-phase` **error**, *`card/duplicate-phase`*
+- [ ] every `tools` entry is a `tool` term; every `risk_markers` entry is a `risk-marker` term
+- [ ] port names unique within their side. `card/duplicate-port` **error**
+- [ ] `required:` only on inputs
+- [ ] every `spec` over 40 characters, and written as an instruction rather than a label.
+      *`card/spec-too-thin`*
+- [ ] the card names no vocabulary version. There is one vocabulary and every card is read
+      against it, so writing an `ontology_version` key is `card/retired-field`, a
+      **warning**, and it is ignored
+- [ ] no key outside the accepted set (`references/card-schema.md`). A typo is an `info` and
+      is **silently ignored**, so check the spelling of `risk_markers` and `will_not` by eye
+
+## 4. Every edge carries something
+
+- [ ] no edge out of a node whose `outputs` is `[]`, and no edge into a node whose `inputs` is
+      `[]`. `bundle/port-mismatch` **error**, *"carries no data"*
+- [ ] every `out=` / `in=` pin names a port the card actually declares.
+      `bundle/port-mismatch` **error**
+- [ ] every edge has at least one compatible pair. Source narrower than target, or equal, or
+      either side `any`. `bundle/type-mismatch` **error**
+- [ ] every edge where more than one pair would fit is **pinned**. *`bundle/port-ambiguous`*,
+      and an unpinned ambiguous edge means the prohibition check is reasoning about the
+      resolver's declaration-order guess rather than about your intent
+
+## 5. Every fork is guarded
+
+- [ ] every node with two or more outgoing edges has a `condition` on every arm, or a
+      `weight` the author chose on purpose. **No diagnostic**: an unguarded fork is legal
+      and the runner decides it by the spelling of the target ids, so a loop whose fix arm
+      sorts before its ship arm never ships. Read `references/dot-and-attractor.md`, Part 2
+- [ ] every `condition` uses only the keys `outcome`, `preferred_label` or `context.<path>`,
+      the operators `=` and `!=`, and `&&` between clauses. *`attractor/condition-syntax`*
+      here, and an error to the runner, which refuses the whole pipeline over it
+- [ ] no `condition=""`. It is no condition at all, and the edge falls back to the order
+      above without anything saying so
+- [ ] the check's success arm is `outcome=success` and its other arm is `outcome!=success`,
+      so a verdict that is neither lands on the arm that does not ship
+
+## 6. The prohibitions
+
+- [ ] every `cannot` entry names a `data-type` term id. A sentence here is
+      `card/unknown-term` **error** and the card does not load
+- [ ] every `will_not` entry is a sentence. A `data-type` here is
+      *`card/prohibition-misfiled`*, and it means a rule the resolver could have enforced
+      is sitting where nothing reads it
+- [ ] no edge carries into a node a type its `cannot` refuses. `bundle/prohibition-violated`
+      **error**. Two directions to keep straight:
+      - **subsumption**: `cannot: [structured]` refuses an incoming `acceptance-criteria`;
+        `cannot: [acceptance-criteria]` does **not** refuse an incoming `structured`;
+      - **the carrier**: with no `out=` pin, the carriers are *every output of the source
+        card*, so the edge is refused if any of them is prohibited. With an `out=` pin, only
+        that one port counts, so a pinned edge can slip past a prohibition the unpinned one
+        would have tripped. It still gets charged by the analyzer, which reads the graph at
+        node level; `cannot` is the tripwire, not the whole guard
+- [ ] no output typed `any` upstream of a node with a narrower prohibition. `any` never
+      violates anything and the whole mechanism goes inert
+
+## 7. Dependencies
+
+- [ ] every `dependencies` entry has a matching incoming edge. `bundle/missing-dependency`
+      **error**
+- [ ] every incoming edge is listed in the target card's `dependencies`.
+      *`bundle/undeclared-dependency`*
+- [ ] entries name the supplier's **card id** or its **DOT node id**; either satisfies the check
+
+## 8. Structure
+
+- [ ] at least one node with no incoming edge. *`bundle/no-entry`*
+- [ ] at least one node with no outgoing edge, and it declares `outputs: []`. *`bundle/no-exit`*
+- [ ] every node reachable from a source. *`bundle/unreachable-node`*
+- [ ] the graph is not empty. *`analysis/empty-graph`*
+
+## 9. The checks that decide the security level
+
+- [ ] **at least one node typed `validation`.** Without it the generator set is empty and the
+      criteria check does not run. *`analysis/criteria-leak-unanchored`* when a producer
+      exists, silence when neither leg does, and a 4 is silence either way
+- [ ] **at least one output port typed `acceptance-criteria`.** Without it the producer set is
+      empty, same outcome
+- [ ] **no edge from the criteria producer into any node whose work is judged, whatever port
+      that edge carries.** The topological walk reads the graph at node level. A brief that
+      needs to reach the builder arrives with the run, not over an edge
+- [ ] the criteria producer does not also emit the artefact the judge reads. One node writing
+      both is charged off the declarations alone
+- [ ] every generator's `spec` shares under 0.35 3-gram Jaccard with the producer's, names no
+      criterion and quotes no threshold. *`analysis/criteria-leak-suspected`*
+- [ ] no `params` key matching `/criteri/i` naming something nothing in the graph produces.
+      *`analysis/criteria-out-of-band`*
+- [ ] every cycle has `max_retries` as a **top-level** key of `params` on one member, holding
+      a non-negative integer that counts the attempts **after** the first. `max_iterations`
+      and `maxIterations` are accepted aliases for the same number. Nested, it is not read,
+      and the cycle takes `unbounded-loop` on every member
+- [ ] every node with `web-search`, `http-fetch`, `sql` or `ci` in `tools` either has no
+      successors or hands to `validation` nodes only. Otherwise
+      `unvalidated-external-access` is inferred, −1.0, whether or not it is declared
+- [ ] you have **not** inserted a validation node purely to silence a marker
+
+## 10. The manifest
+
+- [ ] `blueprint.yaml` carries `slug`, `title`, `summary`, `description`, `category` and
+      `tags`, and `slug` is the folder name and the name the author creates at `/new`
+- [ ] `summary` is one sentence, because it becomes the compiled pipeline's `goal`
+
+## 11. Predict the validator
+
+Write out, for the author, the warnings you expect and why each is intended. The common
+honest ones:
+
+| warning | when it is fine |
+|---|---|
+| `analysis/criteria-relayed-through-judge` | the fixer sits downstream of the judge that holds the criteria. The engine cannot tell `judge → fixer → judge` from `judge → builder → judge` and declines to decide. Charges nothing |
+| `bundle/undeclared-dependency` | never fine. Fix it |
+| `bundle/no-entry` / `bundle/no-exit` | never fine in a first emit. A blueprint with no source and no sink is a loop with no way in |
+| `bundle/port-ambiguous` | never fine. Pin the edge |
+| `attractor/condition-syntax` | never fine. The runner refuses the whole pipeline over it |
+
+And name the two figures the author will read. The autonomy class is read twice off `type`
+and the weaker reading is the one that lands in a band: the share of all nodes not subsumed
+by `human-in-the-loop`, and the same share taken over the **control points** only (the nodes
+under `evaluative` or `orchestration`, plus `human-gate`), which decides a band only from two
+control points up. A graph with one `human-gate` among its two control points reads 0.5 on
+the second axis and lands a band lower than the first axis alone would say. The bands are in
+`references/ontology.md`. The security level is 4 minus the sum of the distinct markers,
+each charged once.
+
+## 12. Re-emitting
+
+If this is a second pass over a bundle that already exists:
+
+- [ ] a card whose content changed has a **new version**, and the old file is **deleted**, not
+      left beside it. `bundle/digest-mismatch` **error**, *`bundle/orphan-card`*
+- [ ] the bump is large enough. `card/version-bump-too-small` **error**. The full table is in
+      `references/card-schema.md`; the rows that bite in a second pass are these. **Major**:
+      a port removed, renamed or retyped, an input made required or a required input added,
+      `type` or `id` changed, a `cannot` entry added, a `will_not` entry withdrawn. **Minor**:
+      `spec`, `model` or `skill` changed, an optional port added, a tool, MCP server, param
+      key, risk marker or dependency added, a phase added or dropped, a `cannot` withdrawn, a
+      `will_not` stated. **Patch**: wording, a param's value, a reorder, anything withdrawn
+      from `tools`, `mcp`, `risk_markers`, `dependencies` or `params`
+- [ ] every DOT pin updated to the new version

package/skill/darkprint/references/writing-cards.md

@@ -0,0 +1,178 @@
+# Writing the prose
+
+The author decides the shape. You write the words. Four card fields carry prose (`action`,
+`spec`, port `description`, `notes`), and two files beside the cards do (`blueprint.yaml`,
+`README.md`).
+
+---
+
+## `action`
+
+One sentence, imperative, naming the operation and the artefact. It is the line a reader
+scans; it is not the instruction the agent receives.
+
+> Turn the incoming request into two separate artefacts: an ordered brief, and the acceptance
+> criteria the finished work will be judged against.
+
+If it contains an "and" naming two different artefacts *and* the node emits both, check
+against the criteria rule below before you keep it.
+
+---
+
+## `spec`, the one that matters
+
+**`spec` is compiled into the node's `prompt`.** It is delivered verbatim to an agent that
+does not see the rest of the graph, so it has to be self-sufficient, and it has to respect
+the isolation the topology declares, because an absent edge with the criteria paraphrased into
+the prose is a false isolation. The engine measures that; it does not take your word for it.
+
+Aim for **150 to 400 words**. Under 40 characters is `card/spec-too-thin`. Under three words is
+excluded from the similarity comparison entirely, so a placeholder card is both useless and
+unchecked.
+
+Write it as:
+
+1. **What arrives.** Name the input ports and say what is in them.
+2. **What to do**, in the order it is done.
+3. **What to emit, on which port**, and in what form.
+4. **What not to do**: the boundaries from Q0.5 and Q4.3, in the second person, the same
+   sentences that went into `will_not`.
+
+For a `shell-tool`, the `spec` still says what arrives and what is emitted; the command in
+`params.tool_command` is what runs. For a node inside a cycle, the `spec` states the total
+number of attempts in words, and `params.max_retries` holds that total minus one.
+
+### The rule you cannot break
+
+A node whose work is judged must not paraphrase the criteria producer's `spec`. The engine
+computes 3-gram Jaccard similarity between the two and warns above **0.35**
+(`analysis/criteria-leak-suspected`).
+
+Concretely, in a generator's `spec`:
+
+- name no criterion,
+- quote no threshold,
+- do not restate the planner's sentences in your own words,
+- do not describe how the work will be checked.
+
+The starter blueprint's builder spec measures **0.0356** against its planner's. That is what
+independent prose looks like. If you find yourself writing "make sure it passes the checks",
+you have just written the leak into the file.
+
+The reason, stated to the author when they push back: whoever writes the work must not see the
+acceptance tests, because a node that sees them writes toward them, and the check stops
+measuring the work and starts measuring the aim.
+
+### Do not write one house style and vary it per node
+
+Six specs sharing a third of their trigrams cross the threshold against each other. Write each
+one about its own job, in its own words.
+
+---
+
+## Port `description`
+
+One line. What is in it, and who it came from, not what the receiving node should do with it.
+
+> The ordered build steps the run was instantiated with, the only thing this node sees.
+
+A one-line description is where the YAML trap lands, because a colon is the natural way to
+write one. A plain scalar containing `": "` is parsed as a nested mapping and the whole card
+fails with `card/parse-error`. Quote it, or fold it:
+
+```yaml
+description: Where it failed: the line and the text     # BREAKS the card
+description: "Where it failed: the line and the text"   # fine
+```
+
+---
+
+## `notes`
+
+Optional, and absence carries no judgement. Use it for the thing a reader would otherwise
+misread as an oversight: the edge you did not draw, the marker you deliberately did not
+declare and why, the cap that is load-bearing twice over.
+
+This is the right place to record a judgement call that could have gone the other way, with
+what it would cost if it did:
+
+> No `irreversible-action`, deliberately: this node writes one tagged artefact to the run's own
+> release target, sends nothing to a third party and deletes nothing. If a reviewer decides a
+> release target counts as publication, the marker costs this blueprint 1.5 and takes its
+> security level from 4 to 3.
+
+---
+
+## `blueprint.yaml`
+
+The manifest, derived from the interview (SKILL.md, Q5.3) and shown back before it is
+written:
+
+```yaml
+slug: help-centre-line
+title: Help Centre Article Line
+summary: >-
+  Outline, draft and check help-centre articles against acceptance criteria the drafter
+  never sees, with one human approval before anything publishes.
+description: |-
+  One paragraph per node in the order a run visits them, in the author's words from Q2.1,
+  ending with the edge that is deliberately absent and why.
+category: Content
+tags:
+  - help-centre
+  - editorial
+  - isolation
+  - human-gate
+```
+
+`summary` is one sentence, because it becomes the compiled pipeline's `goal`: the one line a
+runner reads about the whole graph. `slug` is the folder name, the name the author creates
+at `/new`, and the graph name in card-id grammar. Nothing else goes in the file; the
+registry fills in the author and the dates when it publishes.
+
+---
+
+## `README.md`
+
+For a person opening the folder. Written from the answers, not from a template with the
+blanks filled, and in the shape the registry writes for every published bundle, so a folder
+that came from this skill and a folder downloaded from the site read the same way:
+
+1. **What the blueprint does**, in the author's own sentence from Q0.1, and the blueprint it
+   started from if Phase 1 found one.
+2. **The node table**: DOT id, card `id@version`, type, phase, one line each.
+3. **The edges, including the ones deliberately absent**, with a line per absence saying why,
+   and the guard on every fork. This is the section that earns the file.
+4. **What is in the folder**: `topology.dot`, `cards/`, `blueprint.yaml`, and
+   `ontology/extensions.yaml` when there is one.
+5. **What the validator said**: which validator ran (`darkprint validate`, the
+   `/api/validate/bundle` route, or the upload page), the autonomy class and the security
+   level it computed, and each warning with the reason it is intended. Never claim the bundle
+   validated cleanly without naming which of the three said so.
+6. **What these files leave to the runner**: that ports, `cannot`, `will_not` and
+   `risk_markers` are enforced when the bundle is validated and by nothing in the compiled
+   pipeline, and that every Attractor attribute a card has no field for (goal gates, timeouts,
+   the retry policy above `max_retries`) falls to the runner's own default.
+7. **How to check it again**: drop the folder on `https://www.darkprint.io/upload`.
+
+---
+
+## Re-emitting an existing bundle
+
+A published card version is never edited in place.
+
+- Content changed ⇒ new version, old file **deleted**, DOT pin updated.
+- The bump has to be at least what the engine infers. Under-bumping is
+  `card/version-bump-too-small`, an error. The full table is in `references/card-schema.md`.
+  The rows that catch people: a port removed, renamed or retyped, a required input added, a
+  `cannot` entry added or a `will_not` entry withdrawn are all **major**; `spec`, `model` and
+  a new tool, param key, risk marker or dependency are **minor**; a param's *value*, wording
+  and reorders are **patch**.
+- Leaving the superseded file in `cards/` is `bundle/orphan-card` at best and
+  `bundle/digest-mismatch` at worst.
+- A card reused from the registry is never re-emitted by you at all. If it needs to change,
+  it is a new card with a new id, or the author publishes the change under their own name
+  and the DOT pins that.
+- When a card's identity is a parameter (the starter encodes its debugger's attempt count in
+  the minor version) keep that convention. Two caps behind one pin would be two contents
+  behind one reference.

package/skill/darkprint/templates/card.yaml

@@ -0,0 +1,84 @@
+# cards/<card-id>@<version>.yaml
+#
+# The wire format is snake_case. Every key the validator accepts is listed in
+# references/card-schema.md; anything outside that set is silently ignored, so a typo in
+# `risk_markers` does nothing rather than failing loudly.
+#
+# This is the skeleton for a node instructed by prose (`agent`, `tool`, `validation`,
+# `decision`, `human-gate`, `human-input`). A node that IS a command is `shell-tool` and
+# has its own skeleton in `shell-tool-card.yaml`, because it owes `params.tool_command`.
+#
+# NEVER name a card file `blueprint.yaml` or `extensions.yaml`. Those names are claimed by
+# the manifest and the local vocabulary, and a card called either disappears from the bundle.
+#
+# YAML trap, hit every time: a plain scalar containing ": " is parsed as a nested mapping and
+# the whole card fails with card/parse-error. Quote it, or use a `>-` folded block.
+#   description: Where it failed: the line and the text     <- BREAKS the card
+#   description: "Where it failed: the line and the text"   <- fine
+
+# ---- identity ----
+id: card-id                 # ^(?:namespace/)?[a-z0-9]+(-[a-z0-9]+)*$ lowercase, hyphens, no underscores
+name: Human Readable Name
+type: agent                 # exactly one node-type term. Never an abstract category.
+phase: implementation       # optional and repeatable; omit it entirely when the node sits in none of the five
+
+# ---- behaviour ----
+action: >-
+  One imperative sentence naming the operation and the artefact.
+spec: >-
+  150-400 words. This is compiled into the node's `prompt` and handed verbatim to an agent
+  that does not see the rest of the graph, so it must be self-sufficient: what arrives, what
+  to do in order, what to emit on which port and in what form, and what not to do. If this
+  node's work is judged, it must name no criterion, quote no threshold and paraphrase nothing
+  the criteria producer wrote. The engine measures the overlap and warns above 0.35.
+model: claude-sonnet-5      # optional. A default the runner can override, not a binding.
+agent: Role Name            # optional
+tools: []                   # tool terms. web-search / http-fetch / sql / ci infer a risk marker.
+mcp: []                     # installed server names. Free text, checked against nothing.
+skill: skills/card-id.md    # optional pointer; nothing in the engine reads what it points at
+params:
+  # The iteration cap, when this node sits in a cycle. TOP LEVEL only: nested it is not read,
+  # and the whole cycle takes -1.5 with no obvious cause. It counts the attempts AFTER the
+  # first, so 2 means three runs in all. Say the total in `spec` and make the two agree.
+  # `max_iterations` and `maxIterations` are accepted aliases and mean the same number.
+  max_retries: 2
+
+# ---- interfaces ----
+inputs:                     # must be PRESENT. Write [] when the node needs nothing.
+  - name: brief
+    type: plan              # a data-type term. Do not reach for `any`.
+    description: What is in it and who it came from.
+outputs:                    # must be PRESENT. [] is how a sink is declared.
+  - name: build
+    type: code
+    description: What is handed over.
+dependencies:               # the card ids or DOT node ids of the suppliers, derived from the edges
+  - upstream-card-id
+cannot:                     # data-type term ids ONLY. Anything else is card/unknown-term.
+  # ENFORCED: the resolver refuses any incoming edge whose carrier is that type or anything
+  # narrower, with bundle/prohibition-violated. On an unpinned edge the carriers are EVERY
+  # output of the source card; with `out=` only that port.
+  - acceptance-criteria
+will_not:                   # your own sentences. Nothing checks them, and nothing can.
+  # Addressed to whoever reads the card and to the agent instantiated from it. Putting a
+  # data-type here is card/prohibition-misfiled, a warning: the card loads and no edge is
+  # ever checked against the rule you meant to state.
+  - read the checks the work will be run against
+
+# ---- evaluation metadata ----
+# Whether a person acts here is not a field. It is `type`: human-gate and human-input are
+# subsumed by human-in-the-loop and every other type is not. Writing `requires_human` here
+# is card/retired-field, a warning, and the key is ignored.
+risk_markers: []            # risk-marker terms. unbounded-loop, unvalidated-external-access and
+                            # criteria-leak are inferred from the graph whether declared or not.
+notes: >-
+  Optional. The place to record the thing a reader would otherwise misread as an oversight:
+  the edge that is deliberately absent, the marker deliberately not declared and what it would
+  cost if the judgement went the other way.
+
+# ---- service fields ----
+version: 1.0.0              # full semver. A published version is never edited in place.
+author: your-handle         # optional
+# No ontology_version. There is one vocabulary and every card is read against it. The
+# vocabulary carries no version of its own. Writing the key is card/retired-field, a
+# warning.

package/skill/darkprint/templates/shell-tool-card.yaml

@@ -0,0 +1,52 @@
+# cards/<card-id>@<version>.yaml, for a node that IS a command.
+#
+# `type: shell-tool` is a kind of `tool`, so every rule about tool nodes still holds, and it
+# compiles to the Attractor handler that runs `params.tool_command` and fails the node before
+# doing anything else when the command is missing or blank. A missing command is
+# card/missing-field and a blank one is card/bad-type, both warnings, both meaning the node
+# resolves and then fails on its first execution. A node instructed by prose alone is
+# `type: tool`, and takes the skeleton in `card.yaml`.
+#
+# The same YAML trap as every card: quote any value containing ": ".
+
+# ---- identity ----
+id: test-runner
+name: Test Runner
+type: shell-tool
+phase: testing
+
+# ---- behaviour ----
+action: >-
+  Run the project's test suite against the build and emit the runner's own report.
+spec: >-
+  The build arrives on the `build` port as a checked-out tree. Run the command below from
+  its root and capture everything it prints. Emit the whole output on the `report` port,
+  exit status first, with nothing summarised and nothing removed. Do not modify the tree,
+  do not install anything, and do not retry a command that failed.
+tools: [shell]              # the permission the command needs, as a tool term
+params:
+  # The exact line the runner executes. Fixed in advance, so it is not arbitrary code
+  # execution: declare that marker only when the command runs something decided at run
+  # time, such as a script the previous node wrote.
+  tool_command: npm test
+
+# ---- interfaces ----
+inputs:
+  - name: build
+    type: code
+    description: The tree to test, as the builder handed it over.
+outputs:
+  - name: report
+    type: report
+    description: The runner's own output, exit status included.
+dependencies:
+  - code-builder
+cannot: []
+will_not:
+  - modify the tree under test
+
+# ---- evaluation metadata ----
+risk_markers: []
+
+# ---- service fields ----
+version: 1.0.0

package/skill/darkprint/templates/topology.dot

@@ -0,0 +1,66 @@
+// A skeleton, not a form to fill in blindly. Every line here is a decision the interview
+// has already made. Delete what does not apply.
+//
+// Comments are `//` or `/* */`. A `#` comment trips `attractor/hash-comment`.
+// Attributes are COMMA-separated. Node ids match [A-Za-z_][A-Za-z0-9_]* and are never quoted.
+// NEVER write `type=` on a node: that is Attractor's handler override, not DarkPrint's
+// ontology type, which lives in the card.
+
+digraph blueprint_name {
+  rankdir=LR;
+  node [shape=box, style=rounded];
+
+  /* ---- nodes: the id is the instance, the card is the definition ----
+     Always pin `card="<id>@<MAJOR.MINOR.PATCH>"`. The bare `version=` fallback makes the node
+     id double as the card id, which only works for a single lowercase word. */
+
+  plan_step   [card="plan-step@1.0.0"];
+  build_step  [card="build-step@1.0.0"];
+  check_step  [card="check-step@1.0.0"];
+  fix_step    [card="fix-step@1.0.0"];
+  ship_step   [card="ship-step@1.0.0"];
+
+  /* ---- edges: pin the ports whenever more than one pair would fit ----
+     `out=` names a port on the source card, `in=` a port on the target card. Neither is
+     reserved by Attractor, so both ride along harmlessly in the compiled pipeline. */
+
+  plan_step  -> check_step [label="acceptance criteria", out="criteria", in="criteria"];
+  build_step -> check_step [label="build",               out="build",    in="build"];
+
+  /* ---- THE FORK, and the guard on each arm ----
+     `check_step` has two exits. A runner picks one in a fixed order: a `condition` that
+     holds beats every unguarded edge; then an edge whose `label` matches the label the node
+     asked for; then a next id the node suggested; then the higher `weight`; and on a tie,
+     the target id that sorts first. Two bare edges out of one node are therefore a branch
+     decided by the spelling of the node names. `fix_step` sorts before `ship_step`, so an
+     unguarded version of this loop repairs until the cap is spent and never ships.
+
+     `outcome` is set by the runner from the node's own status on every pass. One key against
+     its own negation is the only total split the guard grammar can make: it has `=` and
+     `!=`, clauses joined by `&&`, and nothing else. */
+  check_step -> fix_step   [label="failure evidence", style=dashed, condition="outcome!=success", out="evidence", in="evidence"];
+  check_step -> ship_step  [label="approved", condition="outcome=success", out="approved", in="release"];
+
+  // The loop returns to the CHECK, never to the builder: the work already done is preserved
+  // and the builder stays isolated from every fact about the failures for the whole run.
+  // The cap is a TOP-LEVEL `params.max_retries` on one member, counting the attempts after
+  // the first: `max_retries: 2` is three runs in all.
+  fix_step   -> check_step [label="patch", out="patch", in="build"];
+
+  /* ---- THE EDGE THAT IS NOT HERE ----
+     Nothing runs from `plan_step` to `build_step`. The criteria reach the node that JUDGES the
+     work and never the node that PRODUCES it.
+
+     The topological half of the `criteria-leak` check reads the graph at NODE level: any edge
+     at all from the criteria producer into a judged node establishes the marker, whichever
+     port that edge carries. So the build brief is handed to `build_step` when the graph is
+     instantiated, as a source node with an input port and no incoming edge, rather than
+     over an edge from the planner.
+
+     The other end of the same rule is written in the card: `build-step` lists
+     `acceptance-criteria` under `cannot`, so drawing that edge unpinned fails the bundle with
+     `bundle/prohibition-violated` rather than loading quietly and scoring 2. Pinning it to
+     `out="brief"` would satisfy the prohibition, because the carrier is then that one port,
+     and the analyzer would still charge criteria-leak, because its walk reads the graph at
+     node level. Two guards, and they answer different questions. */
+}