augure 0.1.0

data/home/runner/work/augure/augure/docs/auditability.md

@@ -0,0 +1,160 @@
+# Auditability: what it means, and what it costs each team
+
+*Explanation. This page is the "why" behind the `explain` payload.*
+
+## The tools (the narrative runs)
+
+The pattern has a name now. Kambhampati et al. call it the
+LLM-Modulo framework ("LLMs Can't Plan, But Can Help Planning", ICML
+2024): the LLM proposes, external model-based verifiers dispose.
+Wang et al.'s CHECKMATE (arXiv 2512.11143, 2025) measured it: Claude
+Code + an external classical planner improves penetration success by
+over 20%. augure-lictor IS that shape, with the receipts: the
+verifier is Datalog + a frozen corpus, not prose.
+
+> The narrative below is now a TOOL: `augure coverage --flip
+> canary:true` replays the corpus under a hardening override and
+> prints what died (the blue scorecard); `augure rules --mitre
+> --json` exports the ATT&CK Navigator layer; the packs' `detection:`
+> sections give lictor's `report --defender` its per-technique
+> observables. The prose describes the design; the commands run it.
+
+## What auditability means here
+
+Every decision Augure produces is a set of readable proofs, not a score:
+
+```json
+{
+  "schema": "augure/decision@1",
+  "selected": "ret2plt",
+  "explain": {
+    "provenance": {
+      "ret2plt": [{
+        "rule": "app_ret2plt",
+        "origin": null,
+        "evidence": [["vuln", "sof"], ["nx", "true"], ["pie", "false"], ["plt", "system"]]
+      }]
+    }
+  }
+}
+```
+
+When sibling rules share a head (the documented way to express OR),
+EVERY firing appears - each attributed to its own rule id and origin.
+
+Three properties fall out of that shape:
+
+1. **Traceability.** Every technique claim points to a rule ID and the exact
+   facts that satisfied it. Nothing is a vibe.
+2. **Reproducibility.** The bandit's draw is seeded. Same facts, same seed,
+   same decision - re-runnable years later, in front of a client, in front
+   of an auditor.
+3. **Disprovability.** A wrong rule is a *findable* wrong rule. When Augure
+   disagrees with your intuition, you can locate the disagreement precisely:
+   which fact was missing, which condition is too narrow. That disagreement
+   is a bug report or a research result - never a shrug.
+
+The original system's motto still applies: *one is a clock, the other is a
+cat*. An LLM agent improvises; a clock ticks the same way every time. You
+can open a clock.
+
+## For red team: the defensible choice
+
+An engagement report that says *"we chose ret2plt because the model said
+so"* does not survive client scrutiny. One that says *"ret2plt was selected
+by rule `app_ret2plt` because the binary imports `system@plt`, PIE is off,
+and the pop-rdi gadget is present; the chain passed the payload-fit check"* -
+does.
+
+Concretely, red teams get:
+
+- **Methodology you can defend.** The explain block drops into the report as
+  evidence, per target.
+- **After-action replay.** Same facts + same seed = same decision. Re-run
+  last quarter's engagement against the current rules and see exactly what
+  the rule updates changed.
+- **Benchmarked intuition.** The prior table encodes measured weight
+  inversions: human operators overweighted shellcode and `ret2libc` and
+  underweighted `ret2plt`. Your team can measure its own priors the same
+  way - and the disagreement with Augure's corpus is itself signal.
+
+The honest boundary: the priors are **authored, not measured on your
+targets**. Treat Augure's recommendation as a falsifiable hypothesis that
+happens to carry its own proof trail - not as an oracle.
+
+## For blue team: the model read backwards
+
+The same fact/rule table, read in reverse, is a hardening map:
+
+- **Coverage mapping.** "Which techniques does our estate make
+  *impossible*?" A rule fires only if its facts hold. `app_shellcode`
+  requires NX off - flip the fact, the rule dies. Enumerate which
+  protections kill which rules, per asset class.
+- **Hardening prioritization.** Each control eliminates a set of rules. The
+  control that kills the most rules on your asset mix is your best next
+  spend - computable, because the model is explicit.
+- **Anti-reflex prediction.** The corpus's discriminating cases
+  (`stack6`/`stack7`-style: filtered return addresses) show what an
+  *adaptive* attacker does when the obvious technique dies: it plans the
+  boring alternative. Blue teams can run the same planner on their own
+  fact base to see the second-order moves.
+- **Reconnaissance signatures.** Every fact a rule needs is something an
+  attacker must *learn* first: `plt("system")`, `gadget("pop_rdi_ret")`,
+  `glibc_minor`. The fact list is a detection surface: what your monitoring
+  should catch someone enumerating.
+
+## For purple team: the shared artifact
+
+Red and blue arguing about "likely attack paths" argue from different
+imaginations. Both teams arguing about a *rule table* argue from the same
+object:
+
+```mermaid
+graph LR
+    RB["blue adds a control"] --> C["fact set changes<br/>(NX on, RELRO full...)"]
+    C --> R["corpus re-run:<br/>rules stop firing"]
+    R --> P["planner predicts<br/>the next move"]
+    P --> D["blue validates<br/>detection for THAT move"]
+    D --> RB
+```
+
+- **One vocabulary.** A technique rule is written once; red side proves it
+  fires, blue side proves it hurts, purple side keeps both proofs in one
+  repo.
+- **The corpus is double-sided.** The 33 frozen CTF targets are offensive
+  regression tests *and* detection validation targets: when blue adds a
+  control, re-run the corpus, and the rules that fell are the measured
+  progress.
+- **The loop.** Blue adds a control → fact set changes → rules stop firing →
+  planner predicts the next move → blue validates detection for *that*
+  move. That is a purple-team program with numbers on it.
+
+## For compliance and assurance
+
+- **Reproducible evidence.** Decision + seed + rules version = a run you
+  can re-execute during an audit. Penetration-test reports can cite the
+  engine output the way they cite a tool version.
+- **Predictions vs field results.** The benchmark numbers are model
+  predictions against frozen corpora. The distinction is in the README and
+  it stays there: an auditor cares that you know the difference.
+- **Full trail (Lictor).** When the companion orchestrator executes a
+  decision, the persisted chain is decision → rule → module → outcome.
+  Every operational action traces back to a proof.
+
+## What auditability does NOT cover
+
+Say it plainly:
+
+1. **Completeness of rules.** What is not encoded is not audited. A
+   technique absent from the table is invisible to the decision layer -
+   auditability guarantees you can inspect what was considered, not that
+   everything was.
+2. **Prior accuracy.** The Beta priors are authored constants calibrated
+   from a corpus of write-ups. They are a starting point to be fed back,
+   not a measurement of your targets.
+3. **The execution side.** Augure decides; Lictor executes. An audit of the
+   decision layer says nothing about what the executor did beyond what its
+   own trail records.
+
+Auditability is a property of the *decision*, and that is exactly as far as
+it reaches. Everything else still requires a human who reads.

