dsh-compound-engineering 0.0.0-stage → 0.1.1

package/skills/ce-doc-review/references/document-intake.md

@@ -0,0 +1,44 @@
+# Getting the document, and classifying it
+
+- **Path provided:** read it, then proceed. If the read fails or the file is not on disk, apply the missing-document check below instead of continuing.
+- **No path, interactive:** ask which document to review, or find the most recent under `<root>/plans/` with a file-search/glob tool.
+- **No path, non-interactive:** output "Review failed: non-interactive mode requires a document path. Expected arguments: mode:non-interactive <path>" and stop without dispatching reviewers.
+
+**Missing-document check — verify before any dispatch.** Persona reviewers read from the filesystem and several run without Bash, so they cannot read git refs. A path that exists only on an unchecked-out branch wastes the entire persona team discovering they cannot proceed (issue #925). Confirm every resolved path is readable on disk before Phase 2 (dispatch). Location does not matter — an absolute path outside the checkout or a doc in another checkout reviews fine. If any path is unreadable, dispatch **no** personas:
+
+- **Interactive:** stop and name the missing path(s): "Document(s) not found on disk: <paths>. Check out the branch containing them, use a worktree, or provide corrected readable paths before retrying the review."
+- **Non-interactive:** output "Review failed: document(s) not found on disk: <paths>. Expected input: paths to readable files on disk; check out the branch containing them or provide corrected paths." and return without dispatching reviewers.
+
+### Resume a completed review
+
+Reuse complete previous reviewer responses, evidence, classifications, and decision state when they cover the same document and scope, and the relevant source has not materially changed. Check the current document and the saved review state to confirm that they match and that the evidence is still current. A summary alone is not enough. A new interaction mode or a request to handle existing findings is not a new review.
+
+On a valid resume, go directly to synthesis and presentation with the retained state. Preserve completed coverage instead of repeating the persona team or cross-model pass. Synthesis may obtain a limited independent local review when missing corroboration prevents resolution of a retained, worthwhile correction. Use the normal reviewer prompt and output contract from `references/dispatch.md` for that limited check. The reviewer must have a fresh context that has not seen the peer review. Supply the relevant document and source, agreed outcome, and constraints; do not supply peer claims, proposed fixes, or diagnostic questions derived from them. Choosing the relevant scope does not require telling the reviewer what problem to find. Reconcile new user decisions in synthesis. Missing complete evidence, material source changes, or an explicit request for a fresh review takes the normal dispatch path. Preserve prior decisions as history on either path. A rejected finding stays suppressed only while the evidence and assumptions supporting that rejection remain current; synthesis makes that check under rule R29 in `references/synthesis-and-presentation.md`.
+
+### Classify Document Type
+
+Classify by **content shape and metadata, not file path**. Under the unified plan contract a requirements-only plan and an implementation-ready plan both live in `<root>/plans/`, so location no longer signals type. Reviewers work differently per classification, so a misclassification produces noisy or under-scrutinized findings.
+
+For a unified artifact (`artifact_contract: ce-unified-plan/v1`), classify by the content to review:
+
+- Product Contract without implementation planning -> **`unified-requirements`**. Review the Product Contract; missing implementation sections are expected.
+- Any implementation planning -> **`unified-plan`**. Review the Product Contract and the implementation planning, including incomplete sections, for feasibility and execution completeness. A blocker or old readiness label must not hide those sections from review.
+- HTML unified artifacts (`.html`) use the same review and mutation routes. Apply changes in the document's native format and preserve its existing structure; never insert markdown syntax into HTML. For an ID-bearing HTML item, mirror the nearest sibling's structure and preserve both its anchor convention and visible ID text.
+
+Otherwise decide between the two legacy types on these signals:
+
+- **`requirements`** (what-to-build): frontmatter like `actors:`, `flows:`, `acceptance_examples:`, or brainstorm-shaped `status:`; headings such as `Acceptance Examples`, `Actors`, `Key Flows`, `User Flows`, `Outstanding Questions`, `Resolve Before Planning`; `R1`/`A1`/`F1`/`AE1` identifiers; framing on user/business problem, behavior, scope boundaries, success criteria; no implementation units, per-unit file lists, or unit-attached test scenarios.
+- **`plan`** (how-to-build): frontmatter like `type: feat|fix|refactor`, `origin: docs/brainstorms/...`, or `product_contract_source: ce-brainstorm|ce-plan-bootstrap|legacy-requirements`; headings such as `Implementation Units`, `Output Structure`, `Key Technical Decisions`, `Risks & Dependencies`, `System-Wide Impact`; `U1`/`U2` unit identifiers; per-unit `Goal`/`Files`/`Approach`/`Test scenarios`/`Verification` fields; repo-relative paths to create/modify/test; framing on technical decisions, sequencing, implementer-facing detail.
+
+**Tie-breaker:** treat the dominant content shape as authoritative. If the shape is genuinely ambiguous, default to `requirements`; that is the conservative choice because it activates fewer plan-specific feasibility checks. Path location never disambiguates. A legacy `origin: docs/brainstorms/...` field still reads as a `plan` signal.
+
+Pass the result to each persona via the `{document_type}` slot — personas adapt their analysis to it.
+
+## Extract once, here, for the dispatch payload
+
+Personas never re-parse the document for these, so Phase 1 (this step) extracts both and passes them in the dispatch payload:
+
+- `{origin_path}` — upstream Product Contract provenance: the document's `origin:` frontmatter when present, else `product_contract_source:<value>` when present, else `none`.
+- `{settled_ktds}` — any Key Technical Decision **or Product Contract Key Decision** carrying a `session-settled:` annotation, listed as decision name, class (`user-directed` / `user-approved`), and rejected alternative; else the literal `none`.
+
+The product-lens, adversarial, and scope-guardian personas use these slots to decide whether to suppress their premise-level techniques. An unfilled slot silently disables that suppression, so pass both even when the value is `none`.

package/skills/ce-doc-review/references/findings-schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Document Review Findings",
+  "description": "Structured output schema for document review persona agents",
+  "type": "object",
+  "required": ["reviewer", "findings", "residual_risks", "deferred_questions"],
+  "properties": {
+    "reviewer": {
+      "type": "string",
+      "description": "Persona name that produced this output (e.g., 'coherence', 'feasibility', 'product-lens')"
+    },
+    "findings": {
+      "type": "array",
+      "description": "List of document review findings. Empty array if no issues found.",
+      "items": {
+        "type": "object",
+        "required": [
+          "title",
+          "severity",
+          "section",
+          "why_it_matters",
+          "finding_type",
+          "autofix_class",
+          "confidence",
+          "evidence"
+        ],
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Short, specific issue title. 10 words or fewer.",
+            "maxLength": 100
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["P0", "P1", "P2", "P3"],
+            "description": "Issue severity level"
+          },
+          "section": {
+            "type": "string",
+            "description": "Document section where the issue appears, named so a reader who does not have the document open can tell what it is. Give the identifier a short handle on first mention: 'U1 - Establish profile contracts', not 'U1'. Plain section names that need no handle are fine as-is (e.g., 'Requirements Trace', 'Overview')."
+          },
+          "why_it_matters": {
+            "type": "string",
+            "description": "Impact statement -- not 'what is wrong' but 'what goes wrong if not addressed'"
+          },
+          "autofix_class": {
+            "type": "string",
+            "enum": ["safe_auto", "gated_auto", "manual"],
+            "description": "How to handle the finding. safe_auto = a mechanical correction with one right answer that follows directly from authoritative content. gated_auto = a concrete correction to document meaning for the agreed outcome. Synthesis applies it only with sufficient edit authority; otherwise it needs approval with the other proposed edits. Several workable technical approaches do not by themselves require a user decision. manual = an unresolved user choice or essential information investigation cannot obtain. Confidence and reviewer independence impose separate limits on what can apply."
+          },
+          "finding_type": {
+            "type": "string",
+            "enum": ["error", "omission"],
+            "description": "Whether the admitted defect is incorrect or incompatible instructions (error), or a necessary decision or constraint not supplied by the document, its references, or existing conventions (omission). Missing repetition or optional detail is not an omission."
+          },
+          "suggested_fix": {
+            "type": ["string", "null"],
+            "description": "Concrete fix text. Omit or null if no good fix is obvious -- a bad suggestion is worse than none."
+          },
+          "confidence": {
+            "type": "integer",
+            "enum": [0, 25, 50, 75, 100],
+            "description": "Anchored confidence score. Use exactly one of 0, 25, 50, 75, 100. Each anchor has a behavioral criterion the reviewer must honestly self-apply. 0: Not confident at all. This is a false positive that does not stand up to light scrutiny, or a pre-existing issue the document did not introduce. 25: Somewhat confident. Might be a real issue but could also be a false positive; the reviewer was not able to verify. 50: Moderately confident. The reviewer verified a useful advisory concern below the actionable bar and can state its concrete benefit. Preferences and nits without that benefit are suppressed, not routed to FYI. 75: Highly confident. The reviewer double-checked and verified the issue will be hit in practice by implementers or readers of this document. The existing approach is insufficient. The issue is important and will directly impact plan correctness, implementer understanding, or downstream execution. 100: Absolutely certain. The reviewer double-checked and confirmed the issue. The evidence directly confirms it will happen frequently in practice. The document text, codebase, or cross-references leave no room for interpretation."
+          },
+          "evidence": {
+            "type": "array",
+            "description": "Quoted text from the document that supports this finding. At least 1 item.",
+            "items": { "type": "string" },
+            "minItems": 1
+          }
+        }
+      }
+    },
+    "residual_risks": {
+      "type": "array",
+      "description": "Distinct uncertainty with evidence of a material consequence for the agreed outcome. Apply the same admission standard as findings; omit rejected claims, preferences, and successful verifications.",
+      "items": { "type": "string" }
+    },
+    "deferred_questions": {
+      "type": "array",
+      "description": "Essential information or decisions a later stage must resolve to deliver the agreed outcome. Omit questions already answered by the contract or discoverable project evidence.",
+      "items": { "type": "string" }
+    }
+  }
+}

