opencode-codeops 1.4.0

package/skills/preflight/dimensions.md

@@ -0,0 +1,181 @@
+# Preflight — The 13-Dimension Scan (detail)
+
+> **CodeOps Artifact Schema**: 1
+
+Read this file before executing Step 3 of the protocol — and especially before auditing a plan,
+where Dimension 13 (Codebase Alignment) carries the most weight. Steps 1 and 2 set up the scan;
+this file covers reconnaissance detail and the full dimension definitions.
+
+## Step 1: Load and understand the artifact
+
+Before scanning, you MUST:
+
+1. **Read the complete artifact** — every document, section, and line.
+2. **Identify the artifact type** — requirements set, implementation plan, or ad-hoc document.
+3. **Load context** — read the project's AGENTS.md (or detected project conventions); understand
+   the tech stack, conventions, and constraints.
+4. **Read the Ambiguity Register** (if one exists) — `requirements/00-ambiguity-register.md` or
+   `plans/<name>/00-ambiguity-register.md`. Understand what decisions were already made and why.
+5. **Freeze the scope** — record the exact audit target, context documents, and authorized
+   modification set. Reading a related document does not add it to the target.
+6. **Resolve artifact identity** — use the exact user-selected file or directory as the audit
+   target. Related artifacts are context; findings do not silently expand the modification set.
+7. **Freeze product scope** — load
+   [../../_shared/scope-expansion-control.md](../../_shared/scope-expansion-control.md), record
+   strict or exploration mode, and separate defects in the authorized target from optional new
+   functionality suggested by the reviewer.
+8. **Load the minimum-sufficient baseline** — use `requirements/README.md` for a requirements set
+   or `00-index.md` for a full plan. For a legacy artifact without that section, derive the
+   original goal and smallest viable design only from explicit artifact statements and repository
+   evidence. If either is unclear, record a blocking ambiguity or finding; do not infer it.
+
+## Step 2: Codebase Reconnaissance — 🚨 NON-NEGOTIABLE
+
+This step is what separates a real preflight from a document-correction exercise. Without it, every
+dimension scan is blind. Build a thorough understanding of the actual codebase the artifact targets.
+
+### What to examine
+
+| What to examine | Why | How |
+|---|---|---|
+| **Project structure** | Understand what exists, how code is organized | List files on the project root recursively; read the directory layout |
+| **Entry points & main modules** | Understand architecture and flow | Read main/index files, server bootstrap, CLI entry points |
+| **Type definitions & interfaces** | Understand the data model and contracts | Read type files, interface definitions, shared types |
+| **Key source files** | Understand implementation patterns and conventions | Read files directly relevant to the artifact's scope |
+| **Existing tests** | Understand test patterns, what's already covered | Read test dirs, test helpers, test config |
+| **Package manifest & dependencies** | Understand available libraries | Read `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc. |
+| **Configuration files** | Understand build, deploy, runtime setup | Read tsconfig, webpack, docker-compose, CI/CD configs |
+| **Existing documentation** | Understand what's already documented | Read README, CHANGELOG, architecture docs |
+
+### Depth of reconnaissance by artifact type
+
+| Artifact type | Reconnaissance depth |
+|---|---|
+| **Requirements** | Moderate — understand architecture, patterns, and existing capabilities to assess feasibility and non-redundancy |
+| **Implementation Plan** | Deep — read every file the plan proposes to modify or depend on; verify every component/API/pattern reference; understand the dependency graph around the affected area |
+| **Ad-hoc Document** | Targeted — focus on the specific area the document addresses |
+
+> Reconnaissance is proportional, not exhaustive. For a plan that modifies 3 files, read those 3
+> files deeply plus their direct dependents — do not read the entire codebase for a small artifact.
+> For a single-RD or single-plan-document audit, related artifacts are context only. Use them to
+> prove or refute claims in the target; do not turn defects located solely in those documents into
+> findings against the selected artifact.
+
+### Mapping document references to code
+
+Systematically map every reference in the artifact to actual code:
+
+- Every **component, module, or service** → Does it exist? Where? What does it actually do?
+- Every **file or directory path** → Does it exist? Is the path correct?
+- Every **API, function, or class** → Does it exist? Does its signature match what's assumed?
+- Every **pattern or convention** assumed → Is it actually used in the codebase?
+- Every **dependency or library** referenced → Is it in the manifest? Right version?
+- Every **existing behavior** described → Is that actually how the code works?
+
+Any reference that cannot be verified against the code is a potential finding for the scan.
+
+### Present the Codebase Context Summary
+
+After reconnaissance, present:
+
+```markdown
+## Preflight: [Artifact Name]
+
+**Artifact Type:** [Requirements Set / Implementation Plan / Ad-hoc Document]
+**Documents:** [X] files, [Y] total sections
+**Ambiguity Register:** [Found — X items resolved / Not found]
+**Scope:** [Full scan / Targeted: specific document]
+
+### Codebase Context
+
+**Repository:** [project name]
+**Tech Stack:** [language, framework, key libraries — from actual package manifest]
+**Architecture:** [brief description of actual architecture observed]
+**Files Examined:** [N] source files, [M] test files, [K] config files
+**Key Observations:**
+- [Notable architectural pattern or convention observed]
+- [Key existing component relevant to the artifact]
+- [Important constraint or limitation found in the code]
+
+**Reference Verification:** [X] references mapped to code — [Y] verified, [Z] unverifiable
+
+Beginning 13-dimension scan...
+```
+
+## Step 3: The 13 dimensions
+
+Scan all 13 every time, with adversarial intent. Every check must be informed by Step 2.
+
+The dimensions test whether the requested artifact is sound; they are not permission to invent a
+larger product. Apply the necessary-correction burden of proof to every newly suggested behavior.
+In strict scope, omit optional additions completely. With active exploration, move them to the
+Scope Expansion Register without counting them as findings.
+
+| # | Dimension | What to hunt for |
+|---|---|---|
+| 1 | **Ambiguities** | Vague language, undefined terms, weasel words ("appropriate", "as needed", "etc."), statements with multiple interpretations, undefined behaviors |
+| 2 | **Implicit Assumptions** | Things taken for granted without stating, assumed capabilities/knowledge/environment. **Codebase check:** verify every assumption about the code — assumed APIs, data models, patterns, capabilities that may not exist or behave differently |
+| 3 | **Logical Contradictions** | Statements that conflict — across documents, sections, or within a paragraph. Inconsistent decisions, conflicting constraints |
+| 4 | **Completeness Gaps** | Missing requirements, journeys, error handling, edge cases, or acceptance criteria needed by the authorized behavior; do not treat adjacent optional functionality as missing. **Codebase check:** existing code/tests/functionality affected by the requested changes but not mentioned — missing impact analysis |
+| 5 | **Dependency Issues** | Circular/missing dependencies, dependencies on undefined components, tasks referencing not-yet-created entities, broken chains. **Codebase check:** verify referenced dependencies against the actual manifest and import graph — exist? right versions? undeclared deps relied on? |
+| 6 | **Feasibility Concerns** | Tasks possibly impossible/unrealistic, underestimated complexity, approaches incompatible with the stated stack, tasks too large to do atomically, or support machinery whose cost is disproportionate to the requested result. **Codebase check:** verify approaches against the actual architecture — will it work with how the code is structured? Do estimates match the real code? Does evidence show why the smallest direct solution fails? |
+| 7 | **Testability** | Requirements/tasks with no clear way to verify success, vague criteria ("should work well"), missing test specs, untestable acceptance criteria |
+| 8 | **Security Blind Spots** | Security defects that make the authorized behavior unsafe; distinguish a necessary correction from optional defense-in-depth functionality using grounded causal evidence |
+| 9 | **Edge Cases** | Boundary conditions and failure modes of the authorized behavior; do not invent adjacent journeys merely to fill the checklist |
+| 10 | **Scope Creep Indicators** | Existing artifact content that exceeds the confirmed baseline, unbounded tasks ("support all formats"), gold-plating, premature optimization, or a material new layer/dependency/harness/infrastructure surface without explicit complexity approval; newly imagined optional additions are silent or `SE-*` proposals, not findings |
+| 11 | **Ordering & Sequencing** | Tasks in wrong order, phases that should swap, work planned before its dependencies exist, missing foundation work. **Codebase check:** verify order against the actual dependency graph — real module boundaries, import chains, build dependencies |
+| 12 | **Consistency** | Naming inconsistencies across documents, conflicting conventions, terminology drift (same thing, different names), formatting that obscures meaning |
+| 13 | **Codebase Alignment** | **The master reality check.** Entirely codebase-grounded — see below |
+
+For Dimensions 6 and 10, apply the **Complexity Escalation Gate** in
+[../../_shared/zero-ambiguity-gate.md](../../_shared/zero-ambiguity-gate.md). An unapproved
+escalation is at least a 🟠 MAJOR finding and blocks a pass. Identify the smallest viable solution
+and the extra build and maintenance surface; do not treat sophistication as evidence of need.
+
+### Dimension 13: Codebase Alignment — detailed sub-checks
+
+Every sub-check requires completed Step 2 reconnaissance and must reference specific files/code.
+
+| Sub-check | What to hunt for | Example finding |
+|---|---|---|
+| **Phantom References** | Components/files/APIs/modules/classes/functions mentioned that do not exist | "Plan references `UserAuthService` in phase 3, but no such class exists. The actual auth logic is in `middleware/auth.ts` as a function chain." |
+| **Stale Assumptions** | Incorrect claims about how existing code works — wrong signatures, data flows, behavior | "RD-05 states 'the cache layer supports TTL per key' but `CacheManager.set()` has no TTL param — it uses a global TTL from config." |
+| **Architecture Mismatch** | Proposed patterns/structures that conflict with the established architecture | "Plan proposes a class-based service layer, but the codebase uses a pure-function pattern — every existing 'service' is an exported function." |
+| **Impact Blindness** | Existing code affected by the changes but not acknowledged | "Plan modifies the `User` interface in `types/index.ts` but doesn't mention the 14 files that import it, 6 of which would break." |
+| **Redundancy** | Things the document proposes to build that already exist | "RD-12 calls for 'a utility to parse env vars with defaults' — this already exists as `resolveConfig()` in `src/config.ts`." |
+| **Test Impact** | Existing tests that would break/become invalid, or test patterns the doc doesn't follow | "The plan adds a new tool but ignores the existing pattern in `tools-setup.ts` where all tools share a lazy-loaded store fixture." |
+| **Dependency Reality** | Assumed-available libs that aren't installed, or installed libs the doc ignores that could solve its problem | "Phase 2 proposes adding `lodash` for deep merge, but it isn't in dependencies. The project already has a custom `deepMerge` in `utils/`." |
+| **Convention Violations** | Proposed naming/organization/patterns that violate actual conventions | "Plan names the new file `getUserData.ts` but the project uses kebab-case: `get-rule.ts`, `search-rules.ts`." |
+| **Scope vs. Reality** | Complexity/effort estimates unrealistic given the actual code | "Plan estimates phase 4 (refactor caching) as 'straightforward, ~100 lines' but the cache spans 3 files, 450 lines, with 40 dependent tests." |
+| **Migration & Compatibility** | Missing data migration plans, backwards-compat concerns, or rollback strategies | "Plan changes the config file format but doesn't address migration for existing users on the old format." |
+
+**Rules for Dimension 13 findings:**
+
+- Cite the **specific file(s) and line(s)** that contradict or invalidate the artifact's claims.
+- Explain the **actual state** of the code, not just that it's "different".
+- Phantom-reference findings MUST suggest what the document **probably meant** if there's a close match.
+- Impact-blindness findings MUST list the **affected files** and how they'd be impacted.
+
+### Dimension depth by artifact type
+
+Scan all 13 every time; depth of analysis adapts:
+
+| Dimension | Requirements | Plans | Ad-hoc |
+|---|---|---|---|
+| Ambiguities | 🔥 Deep | 🔥 Deep | 🔥 Deep |
+| Implicit Assumptions | 🔥 Deep | 🔥 Deep | Standard |
+| Logical Contradictions | 🔥 Deep | 🔥 Deep | Standard |
+| Completeness Gaps | 🔥 Deep | 🔥 Deep | Standard |
+| Dependency Issues | Standard | 🔥 Deep | Light |
+| Feasibility Concerns | Standard | 🔥 Deep | Standard |
+| Testability | 🔥 Deep | Standard | Light |
+| Security Blind Spots | 🔥 Deep | Standard | Light |
+| Edge Cases | 🔥 Deep | Standard | Light |
+| Scope Creep Indicators | 🔥 Deep | 🔥 Deep | Standard |
+| Ordering & Sequencing | Light | 🔥 Deep | Light |
+| Consistency | Standard | Standard | Standard |
+| Codebase Alignment | 🔥 Deep | 🔥 Deep | Standard |
+
+- **🔥 Deep** — exhaustive analysis, actively hunt for issues.
+- **Standard** — thorough review, flag anything found.
+- **Light** — quick check, flag only obvious issues.

package/skills/preflight/report-format.md

@@ -0,0 +1,300 @@
+# Preflight — Report Format, Presentation & Persistence (detail)
+
+> **CodeOps Artifact Schema**: 1
+
+Covers Steps 4-8 of the protocol: compiling the report, presenting findings and collecting
+decisions, pass/fail determination, applying fixes, and roadmap sync — plus iterative re-scan
+numbering, report persistence, and same-agent-bias safeguards.
+
+## Step 4: Compile the Preflight Report
+
+Every finding gets a numbered, structured entry.
+
+### Finding template
+
+```markdown
+### PF-[NNN]: [Finding Title] [severity-icon] [SEVERITY]
+
+**Dimension:** [Which of the 13 dimensions]
+**Location:** [File path + section/line reference in the artifact]
+**Codebase Evidence:** [File path + line reference in the actual code, if applicable]
+**The Problem:** [Clear, specific description of what's wrong and WHY it matters]
+
+**Options:**
+
+| Option | Description | Pros | Cons |
+|--------|-------------|------|------|
+| A | [Description] | [Pros] | [Cons] |
+| B | [Description] | [Pros] | [Cons] |
+| C | [Description] | [Pros] | [Cons] |
+
+**Recommendation:** Option [X] — [concise rationale]
+
+**User Decision:** Pending
+```
+
+**Rules for findings:**
+
+- **Options must be genuinely viable, never strawmen** — present ≥2 options only when ≥2 are
+  genuinely viable. When one resolution clearly dominates, present it alone, state it is the only
+  viable one, and name what you considered and dropped and why. Never pad to a count to manufacture
+  a choice.
+- **Every finding MUST have a recommendation, with rationale** — never just "Option B is better".
+- **High-stakes findings (CRITICAL/MAJOR) get the hardening challenger — ONE per preflight scan,
+  not one per finding.** Per `_shared/recommendation-hardening.md` (challenger budget): spawn a
+  single challenger that receives the whole CRITICAL/MAJOR finding batch (statement + surviving
+  options per finding, without your picks) PLUS the scan's Codebase Context summary, and returns
+  per-finding verdicts to reconcile *before* recording recommendations. Hard cap: 2 challenger
+  spawns per scan. Close findings with the `Confidence:` / `Hardening:` disclosure where that
+  protocol requires it (Med/Low confidence, changed pick, or high stakes — presentation-only,
+  not a required saved field).
+- **Complexity escalations use the shared visible stop packet, not the ordinary compact finding
+  presentation.** Include and persist every approval-evidence field from the shared gate: original
+  goal, named extra system or support code, why it may be needed, codebase evidence, smallest
+  solution that still works, extra cost, independent verdict, and direct user decision. The larger
+  option remains blocked until the user explicitly chooses to approve that named machinery.
+  Generic finding acceptance does not approve it. The `PF-*` finding is the durable owner at
+  preflight.
+- **Findings are numbered sequentially by root cause** — `PF-001`, `PF-002`, ... A reopened root
+  cause retains its identifier across iterations; a new root cause gets the next unused number.
+- **Location must be specific** — "plans/my-feature/03-api-design.md, section 'Error Handling'", not
+  "somewhere in the plan".
+- **Codebase Evidence is required** for findings in dimensions 2, 4, 5, 6, 11, and 13 — cite the
+  actual file and code. For other dimensions, include it when relevant. If you can't verify a claim
+  against the code, say so: "Unable to verify against the codebase; this finding is based on the
+  document alone."
+
+### Report header template
+
+```markdown
+## Preflight Report: [Artifact Name]
+
+> **Status**: REVIEW IN PROGRESS — [X] findings ([C] critical, [M] major, [m] minor, [O] observation)
+> **Iteration**: [N] (first scan / re-scan after fixes)
+> **Artifact**: [type] at [path]
+> **Codebase Grounded**: [N] source files examined, [M] references verified
+> **Last Updated**: [Date]
+
+### Codebase Context Summary
+
+**Tech Stack:** [actual stack from manifest]
+**Architecture:** [brief architecture description from code examination]
+**Key Files Examined:** [list of most relevant files read during reconnaissance]
+
+### Summary by Dimension
+
+| # | Dimension | Findings | Highest Severity |
+|---|-----------|----------|-----------------|
+| 1 | Ambiguities | [count] | [icon] |
+| 2 | Implicit Assumptions | [count] | [icon] |
+| ... | ... | ... | ... |
+| 13 | Codebase Alignment | [count] | [icon] |
+
+### Summary by Severity
+
+| Severity | Count | Status |
+|----------|-------|--------|
+| CRITICAL | [N] | [all resolved? / X pending] |
+| MAJOR | [N] | [all resolved? / X pending] |
+| MINOR | [N] | [all resolved? / X pending] |
+| OBSERVATION | [N] | [all resolved? / X pending] |
+
+---
+
+[Individual findings follow]
+```
+
+Use the severity icons from SKILL.md (red/orange/yellow/blue circles) in the actual report.
+
+## Step 5: Present findings and collect decisions
+
+1. **Present grouped by severity** — CRITICAL first, then MAJOR, MINOR, OBSERVATION.
+2. **Present per the batch rules below** (they are authoritative for pacing) — each finding shown
+   with problem, options, recommendation.
+3. **Collect and record authority for every finding** before the report is final. In normal mode
+   use `**User Decision:** [their choice]`. With active auto-design, an eligible technical
+   resolution uses the canonical delegated marker and complete provenance from
+   `_shared/auto-design.md`; reserved decisions still use `**User Decision:**`. A delegated
+   resolution does not authorize applying the fix or waiving a finding.
+4. **Keep scope authority separate.** Finding resolution and expansion authorization are separate.
+   If an explored remediation exceeds the confirmed product scope, link the finding to its `SE-*`
+   proposal and collect a distinct `Keep`, `Defer`, or `Discard` ruling. In strict scope, optional
+   remediations are not reported.
+
+### Batch presentation rules
+
+- **<= 5 findings** — present all at once, let the user respond to each.
+- **6-15 findings** — present by severity group (all criticals, then all majors, etc.).
+- **> 15 findings** — present in batches of 5-8, grouped by severity, wait for confirmation between batches.
+
+**Previous decisions are respected (hard rule).** A finding that duplicates a decision already
+recorded in the artifact's Ambiguity Register — including a named `⏸ Deferred` row — is NOT
+re-presented for decision: record it as `Accepted Risk — deferred per AR #N` (or cross-reference
+the resolving AR #) and move on. Re-litigating decisions the user already made is a protocol
+violation, not thoroughness.
+
+**Complexity exception:** a deferred complexity decision is accepted risk only when the larger
+machinery is absent from the audited executable artifact. If it remains present, keep the finding
+open at 🟠 MAJOR until the artifact is changed and rechecked. Do not ask the user to decide the
+same deferral again.
+
+### Agent behavior during resolution
+
+| User says | Agent response |
+|---|---|
+| "Fix it per your recommendation" | Record `Resolved — User accepted recommendation: [Option X]`. Valid. |
+| "Go with Option A" | Record `Resolved — User chose Option A`. |
+| "This isn't actually an issue" | Record `Dismissed — User: "[reasoning]"`. Valid — only the user can dismiss. |
+| "I'll fix this later" | Ask to record as a known accepted risk (won't block the pass but noted). If yes: `Accepted Risk — User deferred: "[reason]"` — the preflight face of the shared `⏸ Deferred` status (`_shared/zero-ambiguity-gate.md`); name the decision, owner, and revisit-trigger in the reason. For extra complexity, this applies only after the machinery is removed from the executable artifact and rechecked. |
+| "You decide" | "I've given my recommendation above. Confirm you'd like Option [X]?" — user MUST explicitly confirm. |
+
+For a complexity escalation, explicit approval of the named larger machinery resolves the finding
+without an artifact edit. Choosing the smaller solution, revising, or deferring the larger
+machinery keeps the finding blocked until the artifact is changed and rechecked. If the required
+challenger is unavailable, the finding stays blocked.
+
+## Step 6: Determine pass/fail
+
+See the Pass tiers table in SKILL.md. A clean first-scan pass is a valid outcome — never invent
+findings to justify the review.
+
+## Step 7: Apply fixes (only if requested)
+
+The user may ask the agent to apply fixes:
+
+- **"Apply all fixes"** — modify the artifact documents per the resolved in-scope findings and
+  any linked proposals already ruled `Keep`; this does not authorize undecided, deferred, or
+  discarded `SE-*` entries.
+- **"Apply fixes for PF-003 and PF-007"** — apply specific fixes only.
+- **"I'll fix them myself"** — do nothing; the report is a checklist.
+- **"Apply fixes and re-scan"** — apply, then immediately run another iteration.
+
+> The agent MUST NOT apply fixes without explicit instruction. Preflight is a **review** protocol,
+> not a **modification** protocol. Finding issues and fixing issues are separate steps.
+> A fix instruction is also not scope-expansion authority; apply
+> `_shared/scope-expansion-control.md` before editing.
+
+## Step 8: Roadmap sync
+
+After a preflight **pass**, sync the roadmap via the roadmap skill if one is in play:
+
+- **If `plans/00-roadmap.md` exists:** advance the audited target's row —
+  - an **RD** that passed → stage `RD Preflighted`
+  - a **plan** that passed → stage `Plan Preflighted`
+
+  Update the row's `Stage`, `Status`, and `Last Updated` (update-first mandate).
+- **If `plans/00-roadmap.md` does NOT exist:** these hooks are inert — no error, no auto-creation.
+
+A BLOCKED outcome does NOT advance the roadmap. See the roadmap skill for the full protocol.
+
+## Iterative re-scanning
+
+### How iterations work
+
+1. **Iteration 1** — full 13-dimension scan of the original artifact (with full reconnaissance).
+2. **Fixes applied** — user resolves findings (manually or via "apply fixes").
+3. **Iteration 2** — re-scan focusing on: **verify fixes** (each resolved finding actually fixed),
+   **regression check** (fixes introduced no new issues), **bounded fresh scan** (re-examine all 13
+   within the unchanged audit target), and **codebase re-check** (re-verify changed references).
+4. **Iteration 3, only when blocking defects remain** — inspect the unresolved 🔴/🟠 fixes and their
+   direct dependency surface. Do not restart broad discovery.
+5. **Iteration 4+** — never automatic. Recommend a fresh-session audit to counter accumulated
+   framing bias, or obtain an explicit user decision to continue the current session.
+
+### Re-scan numbering
+
+Finding identifiers name root causes, not scan appearances:
+
+- a verified fix closes its existing `PF-NNN`;
+- a partial fix, residual contradiction, or regression with the same root cause reopens that
+  `PF-NNN` and adds an `Iteration N evidence` note;
+- a genuinely independent root cause receives the next unused number; and
+- merged or split symptoms retain a `Related findings` link so the audit trail stays navigable.
+
+Do not relabel a residual form of an old defect as a new finding merely to keep numbering
+continuous.
+
+### Re-scan report header
+
+```markdown
+## Preflight Report: [Artifact Name] — Iteration [N]
+
+> **Status**: [status]
+> **Previous Iteration**: [X] findings — [all resolved / Y carried forward]
+> **This Iteration**: [Z] new findings
+> **Carried Forward**: [list of PF-### still open from previous iterations]
+```
+
+### Convergence
+
+Use severity and decision state, not the desire for a zero-finding scan:
+
+| State after verification | Result |
+|---|---|
+| Any unresolved 🔴/🟠 | **Blocked**; a bounded corrective rescan is allowed |
+| No unresolved 🔴/🟠; one or more 🟡 pending | Collect decisions; do not rescan yet |
+| No unresolved 🔴/🟠; all remaining 🟡 explicitly accepted | **Passed With Notes**; stop |
+| Only 🔵 observations remain | **Passed With Notes**; stop unless the user requests fixes |
+| No findings remain | **Passed — Clean**; stop |
+| User stops with unresolved 🔴/🟠 | **Blocked**; record the stop without advancing the roadmap |
+
+Applying an accepted minor or observation does not by itself justify another full scan. Verify that
+edit directly; run another bounded scan only when the edit changes behavior, ownership, dependency
+ordering, security, compatibility, or another consequential contract.
+
+Before plan creation or execution consumes a passed artifact, compare its current git blob (or
+content hash when it is uncommitted) with the revision recorded by preflight. A mismatch makes the
+pass stale and requires a targeted re-check of the changed sections; it does not silently trigger a
+set-wide audit.
+
+## Report persistence
+
+Save the report alongside the artifact (locations in SKILL.md). It is a permanent audit trail.
+
+### Relationship to the Ambiguity Register
+
+Separate documents with different purposes:
+
+| Document | Created by | Purpose | Contains |
+|---|---|---|---|
+| **Ambiguity Register** (`00-ambiguity-register.md`) | make-plan / make-requirements skills | Track decisions made DURING creation | User decisions on design choices |
+| **Preflight Report** (`00-preflight-report.md`) | preflight | Track issues found DURING review | Post-creation defects, gaps, codebase misalignments, and resolutions |
+
+When a finding relates to an existing Ambiguity Register entry, cross-reference it:
+
+```markdown
+**Related:** AR #7 decided on JWT auth, but this finding identifies a gap
+in the token refresh flow that AR #7 didn't cover.
+```
+
+Do not re-litigate an Ambiguity Register decision unless new information invalidates it — reference
+the AR entry and explain what changed.
+
+## Same-agent bias awareness — NON-NEGOTIABLE
+
+When the same model created the artifact and reviews it, systematic blind spots are likely — shared
+training biases, knowledge gaps, and reasoning patterns. A bug missed during creation is exactly
+the kind of bug that will be missed during review. Structural safeguards:
+
+1. **Fresh context required** — if the artifact was created in the CURRENT session, note it at the
+   top of the report:
+   ```
+   SAME-SESSION REVIEW: This artifact was created in the current session.
+   Same-agent bias risk is elevated. Consider running preflight in a new session
+   for maximum review independence.
+   ```
+2. **Standard-first checking** — for any behavior that must conform to an external standard (RFC,
+   protocol, spec, regulation), verify by **citing the specific standard text**, not from memory.
+   If you can't cite it, flag the limitation:
+   ```
+   Unable to verify conformance with [standard] — agent does not have
+   access to the full standard text. Flag for human review.
+   ```
+3. **Adversarial question checklist** — before concluding the scan, ask yourself:
+   - "What assumption did I make during creation that I might be unconsciously confirming now?"
+   - "What external standard or convention might this violate that I'm not aware of?"
+   - "What would a domain expert who disagrees with my approach flag as wrong?"
+   If any surface concerns, add them as observation findings.
+4. **User recommendation** — if the artifact is high-stakes (security/compliance/architecturally
+   foundational), recommend: "Consider having a human domain expert review this in addition to
+   the automated preflight."