data/home/runner/work/augure/augure/docs/build-format.md

@@ -0,0 +1,119 @@
+# The build format: from a decision to bytes
+
+augure decides; the pack says how the decision becomes a payload.
+This page documents the BUILD format: the slots vocabulary, how a
+technique becomes buildable, and where every number comes from.
+
+## The lineage (all published)
+
+The build layer descends from a line of published work:
+
+- **metasm** - Y. Guillot, *"Metasm: un framework de manipulation de
+  code en Ruby"*, SSTIC 2007 (also hack.lu 2007).
+- **Déprotection semi-automatique de binaire** - Guillot & Gazet,
+  SSTIC 2008: static unpacking driven by metasm's disassembler.
+- **Exploitation automatique avec metasm** - esec-lab (Sogeti),
+  June 2010: the automatic-exploitation loop this project re-derives,
+  auditable this time.
+- **miasm** - C. Desclaux, SSTIC 2012: metasm's Python successor. The
+  strategy-sim prototype carries a miasm backend in its profiler - the
+  docstring says "Python equivalent of Metasm", literally.
+- **Ghost writing** - screwnomore, 2015: shellcode as preprocessor
+  templates that mutate per build. Our shellcode stubs are assembly
+  SOURCE with equivalent variants picked by a seeded rng.
+
+## Where the numbers come from
+
+| Number | Source | Provenance in the trail |
+|---|---|---|
+| the offset | the frame read statically (`lea reg, [rbp-N]` before the unsafe call) or the cyclic pattern crashed under the debugger | `offset_source: static-frame` / `gdb-cyclic` |
+| the return address | the facts: `win_symbol("win", addr)` or a gadget address | `ret_source: win_symbol:win@0x...` |
+| the gadget | the profiler's byte patterns, then RE-DECODED at the claimed address (a lying gadget is refused) | the gadget fact's address |
+| the shellcode | assembly SOURCE in `augure-profiler/shellcode.rb`, assembled by metasm | the stub name |
+
+Nothing is guessed. A number the facts cannot supply is a loud
+`BuildError`, never a magic constant.
+
+## The slots vocabulary
+
+A build layout is an ordered list of slots (data, in
+`lictor/lib/config/build_layouts.yml` or a pack's `build:` section):
+
+| Slot | Arguments | Emits |
+|---|---|---|
+| `padding` | `measured_offset`, optional `sled` | the measured offset of `A` (or `\x90`) |
+| `qword` | `win` or `gadget:TYPE` | the fact's address, 8 bytes |
+| `dword` | same | 4 bytes (x86), whatever the arch |
+| `shellcode` | `sh`, `bash`, `orw` (+ the flag path as the third element), or `file` with `--payload-file` | the assembled stub |
+| `chain` | one or more refs | one arch-width word per ref, in order |
+
+The `chain` refs resolve against the facts, loud `BuildError` on any
+missing piece: `gadget:TYPE`, `plt_addr:NAME`, `got_addr:NAME` (the
+profiler's address facts), `win`, `leak:NAME` (a
+`leaked_address(name)` fact - the harvest, the run's leak capture),
+`const:N` (a literal - a syscall number, an offset). The built-in
+layouts cover `ret2plt` (the puts@got leak chain) and `ret2libc`
+(post-leak: ret-align + pop_rdi + binsh + system); the `orw` layout
+strikes through the leaked buffer address. The `ret2csu_v2` pack
+teaches its own chain (the canonical csu leak) in `build:` - packs
+teach, the builder follows.
+
+Under `seccomp("true")` the `sh` stub is a booby trap (execve dies):
+the builder switches the stub to the orw chain (open/read/write,
+clean exit) with the flag path embedded.
+
+The armor validates a pack's `build:` section: the technique must be
+the pack's own, the layout must be a slot list from the vocabulary
+(padding, qword, dword, shellcode, chain), the refs must name
+existing predicates. A refused layout never reaches the builder.
+
+## What metasm does here
+
+1. **The frame read** (`StaticOffset`): decode the ELF, resolve the
+   unsafe imports' PLT stubs (`.rela.plt` order; both the classic
+   `.plt` and the CFI `.plt.sec` layouts), disassemble `.text` from
+   every function symbol, net the `e8 rel32` call to an unsafe sink,
+   read the buffer's `rbp` displacement: offset = saved rbp + return
+   slot - displacement. Validated against the canonical numbers
+   (ROP Emporium ret2win x64 = 40, split = 40).
+2. **The shellcode**: `Metasm::Shellcode.assemble` on committed
+   assembly text; the call-back layout keeps every stub
+   position-independent; the live-execution test in the suite runs our
+   own assembled bytes.
+3. **The gadget verification**: the bytes at a claimed gadget address
+   are re-decoded and must match the advertised semantics.
+4. **The crash identification**: the static side names the vulnerable
+   function and its sink; the control evidence is the known pattern
+   found in the registers - exact, not inferred from 0x41414141 shapes.
+5. **The general gadget hunt**: every offset of the executable
+   sections, a decoded chain ending on ret, classified semantically -
+   the multi-instruction gadgets (pop rsi; pop r15; ret) the byte
+   patterns never see.
+6. **The dynamic layer**: the write-site proof (a watchpoint on the
+   return slot catches the instruction that plants the overflow - the
+   taint proven, not inferred), the runtime map (libc, stack of a live
+   run), and lictor's harvest (the service's banner becomes
+   leaked_address facts).
+7. **The encoders**: the keyed self-decoder with the backward-call
+   get-pc (a negative rel32 carries ff bytes, never 00), the payload
+   nop-padded under 128 bytes, the keys per seed. The shikata
+   inheritance, auditable: the seed reproduces the exact bytes. A
+   payload wider than 120 bytes on a 0x00 channel is refused honestly.
+
+No emulation: the suite's live-execution tests are the truth.
+
+## Teaching a buildable technique
+
+Write the pack (rules, kb, mcts, priors per the pack format), add its
+`build:` section with the layout, run the armor:
+
+```sh
+lictor rule validate my_pack.yml   # the armor + the corpus guard
+lictor rule install my_pack.yml    # the technique becomes decidable AND buildable
+lictor plan target.facts --packs packs/
+lictor build ret2mything --facts target.facts
+```
+
+The LLM path goes through the same armor: `validate_pack` and
+`scaffold_exploit` on the MCP surface are the same doors, staged for
+review.