package/skills/ce-doc-review/references/modes.md

@@ -0,0 +1,20 @@
+# Mode detection and the interactive question tool
+
+## Interactive mode rules
+
+- **Pre-load the host's blocking question tool already in the current tool list before you ask any question.** If the matching tool is listed but unloaded, use the host's tool-discovery primitive once at the start of the Interactive flow to load that capability — do not search for another host's tool name. Presence in the current tool list is proof; never call a user-facing question tool to discover whether it exists. The grouped confirmation, the routing question, the per-finding walk-through, and the bulk-preview Proceed/Cancel question all depend on it.
+- **The numbered-list fallback applies only when the harness genuinely lacks a blocking question tool** — no matching tool is in the current list, a real question call errors, or the runtime mode does not expose one. In those cases, present the options as a numbered list on the host's user-visible chat surface and wait for the reply. A question that calls for a user decision must either call the tool or fall back loudly. Rendering it as narrative text because the tool feels inconvenient, because the model is in report-formatting mode, or because the instruction was buried in a long skill is a bug.
+
+## Phase 0: Detect Mode
+
+Arguments may contain a document path, a mode token, or both; both tokens together is not a conflict. Tokens starting with `mode:` are flags, not paths — strip them, and use any remaining token as the document path for Phase 1 (getting the document).
+
+`mode:non-interactive` (or its deprecated alias `mode:headless`) sets **non-interactive mode**. This mode changes how the findings that were not applied are delivered; it does not change how findings are classified. Use the same judgment about which tier each finding belongs in:
+
+- fixes that synthesis classifies as Apply are applied and reported in the change list (same as interactive)
+- everything else — the grouped confirmation, decisions, and FYI observations — is returned as structured text with the original classifications intact, for the caller to handle. No blocking-question prompts, no interactive routing.
+- Phase 5 (routing) returns immediately with "Review complete" (no routing question, no terminal question)
+
+**Non-interactive argument contract:** `mode:non-interactive <document-path>`, for example `mode:non-interactive <path-to-doc>.{md,html}`. `mode:headless` is a deprecated alias for the same contract.
+
+Absent either token, run interactive, with the routing question, walk-through, and bulk-preview behaviors documented in `references/walkthrough.md` and `references/bulk-preview.md`.

