aepkit 0.6.0__py3-none-any.whl

aepkit/skill/references/failure-modes-and-example.md

@@ -0,0 +1,103 @@
+# Failure Modes and Worked Example
+
+Part of the `auditor-executor-protocol` skill. Load when auditing a delivery or looking for a filled-in run. Section names in
+quotes ("Rules of engagement", "Auditing", ...) refer to `SKILL.md` unless they are in
+this file.
+
+## Failure modes seen in practice
+
+- **Self-expansion.** The Executor implements phases marked "do not start." Work
+  arrives with no checkpoints between phases; a defect in an early one gets built on
+  before anyone looks.
+- **Zero stops.** An empty "Blocked" section across dozens of tasks means ambiguities
+  were resolved silently, not that none existed.
+- **Letter over intent.** The task says "add a check for case X"; a check appears, it
+  passes, and the condition X exists to detect is routed around by fixture ordering or
+  test isolation. Anticipate this by naming the expected failure in the task itself.
+- **Evidence-free `DONE`.** Treat as `FAILED`. Say so in the reporting rules up front.
+- **The Auditor shrinks the goal.** Asked for a whole outcome, the plan delivers a
+  slice of it and calls the rest "follow-up," backed by a risk/ROI argument. Shrinking
+  the goal is never authorized; splitting it into phases is fine, as long as the goal
+  is met. Big goals get more phases, never a smaller goal — later phases are part of
+  the run, not a follow-up.
+- **Silent model inheritance.** A subagent launched without an explicit model runs on
+  the Auditor's own model. Nothing fails; the rule is just broken on every task. Pass
+  it every time.
+- **Guided by habit.** In Autonomous mode, the Auditor ends a turn after a `PASS` to
+  "report," or asks the owner a question the charter already lets it decide. Each one
+  costs the owner a message and adds nothing.
+- **A defect ships and nobody owns re-checking its blast radius.** A task changes what
+  an existing field means; every other reader of that field is now a latent bug, and
+  the person who finds it is usually a different, unrelated task that happens to hit
+  it — not a re-audit of the original task. Grep for every reader before signing off,
+  not after something breaks.
+- **A change primes something to fire on its own before anyone can see or stop it.** A
+  migration or config change that alters what triggers an automated write can leave
+  the system armed to act — at scale, on real data — the moment its ordinary trigger
+  next runs, with no one having pressed a button and no UI yet built to see or cancel
+  it. Check the state the change leaves behind, not only the correctness of the new
+  code path.
+
+## Worked example
+
+Everything below is fictional and sanitized. It shows the shape of each artifact, not
+content to copy. Names, commands and risks in a real run come from that project.
+
+**Plan:** "Notifications as a standalone service" in a web shop. Goal set by the owner:
+every notification leaves the monolith. Acceptance criteria AC1-AC4. Phases P0-P5, with
+P0-P2 expanded into tasks and P3-P5 fixed in scope, expanded by the Auditor at each gate.
+Mode: Autonomous (governance decision D9 in the plan of record).
+
+**Rules-of-engagement block (item 8)**, as it would appear in each handoff:
+
+```
+- One task at a time.
+- Verification = run the command and the negative controls, not read the code.
+- Fetch and compare against the remote branch before starting and before pushing.
+- <project's quality-gate command> exits 0 before any push.
+- Every commit to the main branch bumps the version with <project's version script>.
+- No AI tool co-authorship on commits.
+```
+
+**Auditor brief (abridged):**
+
+```
+ROLE: Auditor of plan "Notifications as a standalone service". You do not write feature
+code. You run this in Autonomous mode: launch Executors as subagents, audit each
+delivery by re-running it, resolve their questions, expand P3-P5 once the previous gate
+is APPROVED. Follow the auditor-executor-protocol skill.
+
+AUTONOMY (D9; "Coordination and autonomy" section of the guide):
+- You decide anything the documents leave open; amend decisions by annex with evidence.
+  You never amend AC1-AC4 or reduce scope.
+- BLOCKED → decision entry in the log; the task continues.
+- Permissions needing the owner: one batched request. Short report per closed phase.
+- ONLY reasons to interrupt the owner:
+  1. Reducing or reinterpreting AC1-AC4.
+  2. Deleting production data without a verified, restorable backup.
+  3. A real email or SMS sent to a customer.
+  4. Charges, refunds, or billing changes not proven equivalent.
+  5. Production down after a deploy with no successful rollback.
+  6. An exposed secret.
+  7. Force-push or disabling CI.
+
+EXECUTOR MODEL ASSIGNMENT: small/fast tier for P0-T1, P1-T3, P2-T4 (listed commands,
+bump, gate, push). Mid tier for the rest. Top tier never. Model explicit on every
+launch; if a small-tier task goes off-script, relaunch the whole task on the mid tier.
+
+STATE: clean tree, plan committed and pushed. First task: P0-T1 on the small/fast tier.
+
+GOAL (non-negotiable): no notification leaves the monolith. RUN COMPLETE only with
+P5-G1 APPROVED, which proves AC1-AC4.
+
+WHAT'S VERIFIED AND WHAT ISN'T:
+- Verified (command in the plan): all 14 send sites in the inventory.
+- Not verified: whether the SMS provider accepts idempotency keys (P2-T2 measures it).
+
+TRAPS: "doesn't send" checks that pass because the mock was never registered; negative
+controls restored with a command that wipes other uncommitted work; a small-tier task
+that patches an unexpected surprise itself instead of escalating.
+
+FIRST STEP: read the three documents, confirm the log is empty, launch P0-T1 on the
+small/fast tier.
+```