data/home/runner/work/augure/augure/docs/explanation-architecture.md

@@ -0,0 +1,74 @@
+# Architecture: why rules-as-data
+
+*Explanation. The design rationale.*
+
+## The one decision that shapes everything
+
+> **Separate what the target IS (facts) from what you DO about it (rules),
+> and make both data.**
+
+Everything else follows. The fact schema is a schema; the rules are rows;
+the engine is an interpreter over the rows. That separation is what makes
+an auditable decision layer possible at all:
+
+- **Provenance**: only data can answer "which rule fired because of which
+  facts" - a case statement cannot explain itself.
+- **A second engine**: rules-as-data can be generated into a the frozen corpus .dl
+  program, so a compiled Datalog engine and the Ruby engine can be
+  conformance-tested against each other - the frozen corpus catches any
+  drift between them.
+- **The reverse reading**: "which protections kill which techniques" is
+  a table traversal, not a code trace.
+
+## The engine is boring on purpose
+
+Forward-chaining fixpoint over a tiny rule set: derive tuples until nothing
+new derives. No backtracking, no unification beyond equality, no cuts. The
+entire semantics fits in one file and one afternoon of reading. Boring is
+the point: auditable systems are systems a reviewer can finish.
+
+Negation is stratified by convention (only on input facts) and enforced by
+the corpus spec. Defaults are closed-world (`nx` absent means `nx("true")`)
+
+- documented, tested, and the single most surprising line in the engine.
+
+## Uncertainty, in three layers
+
+```mermaid
+graph TD
+    AG["Genetic algorithm<br/>offline, synthetic targets"] -- "finds weight inversions" --> P["prior table<br/>(ret2plt 15,5 vs the human ROP anchor)"]
+    P --> B["Bandit: Thompson sampling<br/>online, flat, auditable (seeded)"]
+    B -- "blind spot: choices look independent" --> M["MCTS over STAGE_MODEL<br/>a leak is worth what it unlocks"]
+    M --> D["plan: fmtstr_leak -> ret2libc"]
+```
+
+A flat bandit ranks `ret2libc` above a leak; MCTS plans the leak first
+because the transition table says what it unlocks. The planner's lesson,
+as a diagram.
+
+1. **Genetic algorithm (offline).** Evolved weight vectors over synthetic
+   targets; found the inversions humans miss. Research tool, stays in
+   Python - it is the narrative, not the SDK.
+2. **Bandit (online, flat).** Thompson sampling over Beta posteriors.
+   Adapts per target, remains auditable (seeded draws, logged feedback).
+   Blind spot: treats choices as independent.
+3. **MCTS (sequential).** Plans multi-step trajectories: a leak is worth
+   what it unlocks, which no flat weight can express. The STAGE_MODEL is a
+   transition table - data again, so the planner stays inspectable.
+
+## Subprocesses are the API policy
+
+SMT solvers, LLM providers: every external capability enters
+through a serialization boundary (facts text, SMT-LIB text, HTTP). That is
+what makes the zero-runtime-dependency gem possible, keeps native-extension
+attack surface at zero, and lets a consumer swap bitwuzla for cvc5 or an
+LLM backend without touching the core.
+
+## New proposal sources, and why they do not change this
+
+The profiler, the fuzzer's triage, and any future LLM feature extractor
+all emit *facts* into the same boundary. A hypothetical LLM hypothesis
+generator stays behind the whitelist: it proposes facts, the schema
+rejects anything else, the engine never sees a prose sentence. The
+architecture accepts new proposal sources because the contract was never
+"trust the source"; it is "speak fact, or leave".