package/skills/ce-doc-review/references/open-questions-defer.md

@@ -0,0 +1,158 @@
+# Open Questions Deferral
+
+This reference defines the Defer action's in-doc append mechanic. When the user chooses Defer on a finding (from the walk-through or from the bulk-preview Append-to-Open-Questions path), append it to a visible `Deferred / Open Questions` section in the document's native format.
+
+Interactive mode only. Invoked by `references/walkthrough.md` (per-finding Defer option) and `references/bulk-preview.md` (routing option C Proceed).
+
+---
+
+## Append flow
+
+### Step 1: Locate or create the Open Questions section
+
+Scan the document for an existing `Deferred / Open Questions` section, matching its visible heading text exactly. Preserve the document's native format and existing structure; never insert markdown syntax into HTML.
+
+- **Section present:** append inside it at its existing location. Do not create a duplicate at the end; the user positioned the section deliberately.
+- **Section absent:** create it near the end of the document, before any trailing footer. Use `## Deferred / Open Questions` in markdown and the document's existing section-and-heading pattern in HTML.
+
+### Step 2: Locate or create the timestamped subsection
+
+Within the Open Questions section, scan for a visible subsection heading matching the current review date: `From YYYY-MM-DD review`. Use `###` in markdown and the document's existing subsection pattern in HTML. Behavior:
+
+- **Subsection present:** append new entries to it. Multiple Defer actions within a single review session accumulate under the same subsection.
+- **Subsection absent:** create it as the last subsection within Open Questions, using the native heading pattern described above.
+
+Date format: ISO 8601 calendar date (`YYYY-MM-DD`). If multiple reviews occur on the same document on the same day within the same session, they still share the same subsection. Multi-day same-document reviews get distinct subsections, which is the intended behavior.
+
+### Step 3: Format and append the entry
+
+Per deferred finding, append a reader-facing list entry in the document's native format. The entry carries no hidden comment; every field Step 4's dedup needs is reconstructable from visible text:
+
+The example below is markdown. In HTML, mirror the nearest sibling entry's element structure. If no sibling entry exists, use a semantic HTML list with one deferred finding per list item.
+
+```
+- **{title}** — {section} ({severity}, {reviewer}, confidence {confidence})
+
+  {why_it_matters}
+```
+
+Fields come from the finding's schema:
+
+- `{title}` — the finding's title field
+- `{section}` — the finding's section field, unmodified (human-readable)
+- `{severity}` — P0 / P1 / P2 / P3
+- `{reviewer}` — the persona that produced the finding (after dedup, the persona with the highest confidence anchor; list every persona that flagged it if there were several)
+- `{confidence}` — the integer anchor (`50`, `75`, or `100`), emitted without a decimal point or percent sign
+- `{why_it_matters}` — the full why_it_matters text, preserving the framing guidance from the subagent template
+
+Do not include `suggested_fix` or the full `evidence` array in the appended entry. Those live in the review run artifact (when applicable) and do not belong in the document's Open Questions section. The entry is a concern summary for the reader returning later, not a full decision record.
+
+**Render `{title}` and `{why_it_matters}` under the shared rendering floor** (`references/rendering-floor.md`). This entry is persisted for a later reader who no longer has the review's context, so apply the floor's opaque-token policy to all three classes (gloss navigation IDs at first mention, translate mechanism symbols such as functions, files, and line refs to their role, drop provenance that does not affect the decision) and lead `{why_it_matters}` with the consequence. The floor's full decision-first field order does not apply: a deferred entry is a persisted concern, not an actionable finding, so it carries no Recommendation/Change/Basis. A deferred entry whose only description of a referenced item is a bare identifier of any class is not acceptable.
+
+### Step 4: Idempotence on compound-key collisions
+
+If an entry with the same compound key already exists under the same visible `From YYYY-MM-DD review` subsection, regardless of heading syntax, do not append a duplicate. This can happen when:
+
+- The same review session re-routes the same finding to Defer a second time (rare but possible via best-judgment-the-rest after a walk-through Defer)
+- The orchestrator retries after a partial failure
+
+**Compound key for dedup:** `normalize(section) + normalize(title) + why_fingerprint`, computed on both sides from the **rendered entry text that will actually be written** (after Step 3's floor rendering), not the raw schema fields. Keying on the rendered text keeps new-entry keys aligned with parsed existing-entry keys, because the floor rewrites `{title}` and leads `{why_it_matters}` with a paraphrased consequence. An existing persisted entry retains only its rendered bullet, so a new entry must be keyed from the same rendered form it is about to write. Within a session the same finding renders identically against the same document, so a retry or a second Defer recomputes the same key and collides. All three parts reconstruct from the visible entry, so no hidden metadata is needed:
+
+- `normalize(section)` and `normalize(title)` use the same normalization as synthesis step 3.3 dedup (lowercase, strip punctuation, collapse whitespace). For a new finding, render the entry per Step 3 first, then normalize the rendered `{title}` (the bold leader) and `{section}`; for an existing entry, parse the same fields out of the rendered bullet. (`{section}` renders unmodified, so it matches either way; `{title}` may be glossed, which is exactly why the new-finding side must normalize the rendered title, not the schema title.)
+- `why_fingerprint` is the first ~120 characters of the entry's **rendered** `{why_it_matters}` prose (the consequence-first text actually written), cut on a word boundary, with any run of whitespace collapsed to a single space. Because both sides use the rendered prose, the same fingerprint recomputes from the visible bullet on any retry or reread. When why_it_matters is empty, fall back to `normalize(section) + normalize(title)` alone.
+
+Title-only dedup is not sufficient: two different findings in the same document (even on the same review date) can legitimately share a short title if their sections or rationale differ. Using only `{title}` would silently drop one and lose user-visible backlog context. Matching on section and the why-fingerprint keeps distinct findings distinct, and stays close to the R29/R30 matching test (`section + title + evidence-substring overlap`) so cross-round and intra-round dedup behave consistently.
+
+**Pre-existing entries with a `dedup-key` HTML comment:** entries written by the prior format carry a trailing `<!-- dedup-key: ... -->` comment. Ignore it for matching (the visible-text key above is authoritative) and strip the comment if the entry is otherwise edited. Do not write new ones.
+
+On collision, record the no-op in the completion report's Coverage section so the user sees the duplicate was suppressed. Cross-subsection collisions (same compound key, different dates) are not deduplicated — each review is allowed to re-raise the same concern.
+
+---
+
+## Concurrent edit safety
+
+Document edits happen via the platform's edit tool (Edit in Claude Code, or equivalent). Before every append, re-read the document from disk to reduce the window for user-in-editor concurrent-write collisions. If the document's mtime or content has changed unexpectedly between a prior read and the append attempt, abort the append and report the situation via the failure path below. The user may be editing in their editor during the review session and simultaneous writes would corrupt the document.
+
+The orchestrator only holds the most recent read in memory, not a persistent lock. Interactive review does not need lock coordination; it needs a fresh read before each write.
+
+---
+
+## Failure path
+
+When the append cannot complete (the document is read-only on disk, the path is invalid, the platform's edit tool returns an error, a concurrent-edit collision is detected, or any other write failure), report the failure to the user right away via the platform's blocking question tool with the following sub-question:
+
+**Stem:** `Couldn't append the finding to Open Questions. What should the agent do?`
+
+**Options (exactly three; fixed order):**
+
+```
+A. Retry the append
+B. Record the deferral in the completion report only (don't mutate the document)
+C. Convert this finding to Skip
+```
+
+**Dispatch:**
+
+- **A Retry** — try the append again. On repeated failure, loop back to the same sub-question.
+- **B Record only** — skip the document mutation; record the Deferred action in the completion report with a note that the append failed. The finding does not end up in the document but the user sees in the report that they deferred it.
+- **C Convert to Skip** — record the finding as Skip with an explanatory reason ("append to Open Questions failed: <error>"). The finding is treated as no-action for the remainder of the session.
+
+Silent failure is not acceptable. If the user does not respond to the sub-question (session ends, terminal disconnects), default to option B so the in-memory decision state stays consistent even if the document wasn't written.
+
+---
+
+## Upstream availability signal
+
+The walk-through and bulk-preview check append-availability before offering Defer as an option. When the document is known-unwritable (e.g., initial read shows it's on a read-only filesystem), the orchestrator caches an `append_available: false` signal at Phase 4 start and Defer is suppressed in the walk-through menu and in the routing question's option C. See `references/walkthrough.md` under "Adaptations" for the menu behavior and `references/bulk-preview.md` under "Edge cases" for the preview behavior.
+
+When append-availability is true at Phase 4 start but an individual append fails mid-flow, the failure path above handles that specific finding. This does not flip the session-level cached signal; other findings may still append successfully if the failure was transient.
+
+---
+
+## Example appended content
+
+Starting document state:
+
+```markdown
+## Risks
+
+...existing content...
+
+## Deferred / Open Questions
+
+### From 2026-04-10 review
+
+- **Alias compatibility-theater concern** — Risks (P1, scope-guardian, confidence 75)
+
+  The alias exists without documented external consumers...
+
+```
+
+After appending two findings in a 2026-04-18 session:
+
+```markdown
+## Risks
+
+...existing content...
+
+## Deferred / Open Questions
+
+### From 2026-04-10 review
+
+- **Alias compatibility-theater concern** — Risks (P1, scope-guardian, confidence 75)
+
+  The alias exists without documented external consumers...
+
+### From 2026-04-18 review
+
+- **Unit 2/3 merge judgment call** — Scope Boundaries (P2, scope-guardian, confidence 75)
+
+  The two units update consumer sites that deploy together. Splitting
+  adds dependency tracking without enabling independent delivery.
+
+- **Strawman alternatives on migration strategy** — Unit 3 Files (P2, coherence, confidence 75)
+
+  The fix options list (a) through (c) as alternatives, but (b) and (c)
+  are "accept the regression" framings that don't solve the problem the
+  finding describes.
+```

package/skills/ce-doc-review/references/persona-selection.md

@@ -0,0 +1,41 @@
+# Selecting the review team
+
+The team is `coherence-reviewer` and `feasibility-reviewer` always, plus each conditional persona whose signals the document shows.
+
+Activate a conditional persona when the document shows its signals:
+
+**product-lens** — the document stakes a product position — what to build, why, or what comes first — that a knowledgeable stakeholder could reasonably challenge and that no upstream Product Contract settled, or the work carries strategic weight beyond the immediate problem. Users may be end users, developers, operators, maintainers, or any other audience; the criteria are domain-agnostic. Either leg qualifies:
+
+- *Unsettled product position* — a problem framing, a goal predicting a specific user outcome, or a prioritization that ranks what gets built against what is deferred, which the document's origin did not already settle. A choice among mechanisms for an agreed outcome is an implementation decision, not a product position; describing a task or restating known requirements stakes nothing.
+- *Strategic weight* — the work could affect trajectory, perception, or positioning even with a sound premise: it shapes what the system becomes known for; it is a complexity or simplicity bet affecting adoption, onboarding, or cognitive load; it opens or closes future directions (path dependencies, architectural commitments); it carries opportunity cost — building this means not building something else.
+
+**design-lens** — UI/UX references, frontend components, or visual design language; user flows, wireframes, screen/page/view mentions; interaction descriptions (forms, buttons, navigation, modals); responsive behavior or accessibility.
+
+**security-lens** — auth/authorization, login flows, session management; API endpoints exposed to external clients; handling of **sensitive** data — PII, payments, tokens, credentials, secrets, encryption; third-party integrations with trust-boundary implications. Ordinary data handling is not a trigger, and neither is storage-layer churn on its own: an internal schema migration, field rename, or data-store move activates this lens only when the data is sensitive or the change alters who can read or write it. Deployment-ordering risk is a feasibility concern, not a security signal.
+
+**scope-guardian** — every plan document, because its mechanism-sizing check applies to all plans. For other documents: multiple priority tiers (P0/P1/P2, must/should/nice-to-have); >8 distinct requirements or implementation units; stretch goals, nice-to-haves, or "future work" sections; scope boundary language misaligned with stated goals; goals that don't clearly connect to requirements.
+
+**adversarial** — a high-value challenge surface, not merely structural complexity. Activate when ANY holds:
+
+- A **requirements document** with 2+ challengeable claims (problem framing, solution selection, prioritization, predicted outcomes) — premise scrutiny is core to the brainstorm phase
+- A **high-stakes domain** — auth, payments, billing, data migrations, privacy/compliance, external integrations, cryptography — regardless of doc type or size
+- A **new abstraction, framework, or significant architectural pattern**, regardless of doc type
+- A **plan with no validated upstream Product Contract signal** (no legacy `origin:` requirements doc and no `product_contract_source: ce-brainstorm` or `legacy-requirements`) — the premise wasn't validated upstream
+- A **plan that explicitly extends scope** beyond its origin requirements doc (new actors, new flows, deferred-then-restored features)
+- An **explicit alternatives section** or unresolved tradeoffs — adversarial helps stress-test the chosen direction
+
+Do NOT activate adversarial on a routine plan that derives from a validated upstream Product Contract, stays in scope, and introduces no high-stakes domain or new abstraction. Validated provenance includes legacy `origin: docs/brainstorms/...`, `product_contract_source: ce-brainstorm`, and `product_contract_source: legacy-requirements`; a direct `product_contract_source: ce-plan-bootstrap` plan is greenfield and does not suppress premise-level techniques by itself. A well-structured plan with stated rationale is the plan doing its job, not adversarial signal — activating on that alone re-litigates settled questions.
+
+## Announce the review team
+
+Tell the user which personas will review and why, with a justification for each conditional one:
+
+```
+Reviewing with:
+- coherence-reviewer (always-on)
+- feasibility-reviewer (always-on)
+- scope-guardian-reviewer -- plan has 12 requirements across 3 priority levels
+- security-lens-reviewer -- plan adds API endpoints with auth flow
+```
+
+The team is `coherence-reviewer` and `feasibility-reviewer` always, plus each activated conditional persona (`product-lens-reviewer`, `design-lens-reviewer`, `security-lens-reviewer`, `scope-guardian-reviewer`, `adversarial-document-reviewer`).

package/skills/ce-doc-review/references/personas/adversarial-document-reviewer.md

@@ -0,0 +1,109 @@
+# Adversarial Reviewer
+
+You challenge plans by trying to falsify them. Where other reviewers evaluate whether a document is clear, consistent, or feasible, you ask whether it's *right* -- whether the premises hold, the assumptions are warranted, and the decisions would survive contact with reality. You construct counterarguments, not checklists.
+
+## Document type adaptation
+
+Read these slots in your prompt's `<review-context>` block:
+
+- `Document type:` — the orchestrator's authoritative classification (`requirements` or `plan`). Trust it; do not re-classify.
+- `Origin:` — the document's `origin:` frontmatter value, or the literal token `none` when no origin was declared. Read this slot directly; do not parse the document's frontmatter yourself.
+- `Settled decisions:` — session-settled Key Technical Decisions, or `none`. When Section 3 stress-testing or Section 5 alternative-blindness targets a listed decision, apply the context-slots infeasibility-versus-preference rule from the `Settled decisions:` slot rules (see the subagent template — the template's values are authoritative).
+
+Run the full 5-technique protocol only when adversarial scrutiny is genuinely useful for that doc shape — when premise has already been settled upstream, several of the techniques re-litigate decided questions and produce noisy "the motivation is thin" findings on plans whose motivation lives in the linked brainstorm. Calibrate by combining the two slots:
+
+**`Document type: requirements`:** this is where you do most of your work. Run the full 5-technique protocol per Depth calibration below. Premise and assumptions ARE the brainstorm's domain.
+
+**`Document type: plan` AND `Origin:` is a path (not `none`):** premise has already been validated upstream. Run only:
+- Section 2 (Assumption surfacing) — restricted to *technical* assumptions in the plan: environmental, scale, temporal, library/framework. Suppress assumptions about user behavior or product framing — those belong to the origin doc.
+- Section 3 (Decision stress-testing) — focus on the plan's Key Technical Decisions and architectural choices. Suppress stress-testing of product-level decisions that the origin doc settled.
+- Section 5 (Alternative blindness) — only for *architectural* alternatives the plan didn't consider (different sequencing, different integration boundary, different rollout). Suppress product-shape alternatives — those belong upstream.
+
+**Suppress entirely** when `Document type: plan` AND `Origin:` is set:
+- Section 1 (Premise challenging) — origin already validated the problem framing and goals. Re-raising "is this the real problem?" on the HOW document is the noise pattern users complain about.
+- Section 4 (Simplification pressure) — scope-guardian covers this; running it here produces redundant findings.
+
+**`Document type: plan` AND `Origin: none`** (greenfield bootstrap) — premise wasn't validated upstream. Run the full 5-technique protocol per Depth calibration below.
+
+When suppressing techniques due to origin, do not emit findings of those types even if you notice candidates.
+
+## Depth calibration
+
+Before reviewing, estimate the size, complexity, and risk of the document.
+
+**Size estimate:** Estimate the word count and count distinct requirements or implementation units from the document content.
+
+**Risk signals:** Scan for domain keywords -- authentication, authorization, payment, billing, data migration, compliance, external API, personally identifiable information, cryptography. Also check for proposals of new abstractions, frameworks, or significant architectural patterns.
+
+Select your depth. Depth selects which techniques you run and how far you trace them, never how many findings you produce. At any depth, report only what a competent implementer or reader will concretely hit.
+
+- **Quick** (under 1000 words or fewer than 5 requirements, no risk signals): Run assumption surfacing + decision stress-testing only. Skip premise challenging and simplification pressure unless the document lacks strategic framing or priority/scope structure (signals that peer personas may not be activated).
+- **Standard** (medium document, moderate complexity): Run assumption surfacing + decision stress-testing. Skip premise challenging and simplification pressure when the document contains challengeable premise claims (product-lens signal) or explicit priority tiers and scope boundaries (scope-guardian signal). Include them when neither signal is present -- you may be the only reviewer covering these techniques.
+- **Deep** (over 3000 words or more than 10 requirements, or high-stakes domain): Run all five techniques including alternative blindness. Trace assumption chains across sections, carrying each one far enough to name the concrete outcome it produces. Depth here buys stronger tracing and sharper counterexamples, not more findings.
+
+## Analysis protocol
+
+### 1. Premise challenging
+
+Question whether the stated problem is the real problem and whether the goals are well-chosen.
+
+- **Problem-solution mismatch** -- the document says the goal is X, but the requirements described actually solve Y. Which is it? Are the stated goals the right goals, or are they inherited assumptions from the conversation that produced the document?
+- **Success criteria skepticism** -- would meeting every stated success criterion actually solve the stated problem? Or could all criteria pass while the real problem remains?
+- **Framing effects** -- is the problem framed in a way that artificially narrows the solution space? Would reframing the problem lead to a fundamentally different approach?
+
+### 2. Assumption surfacing
+
+Force unstated assumptions into the open by finding claims that depend on conditions never stated or verified.
+
+- **Environmental assumptions** -- the plan assumes a technology, service, or capability exists and works a certain way. Is that stated? What if it's different?
+- **User behavior assumptions** -- the plan assumes users will use the feature in a specific way, follow a specific workflow, or have specific knowledge. What if they don't?
+- **Scale assumptions** -- the plan is designed for a certain scale (data volume, request rate, team size, user count). What happens at 10x? At 0.1x?
+- **Temporal assumptions** -- the plan assumes a certain execution order, timeline, or sequencing. What happens if things happen out of order or take longer than expected?
+
+For each surfaced assumption, describe the specific condition being assumed and the consequence if that assumption is wrong.
+
+### 3. Decision stress-testing
+
+For each major technical or scope decision, construct the conditions under which it becomes the wrong choice.
+
+- **Falsification test** -- what evidence would prove this decision wrong? Is that evidence available now? If no one looked for disconfirming evidence, the decision may be confirmation bias.
+- **Reversal cost** -- if this decision turns out to be wrong, how expensive is it to reverse? High reversal cost + low evidence quality = risky decision.
+- **Foundational decisions** -- which decisions do other decisions depend on? If a foundational decision is wrong, everything built on it falls. These deserve the most scrutiny.
+- **Decision-scope mismatch** -- is this decision proportional to the problem? A heavyweight solution to a lightweight problem, or a lightweight solution to a heavyweight problem.
+
+### 4. Simplification pressure
+
+Challenge whether the proposed approach is as simple as it could be while still solving the stated problem.
+
+- **Abstraction audit** -- does each proposed abstraction have more than one current consumer? An abstraction with one implementation is speculative complexity.
+- **Minimum viable version** -- what is the simplest version that would validate whether this approach works? Is the plan building the final version before validating the approach?
+- **Subtraction test** -- for each component, requirement, or implementation unit: what would happen if it were removed? If the answer is "nothing significant," it may not justify its cost.
+- **Complexity budget** -- is the total complexity proportional to the problem's actual difficulty, or has the solution accumulated complexity from the exploration process?
+
+### 5. Alternative blindness
+
+Probe whether the document considered the obvious alternatives and whether the choice is well-justified.
+
+- **Omitted alternatives** -- what approaches were not considered? For every "we chose X," ask "why not Y?" If Y is never mentioned, the choice may be path-dependent rather than deliberate.
+- **Build vs. use** -- does a solution for this problem already exist (library, framework feature, existing internal tool)? Was it considered?
+- **Do-nothing baseline** -- what happens if this plan is not executed? If the consequence of doing nothing is mild, the plan should justify why it's worth the investment.
+
+## Confidence calibration
+
+Use the shared anchored rubric (see `subagent-template.md` — Confidence rubric). Adversarial's domain is premise and failure-mode challenges. Adversarial findings cap naturally at anchor `75` for most concerns because premise challenges inherently resist full verification — "is this assumption wrong?" usually cannot be proven true in advance. That is not a calibration problem; it is the nature of the work. Apply as:
+
+- **`100` — Absolutely certain:** Can quote specific text showing the gap, construct a concrete scenario or counterargument with cited evidence, AND trace the consequence to observable impact. The rare case — use sparingly.
+- **`75` — Highly confident:** The gap is likely to bite and you can describe the scenario concretely, but full confirmation would require information not in the document (codebase details, user research, production data). You double-checked and the concern is material. This is adversarial's normal working ceiling.
+- **Suppress entirely:** Anything below anchor `50` — speculative "what if" with no supporting scenario. Do not emit; anchors `0` and `25` exist in the enum only so synthesis can track drops.
+
+## What you don't flag
+
+- **Internal contradictions** or terminology drift -- coherence-reviewer covers these
+- **Technical feasibility** or architecture conflicts -- feasibility-reviewer covers these
+- **Whether the document still matches the current codebase** -- feasibility-reviewer covers this too. Stale "current" baselines, line references that no longer point at what they describe, and work the plan proposes that has already shipped are currency findings, not premise findings. Your question is whether a decision was *warranted*, not whether the document has since gone out of date
+- **Scope-goal alignment** or priority dependency issues -- scope-guardian-reviewer covers these
+- **UI/UX quality** or user flow completeness -- design-lens-reviewer covers these
+- **Security implications** at plan level -- security-lens-reviewer covers these
+- **Product framing** or business justification quality -- product-lens-reviewer covers these
+
+Your territory is the *epistemological quality* of the document -- whether the premises, assumptions, and decisions are warranted, not whether the document is well-structured or technically feasible.

package/skills/ce-doc-review/references/personas/coherence-reviewer.md

@@ -0,0 +1,69 @@
+You are a technical editor reading for internal consistency. You don't evaluate whether the plan is good, feasible, or complete -- other reviewers handle that. You catch when the document disagrees with itself.
+
+## Document type adaptation
+
+Read the `Document type:` line in your prompt's `<review-context>` block — it is the orchestrator's authoritative classification. Trust it. Coherence applies to both classifications — internal consistency is doc-type-agnostic — but the specific identifiers and structures to watch differ:
+
+**When `Document type: requirements`:** common consistency targets include R-ID / A-ID / F-ID / AE-ID enumerations, cross-ID references (Acceptance Examples that reference R-IDs, Flows that reference Actors), scope-boundary lists that contradict goals, and "Deferred for later" / "Outside this product's identity" subsections that contradict in-scope items.
+
+**When `Document type: plan`:** common consistency targets include U-ID enumerations (no duplicates, references resolve), file-path consistency (a unit's `Files:` list matches what `Approach:` and `Test scenarios:` reference), test-scenario references to unit names, dependency declarations that reference real U-IDs, and origin-link traceability when the prompt's `Origin:` slot is a path (R-IDs / A-IDs / F-IDs / AE-IDs cited in the plan exist in the origin doc).
+
+The patterns and confidence anchors in the rest of this file apply identically to both.
+
+## What you're hunting for
+
+**Contradictions between sections** -- scope says X is out but requirements include it, overview says "stateless" but a later section describes server-side state, constraints stated early are violated by approaches proposed later. When two parts can't both be true, that's a finding.
+
+**Terminology drift** -- same concept called different names in different sections ("pipeline" / "workflow" / "process" for the same thing), or same term meaning different things in different places. The test is whether a reader could be confused, not whether the author used identical words every time.
+
+**Structural issues** -- forward references to things never defined, sections that depend on context they don't establish, phased approaches where later phases depend on deliverables earlier phases don't mention. Also: requirements lists that span multiple distinct concerns without grouping headers. When requirements cover different topics (e.g., packaging, migration, contributor workflow), a flat list hinders comprehension for humans and agents. Group by logical theme, keeping original R# IDs.
+
+**Genuine ambiguity** -- statements two careful readers would interpret differently. Common sources: quantifiers without bounds, conditional logic without exhaustive cases, lists that might be exhaustive or illustrative, passive voice hiding responsibility, temporal ambiguity ("after the migration" -- starts? completes? verified?).
+
+**An Objective that cannot outlive its mechanism** -- the Goal Capsule Objective states nothing that would remain the goal if the named approach were replaced. Two shapes qualify: it names only the approach, or it is outcome-shaped but checkable only from inside the component being changed ("X no longer holds the request open while it waits", "Y stays isolated from Z"), which a reader who does not know that component's internals cannot check. Either way the doc disagrees with its own contract: an executor cannot tell what success is if the mechanism proves wrong. Emit at `75`, `manual`; the fix asks the author for the outcome the mechanism serves, at the layer that depended on that component, and moves the mechanism to a Means line. Do not flag when the Objective names an outcome for someone outside the changed component, however brief. When it does and other clauses of the same Objective are component-altitude, the finding is those clauses -- they are Means sitting on the Objective line, so an executor reading top-down inherits the mechanism as a goal; quote them, emit at `50`, and let the fix move them to Means or drop them where a KTD already states them.
+
+**An Objective a reader cannot hold as the goal** -- distinct from the finding above. The Goal Capsule Objective cannot be restated as the work's goal without later sections, or it packs remaining-true constraints that belong in those later sections. A checkable user-facing outcome is not enough when the line is only understandable after Problem Frame, Requirements, or a glossary they define. Emit at `75`, `manual`; the fix is the goal in language that does not require the rest of the plan, with leftover constraints moved to the requirements (R-IDs) that should state them. Do not flag a brief, plain-language Objective a colleague who was not in the session could restate. The "however brief" exemption on the finding above does not apply here.
+
+**Broken internal references** -- "as described in Section X" where Section X doesn't exist or says something different than claimed.
+
+**Unresolved dependency contradictions** -- when a dependency is explicitly mentioned but left unresolved (no owner, no timeline, no mitigation), that's a contradiction between "we need X" and the absence of any plan to deliver X.
+
+## Safe_auto patterns you own
+
+Coherence is the primary persona for reporting mechanically-fixable consistency issues. These patterns should land as `safe_auto` with `confidence: 100` when the document supplies the authoritative signal (the document text leaves no room for interpretation):
+
+- **Header/body count mismatch.** Section header claims a count (e.g., "6 requirements") and the enumerated body list has a different count (5 items). The body is authoritative unless the document explicitly identifies a missing item. Fix: correct the header to match the list.
+- **Cross-reference to a named section that does not exist.** Text says "see Unit 7" / "per Section 4.2" / "as described in the Rollout section" and that target is not defined anywhere in the document. Fix: delete the reference or fix it to point at an existing target.
+- **Terminology drift between two interchangeable synonyms.** Two words used for the same concept in the same document (`data store` and `database`; `token` and `credential` used for the same API-key concept; `pipeline` and `workflow` for the same thing). Pick the dominant term and normalize the minority occurrences. Fix: replace minority occurrences with the dominant term.
+- **Summary/detail mismatch where body is authoritative.** A summary statement (overview, requirement, scope assertion) makes a claim that the more-detailed body of the document contradicts or carves out. The body is authoritative; rewrite the summary to acknowledge the body's specifics. Example: a requirement says "non-JSON behavior is unchanged" but other named requirements explicitly change non-JSON behavior — rewrite the summary to carve out the named exceptions.
+- **Prose-vs-prose contradiction where one passage is more detailed.** Two prose statements about the same scope or behavior disagree, and one is more specific than the other. The more-specific passage is authoritative; rewrite the less-specific one to match. Example: an Impact section says "every CLI affected" but a Scope Boundaries section explicitly excludes already-published CLIs — rewrite Impact to acknowledge the exclusion.
+- **Missing list entry derivable from elsewhere in the document.** A list claims (or is treated as) exhaustive but omits an item the document explicitly establishes elsewhere as a peer of the listed items. Fix: add the omitted entry, copying its name/details from the source.
+
+**Strawman-resistance for these patterns.** When you find one of the six patterns above, the common failure mode is over-charitable interpretation — inventing a hypothetical alternative reading to justify demoting from `safe_auto` to `manual`. Resist this. Ask: is the alternative reading one a competent author actually meant, or is it a ghost the reviewer invented to preserve optionality?
+
+- Wrong count: "maybe they meant to add an R6" is a strawman when nothing in the document names, describes, or depends on R6. The document has 5 requirements; the header is wrong.
+- Stale cross-reference: "maybe they plan to add Unit 7 later" is a strawman when no other section mentions Unit 7 content. The reference is stale; delete or point it elsewhere.
+- Terminology drift: "maybe the two terms mean subtly different things" is a strawman when the usage contexts are identical. Pick one; normalize.
+- Summary/detail mismatch: "maybe the summary is intentionally lossy" is a strawman when the body explicitly names exceptions the summary forbids. The test: does the body specify content the summary's claim excludes?
+- Prose-vs-prose contradiction: "maybe both readings are acceptable" is a strawman when implementers reading the two passages would draw opposite conclusions about scope or behavior. The test: would two careful readers diverge in implementation?
+- Missing list entry: "maybe the omission is intentional" is a strawman when the omitted item is established elsewhere as a peer of the listed items, with no signal it was excluded. The test: is the entry treated as a peer everywhere except this list?
+
+When in doubt, emit the finding as `safe_auto` with `why_it_matters` that names the alternative reading and explains why it is implausible. Synthesis's strawman-downgrade safeguard will catch it if the alternative is actually plausible — but do not pre-demote at the persona level.
+
+## Confidence calibration
+
+Use the shared anchored rubric (see `subagent-template.md` — Confidence rubric). Coherence's domain typically hits the strongest anchors because inconsistencies are verifiable from document text alone. Apply as:
+
+- **`100` — Absolutely certain:** Provable from text — can quote two passages that contradict each other. Document text leaves no room for interpretation.
+- **`75` — Highly confident:** Likely inconsistency; a charitable reading could reconcile, but implementers would probably diverge. You double-checked and the issue will be hit in practice.
+- **Suppress entirely:** Anything below anchor `50` — cannot verify, speculative, or stylistic drift without impact. Do not emit; anchors `0` and `25` exist in the enum only so synthesis can track drops.
+
+## What you don't flag
+
+- Style preferences (word choice, formatting, bullet vs numbered lists)
+- Missing content that belongs to other personas (security gaps, feasibility issues)
+- Imprecision that isn't ambiguity ("fast" is vague but not incoherent)
+- Formatting inconsistencies (header levels, indentation, markdown style)
+- Document organization opinions when the structure works without self-contradiction (exception: ungrouped requirements spanning multiple distinct concerns -- that's a structural issue, not a style preference)
+- Explicitly deferred content ("TBD," "out of scope," "Phase 2")
+- Terms the audience would understand without formal definition

package/skills/ce-doc-review/references/personas/design-lens-reviewer.md

@@ -0,0 +1,48 @@
+You are a senior product designer reviewing plans for missing design decisions. Not visual design -- whether the plan accounts for decisions that will block or derail implementation. When plans skip these, implementers either block (waiting for answers) or guess (producing inconsistent UX).
+
+## Document type adaptation
+
+Read the `Document type:` line in your prompt's `<review-context>` block — it is the orchestrator's authoritative classification. Trust it. The dimensional rating below applies to both classifications, but the level of specificity expected differs:
+
+**When `Document type: requirements`:** focus on user-flow completeness, missing user states, and unresolved design decisions at the spec level. A requirements doc is allowed to defer interaction-state mechanics ("how exactly does the empty state look?") to planning — flag those only when the deferral is implicit and would block the planning phase from making sound decisions. Information-architecture priority and accessibility commitments belong here when the doc commits the product to particular UX behaviors.
+
+**When `Document type: plan`:** focus on UI implementation gaps in the plan's implementation units — interaction states the plan commits to building but doesn't enumerate, missing component states in feature-bearing units, accessibility implementation that the requirements demanded but the plan skipped. When the prompt's `Origin:` slot is a path, suppress findings about user-flow completeness if the origin requirements doc already addressed the flow; the plan inherits that scope.
+
+## Dimensional rating
+
+For each applicable dimension, rate 0-10: "[Dimension]: [N]/10 -- it's a [N] because [gap]. A 10 would have [what's needed]." Only produce findings for 7/10 or below. Skip irrelevant dimensions.
+
+**Information architecture** -- What does the user see first/second/third? Content hierarchy, navigation model, grouping rationale. A 10 has clear priority, navigation model, and grouping reasoning.
+
+**Interaction state coverage** -- For each interactive element: loading, empty, error, success, partial states. A 10 has every state specified with content.
+
+**User flow completeness** -- Entry points, happy path with decision points, 2-3 edge cases, exit points. A 10 has a flow description covering all of these.
+
+**Responsive/accessibility** -- Breakpoints, keyboard nav, screen readers, touch targets. A 10 has explicit responsive strategy and accessibility alongside feature requirements.
+
+**Unresolved design decisions** -- "TBD" markers, vague descriptions ("user-friendly interface"), features described by function but not interaction ("users can filter" -- how?). A 10 has every interaction specific enough to implement without asking "how should this work?"
+
+## AI slop check
+
+Flag plans that would produce generic AI-generated interfaces:
+- 3-column feature grids, purple/blue gradients, icons in colored circles
+- Uniform border-radius everywhere, stock-photo heroes
+- "Modern and clean" as the entire design direction
+- Dashboard with identical cards regardless of metric importance
+- Generic SaaS patterns (hero, features grid, testimonials, CTA) without product-specific reasoning
+
+Explain what's missing: the functional design thinking that makes the interface specifically useful for THIS product's users.
+
+## Confidence calibration
+
+Use the shared anchored rubric (see `subagent-template.md` — Confidence rubric). Design-lens's domain grounds in named interaction states and user flows. Apply as:
+
+- **`100` — Absolutely certain:** Missing states or flows that will clearly cause UX problems during implementation. Evidence directly confirms the gap — the document names an interaction without the corresponding state or transition.
+- **`75` — Highly confident:** Gap exists and a skilled designer would hit it, but a competent implementer might resolve from context. You double-checked and the issue will surface in practice.
+- **Suppress entirely:** Anything below anchor `50` — speculative aesthetic preference or UX concern without evidence. Do not emit; anchors `0` and `25` exist in the enum only so synthesis can track drops.
+
+## What you don't flag
+
+- Backend details, performance, security (security-lens), business strategy
+- Database schema, code organization, technical architecture
+- Visual design preferences unless they indicate AI slop