aepkit/skill/references/handoffs.md

@@ -0,0 +1,133 @@
+# Handoffs
+
+Part of the `auditor-executor-protocol` skill. Load when handing a task to an Executor or writing a remediation order. Section names in
+quotes ("Rules of engagement", "Auditing", ...) refer to `SKILL.md` unless they are in
+this file.
+
+## Handing off a task (Auditor)
+
+Writing the execution guide is not the handoff. The Executor's session starts cold — it
+has none of the investigation behind the guide, and "read the execution guide, task
+`<ID>`" is a pointer to an instruction, not the instruction itself. Producing the actual,
+paste-ready message for a fresh Executor session is Auditor work, not something left for
+whoever is relaying the plan to assemble by hand.
+
+**The rules-of-engagement block in the template below is item 8, settled when the run
+started** ("Rules of engagement" in `SKILL.md`) — not re-derived here, and not re-asked per
+task. If you're about to write a handoff and item 8 is still blank, that's the actual
+problem: go settle it before drafting the message, don't paste a rule set from a
+different project or a different run to fill the gap. A rule copied in from elsewhere
+either asserts something false about this codebase or hands the Executor a stop it has
+no way to satisfy.
+
+### Handoff template
+
+One task per message, addressed to a fresh Executor session with no shared context. Fill
+every section — do not leave "see the execution guide" where a fact belongs.
+
+```
+ROLE: Executor. Work from <EXECUTION_GUIDE> (Phase <n>, `<TASK-ID>`) only; report in
+<COMPLIANCE_LOG>, section `<TASK-ID>` (already exists, empty).
+
+[Autonomous mode only:] You are the Auditor's subagent. Questions go as BLOCKED in the
+log and in your final report; you do not address the owner.
+
+REPORTED STATE: <what is already DONE in the log, and whether it was audited or only
+self-reported — do not conflate the two>. Do not reopen <prior tasks>.
+
+TASK: <TASK-ID> — <imperative title>
+Source: <EXECUTION_GUIDE>, section "<TASK-ID>" in full.
+
+Goal: <one sentence — what is true after this that was not before>.
+
+Key finding (already verified, do not re-check it): <the concrete fact driving this
+task, with the file/line/command that established it>.
+
+Decided points, not reopenable without evidence that contradicts them:
+1. <decision>
+2. <decision>
+...
+
+Failure to avoid explicitly: <the specific mistake a context-free Executor would make by
+reflex — copying a neighboring task's filter that doesn't apply here, re-deriving a
+fact that was already established and getting it wrong, etc.>.
+
+Verify (literal):
+<exact command>
+
+Success, minimum: <what the check(s) must prove, in terms of cases — not "it passes">.
+
+Report: <TASK-ID>, in <COMPLIANCE_LOG>, section already created.
+
+RULES OF ENGAGEMENT (this run's — confirmed at the start, not a default):
+<the block settled above>
+```
+
+`Key finding` and `Failure to avoid` exist because a fresh Executor has no memory of the
+investigation behind the task — it will make exactly the mistake full context would have
+prevented. Naming the specific reflex to avoid is cheaper than an Executor discovering it
+mid-task.
+
+Do not paste a rules-of-engagement block from one project's run into another's handoff
+without re-confirming it applies. It is a per-run artifact, not part of this skill.
+
+## Remediation handoff (Auditor)
+
+A verdict is not the deliverable — a well-evidenced `CONDITIONAL` or `REJECTED` that
+ends in prose still leaves the Executor with nothing to act on. This is the
+`Remediation order (annex)` from "The document set": write it, and hand it off the same
+way the first task was handed off, not as a narrative the reader has to translate into
+next steps themselves.
+
+```
+ROLE: Executor. Work from this remediation only; the rest of <EXECUTION_GUIDE> is
+unaffected unless named below. Report in <COMPLIANCE_LOG>, appended under <GATE-ID> —
+do not overwrite the original entry.
+
+MODEL: <the original task's, or the next tier up if this is an escalation>.
+
+AUDIT RESULT: <Phase/Task> — <CONDITIONAL | REJECTED>. <one line: what was
+independently re-verified and passed, so the Executor knows what not to touch>.
+
+BLOCKED: <GATE-ID> — <what's actually wrong, in the Auditor's own re-run terms, not a
+restatement of what the original delivery claimed>.
+
+Root cause (verified — carries the command that established it, not reasoned from the
+code): <the mechanism, with file/line and the falsifying probe or command that proved
+it wrong>.
+
+Candidate fix — a recommendation, not a decided point; the Auditor has not run it:
+<the shape of a fix. Mark explicitly as unverified — the Executor confirms it, and may
+find a better one, per "a factual claim always is reopenable">.
+
+Do not touch: <what already passed and must not be disturbed by this fix — the other
+approved gates or tasks in this delivery>.
+
+Verify (literal): <the exact re-run command(s), including re-running the falsifying
+probe that caught this — it must now pass>.
+
+Success, minimum: <what must be true afterward — the probe that failed now passes, the
+original suite stays green, nothing named under "Do not touch" moved>.
+
+Report: <GATE-ID>, in <COMPLIANCE_LOG>, as a remediation entry.
+
+RULES OF ENGAGEMENT: <this run's block>
+```
+
+The "candidate fix, not a decided point" framing matters — the Auditor found the defect
+by running a probe, not by running the fix. Presenting it as settled would violate the
+Auditor's own rule 4 ("The Auditor is bound by rule 4 too" in `SKILL.md`).
+
+**No verdict ends the loop by itself if anything is left to run — and "anything left to
+run" is not only "a phase remains" or "a remediation order is needed."** It also covers
+the most common case of all: a plain `PASS` on one task, mid-phase, with something else
+already outstanding — an earlier remediation, the next task in line. That case has no
+name of its own in the Verdicts table of `SKILL.md`, which is exactly why it's the easiest one
+to ship without a handoff: closing with a status sentence that *describes* what's still
+pending, instead of resending the pasteable block for it. Only a genuine "nothing left"
+closes without a handoff. Otherwise: send the outstanding remediation, or the next
+phase's first task, or the handoff already sent and not yet acted on — with the literal
+template from "Remediation handoff" or "Handing off a task" above, in the same message
+as the verdict, never as a sentence describing it. The Executor's next session starts
+cold no matter which verdict just landed; a one-line summary of what's still owed is
+exactly the kind of pointer-not-an-instruction this whole document exists to close.