data/home/runner/work/augure/augure/docs/how-to-swap-solver.md

@@ -0,0 +1,73 @@
+# How to: plug a real SMT solver
+
+Assumes augure is installed. Goal: route the numerical checks through z3,
+bitwuzla or cvc5 instead of the arithmetic fast path.
+
+## 1. Install a solver
+
+```sh
+apt install z3          # or brew install z3
+# bitwuzla and cvc5 have upstream binaries
+```
+
+## 2. Emit the SMT-LIB and solve it
+
+```ruby
+require "augure"
+
+smt = Augure::Verifier.payload_fits_smtlib(256, 40)
+puts smt
+# (set-logic QF_LIA)
+# (declare-const buffer_size Int)
+# (assert (= buffer_size 256))
+# (assert (>= buffer_size 40))
+# (check-sat)
+
+status = Augure::SmtProcess.solve(smt, solver: "z3")
+# => :sat
+```
+
+The contract is text-in, status-atom-out:
+
+| Return | Meaning |
+|---|---|
+| `:sat` | constraint satisfied |
+| `:unsat` | constraint violated |
+| `:unknown` | solver missing, timed out, or answered garbage |
+
+`:unknown` is deliberate: a verification *failure* must be visible and
+logged, never a crash. Treat `:unknown` as "do not claim verified".
+
+## 3. Solver options
+
+```ruby
+Augure::SmtProcess.solve(smt, solver: "bitwuzla", timeout: 5)
+```
+
+- `solver` - any binary that reads SMT-LIB v2 on stdin.
+- `timeout` - seconds (default 10). Expiry returns `:unknown` and kills the
+  child process.
+
+## 4. Which path should you use?
+
+The arithmetic fast path answers the same questions without a subprocess:
+
+| | arithmetic | SMT solver |
+|---|---|---|
+| latency | nanoseconds | milliseconds (process spawn) |
+| dependencies | none | solver binary |
+| audit value | provable by inspection | provable by solver certificate |
+
+Default to arithmetic; reach for the solver when a check outgrows integer
+arithmetic (bit-vectors, arrays, string constraints). The corpus spec pins
+both paths to the same answers, so switching never silently changes a
+verdict.
+
+## Troubleshooting
+
+- **`:unknown` with a solver installed** - run the emitted text manually:
+  `z3 < smt.txt` and read its stdout. Augure only
+  parses a bare `sat`/`unsat` token; solver banners are fine, they are
+  ignored.
+- **Permission denied** - the solver path is not executable; give the
+  absolute path.