aepkit/skill/references/tasks-and-gates.md

@@ -0,0 +1,84 @@
+# Writing Tasks and Gates
+
+Part of the `auditor-executor-protocol` skill. Load when writing a task or a gate. Section names in
+quotes ("Rules of engagement", "Auditing", ...) refer to `SKILL.md` unless they are in
+this file.
+
+## Writing a task (Auditor)
+
+```
+### <TASK-ID> — <imperative, one line>
+
+**Goal:** one sentence. What is true after this that was not before.
+**Files:** every path the Executor should read or change.
+**Blast radius:** every caller or reader of anything a step renames, empties, deletes, or
+  redefines — including a later task's planned work. Empty if genuinely none; never left
+  blank.
+**Steps:** numbered. Exact enough that two Executors produce the same thing.
+**Verify:** the literal command, and the output that counts as success.
+**Report:** the task ID.
+```
+
+Rules for the steps:
+
+- Encode decisions, do not re-open them. "Polling, not a push channel — this is
+  decided, believing otherwise is a stop, not a choice to make while implementing."
+- **Name the failure you expect.** If a field might get overwritten, if a type behaves
+  differently across two environments, if a cap is a layout decision and not a data
+  one — say so in the task. Most bad output comes from an ambiguity the task's author
+  already saw and didn't write down.
+- State what must *not* change alongside what must.
+- **The Blast radius field is not optional decoration — write it before the step, not
+  after something breaks.** When a task renames or redefines what an existing field or
+  column means, the task text must include the command to find every other reader of
+  it, and the Executor must run it and account for every hit, not only the call sites
+  the task's file list happened to name. When a step would empty, delete, or replace
+  shared code, check whether a *later* task in the same phase was planned to still call
+  it — if so, the step is "leave a delegating stub," not "empty it," until the task that
+  owns that caller lands. A task's file list is a lower bound on its blast radius,
+  discovered by the person who wrote the task before the work started — not the whole
+  of it, discovered later by whoever happens to hit the stale or broken reader next.
+- **When a task changes what triggers an automatic action** (a scheduler, a background
+  job, a materializer, anything that can fire without a human pressing a button), the
+  task must require checking — before shipping — what state the change leaves the
+  system in and whether anything is now primed to fire destructively on its next
+  ordinary trigger. Passing tests prove the new code path is correct; they do not
+  prove nothing is about to run against real data the moment it gets the chance.
+
+## Writing a gate (Auditor)
+
+A gate is a claim that can be proven false. "Tests pass" is not a gate. "The
+visibility check was observed failing with the filter removed" is.
+
+Every gate names how it is proven. Include, whenever the phase produces a security,
+privacy, or financial-integrity boundary, a **negative control**: the Executor must
+remove the protection, observe the check fail, restore it, and observe it pass. A
+check never seen failing has not been verified. It must also fail for the right
+reason: a syntax error or a missing import fails just as loudly, so the control names
+the failure it expects (the assertion, the status code) and the Auditor checks the
+output shows it. `aepkit negcontrol` runs this sequence and produces a paste-ready
+transcript; `--expect "<regex>"` makes it reject a failure whose output does not match.
+
+**A gate defined by more than one command must be re-run in full, not cited from
+whichever half was last checked.** A compound gate closed in one phase by running only
+one of its checks, then cited as "already satisfied" in later phase gates without ever
+re-running the rest, can let real violations accumulate for phases before anyone
+notices. If a gate's own definition lists multiple checks, every phase that claims it as
+satisfied re-runs all of them — a partial citation from an earlier phase does not close
+a compound gate.
+
+**A shared test fixture that always uses a simplified shape hides bugs that only appear
+with a realistic one.** A helper that builds request URLs, headers, or IDs for tests
+should default to a realistic shape (a base URL with its own path prefix, a populated
+auth header, a non-empty ID) rather than the minimal shape that's easiest to write —
+otherwise every test built on it passes for the wrong reason. When gating a feature that
+touches an external contract, prove it against at least one realistically-shaped
+fixture, not only the simplified one most unit tests use.
+
+**When a decision restricts what one channel may carry, check every other channel
+available for the same call.** A rule like "this value travels only via the field
+scoped for it, never the generic payload" is not proven by testing the transport where
+that rule was enforced — check whether the same data can leak through a sibling channel
+on a transport the restriction was never applied to, especially one that leaves your own
+infrastructure for a third party. A restriction proven on one channel or transport is
+not proven on all of them.

aepkit/status.py

@@ -0,0 +1,122 @@
+"""Tally the compliance log and print what is still open.
+
+Two sources are combined per task/gate ID:
+
+- the Auditor's verdict: the "Verdict" column of the status board table, or a report
+  header whose status is a verdict (APPROVED, CONDITIONAL, REJECTED);
+- the Executor's latest report header (DONE, BLOCKED, FAILED, PENDING).
+
+Only APPROVED closes an item. A DONE report without a verdict is self-reported, not
+audited, so it is listed as awaiting audit. When the board and a report header carry
+different verdicts, the item is listed as a conflict and stays open.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+LOG_HEADER_RE = re.compile(
+    r"^###\s+([A-Za-z0-9_.\-]+)\s+[\u2014\u2013\-]\s+([A-Za-z_]+)\s*$", re.MULTILINE
+)
+
+VERDICTS = {"APPROVED", "CONDITIONAL", "REJECTED"}
+CLOSED = "APPROVED"
+AWAITING_AUDIT = "AWAITING AUDIT"
+CONFLICT = "CONFLICT"
+
+
+def _cells(line: str) -> list[str]:
+    return [c.strip().strip("`*").strip() for c in line.strip().strip("|").split("|")]
+
+
+def _board_verdicts(text: str) -> dict[str, str]:
+    """ID -> verdict from the first table whose header has "ID" and "Verdict" columns."""
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        if not line.lstrip().startswith("|"):
+            continue
+        header = [c.lower() for c in _cells(line)]
+        if "id" not in header or "verdict" not in header:
+            continue
+        id_col, verdict_col = header.index("id"), header.index("verdict")
+        verdicts: dict[str, str] = {}
+        for row in lines[i + 1 :]:
+            if not row.lstrip().startswith("|"):
+                break
+            cells = _cells(row)
+            if len(cells) <= max(id_col, verdict_col) or set(cells[id_col]) <= set("-: "):
+                continue
+            verdicts[cells[id_col]] = cells[verdict_col].upper()
+        return verdicts
+    return {}
+
+
+def run(target_dir: str) -> int:
+    target = Path(target_dir)
+    log_path = target / "compliance-log.md"
+    if not log_path.exists():
+        print(f"error: {log_path} not found.", file=sys.stderr)
+        return 2
+
+    text = log_path.read_text(encoding="utf-8")
+
+    # IDs in first-seen order; for headers, the last occurrence wins (resubmissions).
+    order: dict[str, None] = {}
+    reports: dict[str, str] = {}
+    header_verdicts: dict[str, str] = {}
+    last_header_id = ""
+    board = _board_verdicts(text)
+    for task_id in board:
+        order.setdefault(task_id, None)
+    for m in LOG_HEADER_RE.finditer(text):
+        task_id, value = m.group(1), m.group(2).upper()
+        order.setdefault(task_id, None)
+        last_header_id = task_id
+        if value in VERDICTS:
+            header_verdicts[task_id] = value
+        else:
+            reports[task_id] = value
+
+    if not order:
+        print("no task entries found in compliance-log.md.")
+        return 0
+
+    states: dict[str, str] = {}
+    conflicts: dict[str, str] = {}
+    for task_id in order:
+        board_verdict = board.get(task_id, "")
+        board_verdict = board_verdict if board_verdict in VERDICTS else ""
+        header_verdict = header_verdicts.get(task_id, "")
+        verdict = board_verdict or header_verdict
+        report = reports.get(task_id, "PENDING")
+        if board_verdict and header_verdict and board_verdict != header_verdict:
+            states[task_id] = CONFLICT
+            conflicts[task_id] = (
+                f" (status board: {board_verdict}, report header: {header_verdict})"
+            )
+        elif verdict:
+            states[task_id] = verdict
+        elif report == "DONE":
+            states[task_id] = AWAITING_AUDIT
+        else:
+            states[task_id] = report
+
+    counts = Counter(states.values())
+    print("Status board:")
+    for state, n in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0])):
+        print(f"  {state:<15} {n}")
+
+    open_items = [(tid, st) for tid, st in states.items() if st != CLOSED]
+    print(f"\n{len(open_items)} open (not APPROVED):")
+    for tid, st in open_items:
+        report_of_item = reports.get(tid)
+        detail = f" (report: {report_of_item})" if report_of_item and st in VERDICTS else ""
+        detail = conflicts.get(tid, detail)
+        print(f"  - {tid}: {st}{detail}")
+
+    last_id = last_header_id or next(reversed(order))
+    print(f"\nMost recent entry: {last_id} ({states[last_id]})")
+    return 0

aepkit/templates/compliance-log.md

@@ -0,0 +1,37 @@
+# {{PROJECT_NAME}} — Compliance Log
+
+> **Evidence of record.** One report and one verdict per task/gate ID. Pre-generate an
+> empty row per ID from the execution guide so nothing gets skipped silently.
+>
+> Maintained by the Auditor after every verdict. Compact repeated open conditions
+> periodically instead of only appending — see the protocol's note on log maintenance.
+
+---
+
+## Status board
+
+| ID | Delivery | Verdict | Notes |
+|---|---|---|---|
+| P0-T1 | | `PENDING` | |
+| P0-G1 | | `PENDING` | |
+
+---
+
+## Open conditions
+
+None yet.
+
+---
+
+## Reports
+
+### P0-T1 — PENDING
+**Changed:**
+**Verify output:**
+**Observations:**
+**Decisions made without stopping:**
+
+### P0-G1 — PENDING
+**Verify output:**
+**Observations:**
+

aepkit/templates/execution-guide.md

@@ -0,0 +1,75 @@
+# {{PROJECT_NAME}} — Execution Guide
+
+> **You are the Executor.** The Auditor wrote this file and will re-run every gate
+> independently. Read `plan-of-record.md` once for context, then work only from here.
+> Report every task in `compliance-log.md`.
+
+---
+
+## Rules of engagement
+
+1. **One task at a time, in order.** No batching. Do not start a phase whose
+   predecessor is not marked `APPROVED` in the compliance log.
+2. **Never invent a value the codebase declares.** Read it. Needing to ask for one
+   means a file was skipped.
+3. **Never guess a cause. Observe it.** Read the log, run the query, print the value.
+4. **Verification is running the thing, not reading the code.** "I reviewed it and it
+   looks correct" is reported as `FAILED`.
+5. **Scope is the task text.** Unrelated problems go in *Observations*. Do not fix
+   them.
+6. **Stop and ask** when this document contradicts the code, when a task needs a
+   decision this document does not make, or when a previously passing check starts
+   failing for reasons unrelated to your change. If you resolve an ambiguity without
+   stopping, log the decision. A decision in the plan of record is settled; a factual
+   claim never is — if this document states something the code contradicts, the
+   evidence outranks the order.
+7. **When the system cannot do what a task asks, that is the deliverable.** Report it
+   and stop. A task that ends in a well-argued finding is a success.
+8. Project-specific rules that apply to every task — list them here, cited from their
+   source rather than restated:
+   -
+   -
+
+## Reporting format
+
+For each task, append to `compliance-log.md`:
+
+```
+### <TASK-ID> — DONE | BLOCKED | FAILED
+**Changed:** <paths>
+**Verify output:**
+<pasted, literal, unedited command output>
+**Observations:** <or "none">
+**Decisions made without stopping:** <or "none">
+```
+
+A `DONE` with no pasted output is recorded as `FAILED`.
+
+---
+
+# Phase 0 — <name>
+
+### P0-T1 — <imperative, one line>
+
+**Goal:**
+**Files:**
+**Steps:**
+1.
+
+**Expected failure to avoid:**
+
+**Verify:**
+```bash
+```
+
+**Report:** `P0-T1`
+
+---
+
+### P0-G1 — Gate: <claim under test>
+
+**Proven by:** <the check that proves the claim>
+
+**Negative control:** <how you remove the protection, which check fails, and that it passes again once restored>
+
+**Report:** `P0-G1`

aepkit/templates/plan-of-record.md

@@ -0,0 +1,79 @@
+# {{PROJECT_NAME}} — Plan of Record
+
+> **Status:** draft. This document holds the *what* and the *why*. Nobody implements
+> from this file. The executable instructions live in `execution-guide.md`; evidence
+> goes in `compliance-log.md`.
+
+**Target version / milestone:**
+**Operating mode:** <Guided | Autonomous>
+
+---
+
+## 1. Why this exists (opportunity framing)
+
+What problem is this solving, and why now. If several requests trace back to one
+underlying gap, name the gap here rather than listing the requests as unrelated.
+
+- **Target outcome:** <measurable behavior, metric, or system state that changes when this is done>
+- **Problem / friction:** <verified gap or failure mode in the current system, without prescribing the feature yet>
+- **Cost of doing nothing:** <concrete impact of not doing this work or deferring it>
+
+## 2. What the audit of the current system found
+
+| Finding | Evidence |
+|---|---|
+| | |
+
+State each finding with the command or artifact that established it, not from memory.
+
+## 3. Opportunity shaping & decisions (settled — reopening one is a stop, not a choice)
+
+For open-design or new-capability work, compare at least three distinct approaches before
+locking the architecture. For deterministic bugfixes, security patches, schema migrations,
+or strict compliance work, mark the shaping and assumption fields as
+`N/A (Deterministic Fix/Compliance)` and go straight to `D1`.
+
+- **Option A (minimal / existing tooling / config-only):** <approach, cost, and limits — or `N/A (Deterministic Fix/Compliance)`>
+- **Option B (balanced / pragmatic implementation):** <approach, cost, and limits — or `N/A (Deterministic Fix/Compliance)`>
+- **Option C (full architectural / custom build):** <approach, cost, and limits — or `N/A (Deterministic Fix/Compliance)`>
+- **Selected option & rationale:** <which option wins and why the other two were rejected — or `N/A (Deterministic Fix/Compliance)`>
+- **Riskiest assumption & first-phase validation:** <the primary value, usability, feasibility, or viability assumption that could invalidate the plan, and how the first phase (`P0` or `P1`) tests it before building the rest — or `N/A (Deterministic Fix/Compliance)`>
+
+### D1 — <decision name>
+
+What was decided, what alternative was rejected and why, what failure this prevents.
+
+## 4. What this deliberately does not do
+
+Scope boundaries the Auditor is holding, so an Executor (or a future Auditor) doesn't
+drift into rebuilding something that was cut on purpose.
+
+- **Explicit non-goals:** <what is deliberately out of scope for this run>
+
+## 5. Phases
+
+When the plan carries an unverified technical or product assumption, the first phase
+(`P0` or `P1`) must test that riskiest assumption before building secondary scaffolding.
+
+| Phase | Delivers | Risk |
+|---|---|---|
+| | | |
+
+## 6. Deferred items ledger
+
+| ID | What | Deferred to | Closed by |
+|---|---|---|---|
+| | | | |
+
+Every decision or annex that pushes work to a future phase gets a row here in the same
+edit. An open row (`Closed by` without a task ID) for a phase being closed is a stop.
+
+## 7. Request traceability
+
+| Origin request | Where it lands |
+|---|---|
+| | |
+
+## 8. Standards this work is held to
+
+Cite the project's own conventions rather than restating them here.