data/home/runner/work/augure/augure/docs/how-to-write-rules.md

@@ -0,0 +1,71 @@
+# How to: write a technique rule
+
+Assumes you have run the tutorial and understand the fact format. Goal: add
+a rule to the applicability table with test coverage and provenance.
+
+## 1. Add the rule to the table
+
+Open `lib/augure/rules.rb`. Rules live in one place - the table IS the
+engine. Add yours where it belongs in the reading order:
+
+```ruby
+b.rule :app_my_technique, ["applicable", "my_technique"],
+       source: "one line: when does this fire and why" do |c|
+  c.fact "vuln", "sof"
+  c.fact "nx", "true"
+  c.fact "plt", "pwnme"
+end
+```
+
+Condition vocabulary:
+
+| Condition | Meaning |
+|---|---|
+| `c.fact rel, val` | a tuple `rel("val")` exists |
+| `c.not_fact rel, val` | that tuple is absent (input relations only) |
+| `c.match rel, idx, "pattern"` | arg `idx` matches the regex |
+| `c.cmp rel, :ge, 26` | an integer arg satisfies the comparison |
+
+## 2. Test it (before the rule exists in your head, after in the file)
+
+```ruby
+# spec/augure/engine_spec.rb
+it "fires my_technique when pwnme is imported" do
+  f = "vuln(\"sof\").\nnx(\"true\").\nplt(\"pwnme\").\n"
+  expect(applicable(f)).to include("my_technique")
+end
+
+it "does not fire my_technique without NX" do
+  f = "vuln(\"sof\").\nnx(\"false\").\nplt(\"pwnme\").\n"
+  expect(applicable(f)).not_to include("my_technique")
+end
+```
+
+Run `bundle exec rspec`. If the frozen CTF corpus conformance spec now fails,
+your rule changed an existing decision: that is either a bug in the rule or
+an improvement - update the corpus entry and say which, in the commit.
+
+## 3. Check the provenance appears
+
+```sh
+bundle exec ruby -e '
+require "augure"
+r = Augure::Pipeline.analyze(facts: "vuln(\"sof\").\nnx(\"true\").\nplt(\"pwnme\").\n")
+p r[:explain][:provenance]["my_technique"]
+'
+```
+
+You should see `rule: :app_my_technique` with the evidence pairs. That is
+the audit payload - it is automatic, you earned it by using the table.
+
+## Rules of the road
+
+- **One rule, one reason.** Split OR-conditions into sibling rules sharing a
+  head; the provenance then tells *which* reason fired.
+- **Negation on inputs only.** `not_fact` on a derived relation breaks
+  stratification; the corpus conformance spec will catch it loudly.
+- **Defaults are closed-world.** Absent `nx` means `nx("true")` - document
+  any rule that depends on absence.
+- **The corpus is the contract.** A rules commit that moves a corpus verdict
+  must update `lib/augure/ctf_corpus.json` in the same commit and justify
+  the move in the message.

data/home/runner/work/augure/augure/docs/pack-format.md

@@ -0,0 +1,137 @@
+# Pack format: teach augure a new technique (as data)
+
+*How-to. For operators and LLM agents. You write a YAML file; the armor
+decides whether augure learns it.*
+
+## The one rule before anything
+
+**You write data, never code.** A pack is a constrained YAML document.
+If your intent needs something the format cannot express, the format
+will refuse it - that is the design, not a bug. The vocabulary exists
+so that a wrong pack is impossible, not merely discouraged.
+
+## Anatomy
+
+```yaml
+technique: my_new_technique      # [a-z0-9_]+ - the NEW technique's name
+author: claude-code (session 2026-10-03)   # mandatory: who taught augure
+source: https://...              # mandatory: a verifiable reference
+rules:
+  - id: app_my_new_technique     # convention: app_<technique>
+    head: [applicable, my_new_technique]
+    conditions:                  # ONLY the 4 forms below
+      - [fact, vuln, sof]        # a tuple vuln("sof") exists
+      - [not_fact, relro, full]  # absent (input facts ONLY)
+      - [match, gadget, 0, pop]  # gadget arg 0 matches /pop/
+      - [cmp, glibc_minor, ge, 26]  # integer arg >= 26
+kb:
+  - id: my_new_technique_001
+    technique: my_new_technique
+    description: >
+      What the technique is, when it applies, what it needs. This is
+      what the agent (or human) will read back from `augure explain`.
+    chain: [step_one, step_two]
+    unlocks: [libc_base]
+    success_rate: 0.7             # 0..1 - authored, say so if uncertain
+mcts:
+  requires: []                   # capabilities needed before this runs
+  provides: [libc_base]          # capabilities it unlocks
+  terminal: false                # true only if it yields a shell
+  success: 0.7                   # the planner's base success
+priors: [14, 6]                  # Beta(alpha, beta): mean 0.7 here
+
+# All three sections below are OPTIONAL:
+build:                           # (check 8) the assembly order - packs
+  technique: my_new_technique    # teach, lictor's builder follows
+  layout:                        # slots: padding/qword/dword/shellcode/chain
+    - [padding, measured_offset]
+    - [chain, "gadget:pop_rdi_ret", "plt_addr:system"]
+
+detection:                       # (check 9) the DEFENDER side - what the
+  - channel: wire                # technique looks like to the defenses;
+    signature: "cyclic padding then a non-mapped return"  # channel from
+    note: "the padding phase"    # wire/syslog/syscall/crash/file
+
+mitre:                           # (check 10) the ATT&CK mapping
+  - T1068
+```
+
+## The checks (in the order the loader runs them)
+
+1. **Condition vocabulary**: only `fact`, `not_fact`, `match`, `cmp`.
+   Anything else - including "clever" ones - is refused.
+2. **Existing predicates only**: your conditions may reference the 33
+   input facts (see `docs/reference.md#schema` - the binary vocabulary:
+   nx/pie/canary/plt/gadget/plt_addr/got_addr...; the network vocabulary,
+   emitted from nmap scans: service/software_version/remote; the
+   confidence marker: verified; the leaks: leaked_address) and the
+   built-in derived relations (`vuln`, `has_reg_control`,
+   `has_write_primitive`, `has_syscall_gadget`, `has_csu_gadget`,
+   `has_pivot_gadget`, `enough_gadgets`). You cannot invent a fact
+   source.
+3. **Stratification**: `not_fact` on input facts only.
+4. **New heads only**: your technique must be NEW. Overriding
+   `ret2plt` or any built-in is refused - the corpus owns those verdicts.
+5. **Priors and rates in range**: priors are exactly `[alpha, beta]`
+   numbers; success rates in `[0, 1]`.
+6. **Corpus guard**: with your pack loaded, all 33 frozen corpus
+   targets must keep their documented ranking (your technique may rank
+   BELOW the documented top). A pack that takes the top-1 of a
+   documented target is refused - claiming better on frozen truth is a
+   dev-time corpus update, not a runtime pack. Two documented
+   exceptions: an entry with an EMPTY built-in verdict has nothing to
+   move (additive packs extend it), and an entry documenting
+   `pack_verdict: <technique>` polices the pack answer's ARRIVAL
+   instead - the pwnable/orw case.
+7. **match patterns and cmp operands fail at load**: a `match` pattern
+   is precompiled (`RegexpError` at load, not at decision); `cmp`
+   operands must be integers and operators from the engine's table -
+   `"26"` or a typo'd operator never reaches the engine.
+8. **build: (optional)**: must name its own technique; the layout must
+   be a non-empty slot list from the vocabulary
+   (padding/qword/dword/shellcode/chain). The builder interprets; the
+   armor gates the vocabulary.
+9. **detection: (optional)**: each entry needs a `channel` from
+   wire/syslog/syscall/crash/file plus a concrete `signature` and
+   `note` - a vague hint is not detection content.
+10. **mitre: (optional)**: an array of ATT&CK technique codes
+    (`T1068`, `T1068.001`) only.
+
+## The optional `build:` and `detection:` sections
+
+`build:` teaches the BUILDER the technique's assembly order (packs
+teach, lictor's builder follows): the layout must be a slot list from
+the vocabulary (padding/qword/dword/shellcode/chain - see
+build-format.md), the technique must be the pack's own. Armor check 8.
+
+`detection:` is the DEFENDER side of the technique - the corpus read
+backwards. One entry per observable: `channel` from the constrained
+vocabulary (wire/syslog/syscall/crash/file), a concrete `signature`,
+and a `note` saying what the observable means. A vague hint is not
+detection content - the armor rejects it (check 9). The blue team
+consumes these with `augure rules --mitre` and the hardened-coverage
+flow; a pack without `detection:` teaches the offense but leaves the
+defense blind.
+
+## The cycle
+
+```sh
+lictor rule validate my_pack.yml    # dry-run: schema + corpus guard
+lictor rule install my_pack.yml     # interactive confirm, versioned, trailed
+augure analyze target.facts         # your technique is now decidable
+```
+
+Via an MCP agent: the rules change every future decision - the
+operator reads the validated pack before installing it.
+
+## Writer's discipline (for agents especially)
+
+- Copy `packs/ret2csu_v2.yml` (the canonical example) - change the
+  substance, keep the structure.
+- `success_rate` and `priors` are authored numbers: ground them in the
+  source you cite, and say so in the description if they are estimates.
+- If validation refuses you, read the refusal - each check names its
+  reason. Fix the data; never look for a way around the armor.
+- One pack = one technique. Split OR-conditions into sibling rules
+  sharing the head; the provenance then carries EVERY reason that
+  fired, each attributed to its own rule.