cfsa-antigravity 1.0.0

package/template/.agent/workflows/propagate-decision-apply.md

@@ -0,0 +1,135 @@
+---
+description: Present each contradiction for approval, flag implicit assumptions for /resolve-ambiguity, run consistency check, and write propagation record
+parent: propagate-decision
+shard: apply
+standalone: true
+position: 2
+pipeline:
+  position: utility
+  stage: quality-gate
+  predecessors: [propagate-decision-scan]
+  successors: []
+  skills: [resolve-ambiguity, technical-writer]
+  calls-bootstrap: false
+---
+
+# Propagate Decision — Apply
+
+Review and apply fixes for explicit contradictions one at a time, flag implicit assumptions for `/resolve-ambiguity`, run a consistency check on changed documents, and write the propagation record.
+
+> **Prerequisite**: `docs/audits/propagation-scan-[date].md` must exist. Run `/propagate-decision-scan` first if no scan report is found.
+
+---
+
+## 1. Explicit contradictions (one at a time)
+
+Read .agent/skills/resolve-ambiguity/SKILL.md and follow its methodology.
+
+For each explicit contradiction from the scan report, display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Contradiction 1 of X
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Document: docs/plans/ia/03-payments.md
+Section:  Data Model
+Current:  PostgreSQL array types used for tag storage
+Locked:   MySQL (no native array type)
+Fix to:   Replace with JSON column type per MySQL conventions
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[Y] Apply fix and move to next
+[n] Skip this item
+[skip] Skip entire document
+[stop-and-save] Save progress and stop for later resumption
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+- **Y** — Apply the fix to the source document and move to the next contradiction
+- **n** — Skip this item (leave it unchanged, record as skipped)
+- **skip** — Skip all remaining contradictions in this document
+- **stop-and-save** — Save progress to the scan file (mark which items are done/skipped) and stop. The user can re-run `/propagate-decision-apply` later to resume from where they left off.
+
+> After applying a fix (`[Y]`) to a **spec document** (any file under `docs/plans/ia/`, `docs/plans/be/`, or `docs/plans/fe/`), append a row to that spec's `## Changelog` table recording: today's date, `'Decision propagation: [decision type] — [brief description of fix]'`, `/propagate-decision-apply`, and the section(s) updated. If the spec does not yet have a `## Changelog` section, add one before appending. Skip changelog updates for non-spec documents (e.g., architecture design, vision, engineering standards).
+
+---
+
+## 2. Implicit assumptions (one at a time)
+
+For each implicit assumption from the scan report, display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Assumption 1 of X
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Document: docs/plans/be/auth-spec.md
+Section:  Middleware
+Current:  "the auth provider"
+Issue:    Does not specify Supabase Auth — could be misinterpreted
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[Y] Flag for /resolve-ambiguity
+[n] Ignore (not ambiguous enough to matter)
+[skip] Skip entire document
+[stop-and-save] Save progress and stop for later resumption
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+- **Y** — Add the item to `docs/audits/propagation-ambiguity-[date].md` for later `/resolve-ambiguity` use
+- **n** — Ignore this item (record as ignored)
+- **skip** — Skip all remaining assumptions in this document
+- **stop-and-save** — Same behavior as Step 1
+
+---
+
+## 3. Consistency check on changed documents
+
+For every document that received at least one fix in Step 1:
+
+1. **Re-read the full document** — verify the fix was applied correctly
+2. **Check for remaining references to old values** — the fix may have changed one section but the same old value may appear elsewhere in the document
+3. **Check for internal contradictions introduced by fixes** — the fix may conflict with other content in the same document
+4. **Check cross-references between changed documents** — if two documents were both fixed, verify they are now consistent with each other
+
+Report any issues found. **Do not auto-fix** — present them to the user for review. If new contradictions were introduced, add them to the scan report for a subsequent apply pass.
+
+---
+
+## 4. Write propagation record
+
+Read .agent/skills/technical-writer/SKILL.md and follow its methodology.
+
+Write `docs/audits/propagation-[type]-[date].md` recording:
+
+- **Decision type** that was propagated
+- **Source document** containing the locked decision
+- **Documents scanned** (count and list)
+- **Explicit contradictions found** (count)
+- **Fixes applied** (count and list)
+- **Fixes skipped** (count and list with reasons)
+- **Implicit assumptions flagged** (count)
+- **Implicit assumptions ignored** (count)
+- **Consistency check results** (pass/fail with details)
+- **Timestamp** of the propagation run
+
+---
+
+## 5. Propose next steps
+
+Display the completion summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Propagation Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Fixed:   X contradictions across Y documents
+Flagged: X implicit assumptions for /resolve-ambiguity
+Skipped: X items
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Recommended next steps:
+1. Run `/resolve-ambiguity` to address the X flagged assumptions
+   (see docs/audits/propagation-ambiguity-[date].md)
+2. Run `/remediate-pipeline` to audit all layers with the corrected specs
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+If no assumptions were flagged, omit recommendation 1.

package/template/.agent/workflows/propagate-decision-scan.md

@@ -0,0 +1,147 @@
+---
+description: Pre-scan all 6 decision types, present selection menu, run full scan on selected types, and build impact report
+parent: propagate-decision
+shard: scan
+standalone: true
+position: 1
+pipeline:
+  position: utility
+  stage: quality-gate
+  predecessors: [] # callable standalone
+  successors: [propagate-decision-apply]
+  skills: [technical-writer]
+  calls-bootstrap: false
+---
+
+# Propagate Decision — Scan
+
+Pre-scan all 6 decision types for downstream contradictions, present a selection menu, run a full scan on the selected types, and write the impact report.
+
+> **Prerequisite**: At least one instruction file must be filled (not `{{PLACEHOLDER}}`). If all instruction files are still template placeholders, there are no locked decisions to propagate — run `/bootstrap-agents` first.
+
+---
+
+## 1. Pre-scan all decision types
+
+Read all six decision sources and do a quick surface scan of downstream documents:
+
+| Decision Type | Source Document | Downstream Scope |
+|--------------|-----------------|-------------------|
+| **structure** | `.agent/instructions/structure.md` | All IA shards, BE specs, FE specs |
+| **tech-stack** | `.agent/instructions/tech-stack.md` + architecture doc | All IA shards, BE specs, FE specs |
+| **auth-model** | Architecture doc (auth/security section) | All BE specs with middleware, all FE specs with auth flows |
+| **data-placement** | `docs/plans/data-placement-strategy.md` | All IA shards with data models, all BE specs with storage |
+| **patterns** | `.agent/instructions/patterns.md` | All IA shards, BE specs with implementation patterns, FE specs with component patterns |
+| **error-architecture** | Architecture doc `## Error Architecture` section — all 5 sub-sections (`### Global Error Envelope`, `### Error Propagation Chain`, `### Unhandled Exception Strategy`, `### Client Fallback Contract`, `### Error Boundary Strategy`) — located at `docs/plans/*-architecture-design.md` | All BE specs (`docs/plans/be/`) — error envelope conformance, propagation chain rules. All FE specs (`docs/plans/fe/`) — client fallback contract per surface, error boundary placement. |
+
+For each decision type:
+1. Read the source document to extract the current locked value
+2. Quick-scan downstream documents for any reference to that decision topic
+3. Note the count of downstream references found (matches + mismatches — the full scan in Step 3 will determine which are conflicts)
+
+---
+
+## 2. Present selection menu
+
+Show the pre-scan findings per decision type:
+
+```
+Decision propagation pre-scan:
+
+[1] structure — structure.md — inconsistencies detected in X documents
+[2] tech-stack — tech-stack.md — inconsistencies detected in X documents
+[3] auth-model — architecture doc — inconsistencies detected in X documents
+[4] data-placement — data-placement-strategy.md — inconsistencies detected in X documents
+[5] patterns — patterns.md — inconsistencies detected in X documents
+[6] error-architecture — architecture doc ## Error Architecture — inconsistencies detected in X documents
+
+[A] All with inconsistencies
+[Q] Quit — no propagation needed
+```
+
+If the user selects `[A]`, run the full scan (Step 3) on all 6 types first, then filter to only those with at least one explicit contradiction or implicit assumption.
+
+If called with a specific argument (e.g., `/propagate-decision structure`), skip the menu and proceed directly with that decision type.
+
+**Do not proceed until the user selects.**
+
+---
+
+## 3. Full scan on selected types
+
+For each selected decision type, scan every downstream document in the scope defined by the table in Step 1:
+
+1. **Read the locked value** from the source document
+2. **Search each downstream document** for references to the decision topic
+3. **For each reference found**, record the line number and classify it as one of:
+   - **Explicit contradiction** — The document states a value that directly conflicts with the locked decision (e.g., document says "PostgreSQL" but tech stack locks "MySQL")
+   - **Implicit assumption** — The document references the topic but uses vague or underspecified language that neither confirms nor contradicts the locked decision (e.g., says "the database" without naming it)
+   - **Consistent** — The document correctly uses the locked value
+
+Record all explicit contradictions and implicit assumptions with their document path, line number, current text, and the locked value they should reflect.
+
+### error-architecture scan
+
+**Source extraction:**
+- Locate `docs/plans/*-architecture-design.md` using the glob (not a hardcoded path).
+- Read the `## Error Architecture` section and extract the locked decisions from all five sub-sections, in particular the canonical field names from `### Global Error Envelope` (e.g., `code`, `message`, `details`, `request_id`).
+
+**BE spec conformance** — scan every file in `docs/plans/be/`:
+- Check whether the spec references the global error envelope by its locked name and uses the canonical field names exactly as locked in `### Global Error Envelope`.
+- Check whether the spec references the propagation chain rules — which layer catches, logs, and surfaces errors — as defined in `### Error Propagation Chain`.
+- Classify findings:
+  - **Explicit contradiction** — spec defines its own error shape with field names or structure that directly conflicts with the locked envelope.
+  - **Implicit assumption** — spec mentions "error handling" or "error response" without naming the canonical envelope shape or field names.
+  - **Consistent** — spec correctly names and uses the locked envelope.
+
+**FE spec conformance** — scan every file in `docs/plans/fe/`:
+- Check whether the spec references the client fallback contract appropriate for its surface type, as defined in `### Client Fallback Contract`.
+- Check whether the spec references error boundary placement per `### Error Boundary Strategy`.
+- Apply the same three-way classification (explicit contradiction / implicit assumption / consistent).
+
+All findings are recorded in the standard format (document path, line number, current text, locked value) for inclusion in the impact report built in Step 4.
+
+---
+
+## 4. Build and write impact report
+
+Read .agent/skills/technical-writer/SKILL.md and follow its methodology.
+
+Write `docs/audits/propagation-scan-[date].md` with:
+
+### Explicit Contradictions
+
+| Document | Line | Current Text | Locked Value | Decision Type |
+|----------|------|--------------|--------------|---------------|
+| `src/auth/tokens.ts` | 47 | `jwt.sign(payload, secret)` | Supabase Auth (no custom JWT) | auth-model |
+| ... | ... | ... | ... | ... |
+
+### Implicit Assumptions
+
+| Document | Line | Current Text | Concern | Decision Type |
+|----------|------|--------------|---------|---------------|
+| `docs/plans/be/auth-spec.md` | 23 | "the auth provider" | Does not name the locked auth provider | auth-model |
+| ... | ... | ... | ... | ... |
+
+### Summary
+
+- **Explicit contradictions**: X items across Y documents
+- **Implicit assumptions**: X items across Y documents
+- **Consistent references**: X items (no action needed)
+
+---
+
+## 5. Present summary and confirm
+
+Present the summary counts to the user:
+
+> **Propagation scan complete.**
+>
+> - **X explicit contradictions** found — these directly conflict with locked decisions and should be fixed
+> - **Y implicit assumptions** found — these are vague references that could be flagged for `/resolve-ambiguity`
+>
+> Review the full report at `docs/audits/propagation-scan-[date].md`.
+>
+> Run `/propagate-decision-apply` to review and apply fixes one at a time.
+
+**STOP — do not proceed to apply until the user explicitly confirms.**

package/template/.agent/workflows/propagate-decision.md

@@ -0,0 +1,56 @@
+---
+description: Scan downstream pipeline documents for inconsistencies with locked decisions and correct them one at a time
+pipeline:
+  position: utility
+  stage: quality-gate
+  predecessors: [] # callable from any stage
+  successors: [] # returns to caller
+  skills: [resolve-ambiguity, technical-writer]
+  calls-bootstrap: false
+shards: [propagate-decision-scan, propagate-decision-apply]
+---
+
+# Propagate Decision
+
+Scan downstream pipeline documents for contradictions with locked decisions, then apply fixes one at a time with user approval.
+
+**Usage**: `/propagate-decision` — you'll be shown a pre-scan of all 6 decision types and asked which to propagate.
+
+**Optional**: `/propagate-decision structure` — skip the menu and propagate a specific decision type directly.
+
+**When to use this**: After filling an instruction file placeholder or changing a locked architectural decision. Run **before** `/remediate-pipeline` — propagation fixes inconsistencies that would otherwise appear as ambiguity gaps during auditing.
+
+**When NOT to use this**: If you're adding genuinely new features or requirements — use `/evolve-feature` instead. This command corrects always-intended things; that command adds new things.
+
+**Key distinction from `/evolve-feature`**: `/propagate-decision` corrects downstream documents that should have always reflected a locked decision. `/evolve-feature` adds genuinely new scope that didn't exist before.
+
+---
+
+## Shard Overview
+
+| # | Shard | What It Does |
+|---|-------|--------------|
+| 1 | [`propagate-decision-scan`](.agent/workflows/propagate-decision-scan.md) | Pre-scans all 6 decision types, presents selection, runs full scan, writes impact report |
+| 2 | [`propagate-decision-apply`](.agent/workflows/propagate-decision-apply.md) | Presents each contradiction for approval, flags implicit assumptions, writes propagation record |
+
+---
+
+## Orchestration
+
+### Step A — Run `.agent/workflows/propagate-decision-scan.md`
+
+Pre-scans all 6 decision types, presents a selection menu to the user, runs a full scan on the selected types, builds an impact report with explicit contradictions and implicit assumptions, writes the report to `docs/audits/propagation-scan-[date].md`, and stops for user confirmation before proceeding.
+
+### Step B — Run `.agent/workflows/propagate-decision-apply.md`
+
+Presents each explicit contradiction one at a time with Y/n/skip/stop-and-save options, flags implicit assumptions for `/resolve-ambiguity`, runs a consistency check on changed documents, writes a propagation record, and proposes next steps.
+
+---
+
+## Key Principles
+
+- **Locked decisions are non-negotiable** — Downstream documents must reflect locked decisions. This workflow enforces that.
+- **One at a time** — Every fix is presented individually for user approval. No batch auto-fixes.
+- **Explicit vs implicit** — Explicit contradictions are direct conflicts that get fixed. Implicit assumptions are vague references that get flagged for `/resolve-ambiguity`.
+- **Consistency check after fixes** — Fixing one contradiction can introduce another. The consistency check catches cascading issues.
+- **Stop-and-save** — The user can pause at any time and resume later. Progress is persisted.

package/template/.agent/workflows/remediate-pipeline-assess.md

@@ -0,0 +1,138 @@
+---
+description: Scan pipeline state, identify layers with content, check existing audit reports, and build the remediation plan
+parent: remediate-pipeline
+shard: assess
+standalone: true
+position: 1
+pipeline:
+  position: utility
+  stage: quality-gate
+  predecessors: [] # callable standalone
+  successors: [remediate-pipeline-execute]
+  skills: [code-review-pro]
+  calls-bootstrap: false
+---
+
+# Remediate Pipeline — Assess
+
+Scan all five pipeline layers, check for existing audit reports, determine the starting layer, and present a remediation plan for user approval.
+
+> **Prerequisite**: At least one pipeline layer must have completed documents. If `docs/plans/vision.md` does not exist, tell the user to run `/ideate` first.
+
+---
+
+## 0. Pre-check: scan instruction files for unfilled placeholders
+
+Before assessing pipeline layers, scan all instruction files for any `{{` patterns:
+
+1. `AGENTS.md`
+2. `GEMINI.md`
+3. `.agent/instructions/workflow.md`
+4. `.agent/instructions/commands.md`
+5. `.agent/instructions/structure.md`
+6. `.agent/instructions/patterns.md`
+7. `.agent/instructions/tech-stack.md`
+
+**If any unfilled `{{PLACEHOLDER}}` patterns are found**:
+
+> **STOP** — do not proceed with pipeline remediation. Tell the user which files and placeholders are affected and provide remediation commands:
+>
+> | File(s) with unfilled placeholders | Remediation |
+> |------------------------------------|-------------|
+> | `structure.md` (`{{PROJECT_STRUCTURE}}`, `{{ARCHITECTURE_TABLE}}`) | Run `/create-prd-compile` Step 9.5 to generate and lock the directory structure |
+> | `patterns.md` (`{{FRAMEWORK_PATTERNS}}`) | Run `/bootstrap-agents-provision` after confirming the frontend framework |
+> | `AGENTS.md`, `GEMINI.md`, or other files | Run `/bootstrap-agents-fill` then `/bootstrap-agents-provision` with confirmed stack values |
+>
+> Pipeline remediation audits spec documents, but agents use instruction files throughout implementation — broken instruction files must be fixed first.
+>
+> Once all instruction files are clean, re-run `/remediate-pipeline` to audit the spec layers.
+
+**If all instruction files are clean**: Confirm "Instruction files are fully configured." and proceed to the additional checks below.
+
+**Check for unapplied propagation scan:**
+Look for `docs/audits/propagation-scan-*.md`. If any exist, check whether a corresponding `docs/audits/propagation-[type]-*.md` exists with a newer timestamp. If a scan exists without a completed apply record:
+
+> **STOP** — A decision propagation scan was run but not applied. Run `/propagate-decision-apply` to apply the pending fixes before pipeline remediation. Auditing specs that are inconsistent with locked decisions produces meaningless results.
+
+**Check for unapplied feature evolution:**
+Look for `docs/audits/evolve-feature-*.md`. If any exist, check whether the affected layers have been re-audited since the evolution was applied (compare timestamps of the evolution record against the layer audit reports). If layers were updated but not re-audited:
+
+> **Note** — A feature evolution was applied to [layers]. Run `/audit-ambiguity [layer]` to verify the new content meets the quality bar before pipeline remediation proceeds.
+
+If all checks pass, proceed to Step 1.
+
+---
+
+## 1. Scan pipeline layers
+
+Read .agent/skills/code-review-pro/SKILL.md and follow its systematic review methodology.
+
+Check which layers have content by verifying the presence of key files:
+
+| Layer | Key Files to Check | Has Content If… |
+|-------|-------------------|-------------------|
+| Vision | `docs/plans/vision.md` | File exists and is non-empty |
+| Architecture | `docs/plans/*-architecture-design.md` | At least one dated file exists |
+| IA | `docs/plans/ia/index.md` | File exists with ≥1 shard listed |
+| BE | `docs/plans/be/index.md` | File exists with ≥1 spec listed |
+| FE | `docs/plans/fe/index.md` | File exists with ≥1 spec listed |
+
+For each layer with content, also note:
+- How many documents it contains (shards/specs count)
+- Whether any deep dive files exist (IA layer only)
+
+---
+
+## 2. Check existing audit reports
+
+For each layer with content, check `docs/audits/[layer]-ambiguity-report.md` and `docs/audits/audit-scope.md`. Classify each layer using this decision tree:
+
+| Condition | Classification |
+|-----------|---------------|
+| No audit report exists | `needs-audit` |
+| Report exists, score > 0% | `needs-audit` |
+| Report exists, score = 0%, no `## Gaps Fixed` in `audit-scope.md` | `unverified-clean` |
+| Report exists, score = 0%, `## Gaps Fixed` exists but `fixed_by_session` is the current session | `unverified-clean` (same session cannot self-confirm) |
+| Report exists, score = 0%, `## Gaps Fixed` exists from a different session | `confirmed-clean` |
+| No content in layer | `no-content` |
+
+---
+
+## 3. Determine starting layer
+
+**If the user invoked with `@layer` argument**:
+1. Validate that all upstream layers are `confirmed-clean`. If any upstream layer is not confirmed clean, warn the user: "Layer [X] cannot be audited until upstream layers are clean. Starting from [upstream layer] instead."
+2. Start from the first dirty upstream layer, or the requested layer if all upstream layers are clean.
+
+**If no argument**: Start from the first layer (in Vision → Architecture → IA → BE → FE order) that is `needs-audit` or `unverified-clean`.
+
+**If all layers with content are `confirmed-clean`**: "All pipeline layers are already confirmed clean. No remediation needed." Propose the appropriate next pipeline step and exit.
+
+---
+
+## 4. Present remediation plan
+
+Use `notify_user` to present the following:
+
+> ## Pipeline Remediation Plan
+>
+> Layer | Documents | Status | Action
+> Vision | 1 doc | ✅ Confirmed clean | Skip
+> Architecture | 2 docs | ⚠️ Unverified clean | Re-audit to confirm
+> IA | 17 shards + 9 deep dives | 🔴 Needs audit | Audit + remediate
+> BE | 17 specs | 🔴 Needs audit | Audit + remediate
+> FE | — | ⬜ No content | Skip (not started)
+>
+> **Starting from**: IA
+>
+> This will audit the IA layer with adversarial probing, remediate any gaps found, then stop and ask you to confirm with a fresh audit before advancing to BE.
+
+"Does this plan look right? Confirm to proceed, or tell me which layer to start from."
+
+**Do NOT proceed** to Step 5 until the user explicitly confirms the remediation plan.
+
+---
+
+Read `.agent/skills/prd-templates/references/operational-templates.md` for the **Remediation State** template. Create or update `docs/audits/remediation-state.md` using the template, filling in layer statuses from Step 2 and the current layer from Step 3.
+
+After writing `remediation-state.md`, proceed to run `.agent/workflows/remediate-pipeline-execute.md`.

package/template/.agent/workflows/remediate-pipeline-execute.md

@@ -0,0 +1,135 @@
+---
+description: Execute adversarial audit, remediate gaps, enforce fresh-session confirmation, and advance layers
+parent: remediate-pipeline
+shard: execute
+standalone: true
+position: 2
+pipeline:
+  position: utility
+  stage: quality-gate
+  predecessors: [remediate-pipeline-assess]
+  successors: [] # returns to caller after stop
+  skills: [resolve-ambiguity, technical-writer, code-review-pro, pipeline-rubrics]
+  calls-bootstrap: false
+---
+
+# Remediate Pipeline — Execute
+
+Layer-by-layer audit → remediate → fresh-run instruction loop.
+
+> **Prerequisite**: Read `docs/audits/remediation-state.md` to determine the current layer and status. If this file does not exist, run `/remediate-pipeline-assess` first.
+
+---
+
+## 1. Read remediation state
+
+Read `docs/audits/remediation-state.md` to determine:
+- The current layer to process
+- The status of all layers
+- Any layers already confirmed clean this session
+
+---
+
+## 2. Re-invocation detection
+
+Read `docs/audits/audit-scope.md` and look for a `## Gaps Fixed` section.
+
+- **If absent** → This is a first-pass invocation. Proceed to Step 3.
+- **If present** → Read the `layer` and `fixed_by_session` fields.
+  - If `layer` matches the current layer AND `fixed_by_session` is different from the current session identifier → The user has run a fresh audit and it passed. Mark the current layer as confirmed clean in `remediation-state.md`. Advance to the next layer. If no more layers need auditing, go to Step 7. Otherwise, proceed to Step 3 for the next layer.
+  - If `layer` matches but `fixed_by_session` is the same session → **STOP**: "The session that fixed gaps cannot confirm them clean. Please run `/audit-ambiguity [layer]` as a fresh invocation, then re-run `/remediate-pipeline`."
+
+---
+
+## 3. Run adversarial audit inline
+
+Read .agent/skills/code-review-pro/SKILL.md and apply its adversarial review discipline to each layer.
+
+**CRITICAL**: Run the audit inline — do not invoke `/audit-ambiguity` as a sub-workflow.
+
+**CRITICAL ANTI-HALLUCINATION RULE**: Process one document at a time through 3a → 3b → 3c before moving to the next. Never batch-read and score from memory.
+
+### Layer-to-documents mapping
+
+Read `.agent/skills/pipeline-rubrics/references/scoring.md` for the document-to-layer mapping table. Load all documents for the current layer.
+
+### 3a. Implementer Simulation
+
+Attempt to write a stub implementation using only what's in the spec. List every decision not explicitly specified. Write each to `docs/audits/[layer]-ambiguity-report.md` as ❌. These gaps are unconditional.
+
+### 3b. Rubric Scoring with Two-Implementer Test
+
+Load the matching rubric from `.agent/skills/pipeline-rubrics/references/` (see SKILL.md for the file mapping). Score each dimension:
+
+- **✅** → "Two implementers would make the same decision because: [specific reason citing exact text]." If can't confidently say this, score ⚠️.
+- **⚠️** → Quote what exists + what's missing + what decision implementer must guess.
+- **❌** → List section headings checked, confirm absent.
+
+Write scores immediately to the report file.
+
+### 3c. Devil's Advocate Pass
+
+For each ✅: "What would a junior developer get wrong?" and "What would a malicious implementer exploit?" Downgrade to ⚠️ if either reveals a gap.
+
+---
+
+## 3.5. Cross-Layer Consistency
+
+Runs after all per-document scoring, when the layer is BE, FE, or scope is `all`. Read `.agent/skills/pipeline-rubrics/references/scoring.md` for the cross-layer consistency checks. Write all findings to a `## Cross-Layer Consistency` section in the report.
+
+---
+
+## 4. Zero-gap first-pass path
+
+Read .agent/skills/verification-before-completion/SKILL.md and follow its methodology.
+
+If 0% ambiguity on first pass — layer is "unverified clean." The fresh-run rule still applies. Add summary to report, persist `## Gaps Fixed` in `docs/audits/audit-scope.md`, proceed to Step 6.
+
+---
+
+## 5. Remediate gaps
+
+Read `.agent/skills/resolve-ambiguity/SKILL.md` for the resolution methodology.
+
+**Classify all gaps for the entire layer first, then present together:**
+
+- **Judgment calls** (Intent/Choice — product direction, UX preference, scope): Present ALL to user grouped by document. Wait for decisions.
+- **Mechanical fixes** (Technical/factual — resolvable via tiered lookup): Propose with citations. Apply after approval.
+
+### Resolution order
+
+1. Present all judgment calls. Wait for decisions.
+2. Apply approved mechanical fixes.
+3. Apply user-resolved judgment calls. Re-check if mechanical fixes changed.
+
+Add summary to report. If >70% of docs scored ❌ on majority of dimensions, recommend rewriting layer from scratch.
+
+### Persist fix metadata
+
+Append or replace `## Gaps Fixed` in `docs/audits/audit-scope.md` with: layer, fixed_at (ISO 8601), fixed_by_session (UUID), gaps_resolved (count), report_file path.
+
+---
+
+## 6. Instruct fresh-run confirmation
+
+Use `notify_user`:
+
+> ## [Layer] Remediated
+> [N] gaps fixed across [M] documents.
+> **Next**: Run `/audit-ambiguity [layer]` as a fresh invocation.
+> When it scores 0%, run `/remediate-pipeline` again to advance.
+> Do NOT re-run this workflow in this same session.
+
+**STOP** — Do not execute further steps in this invocation.
+
+---
+
+## 7. Advance or complete
+
+Runs when re-invoked after `/audit-ambiguity [layer]` confirmed the layer clean (detected in Step 2).
+
+### If more layers remain
+Update `remediation-state.md`: move current layer to confirmed-clean, set next layer as current. Use `notify_user` to instruct re-running `/remediate-pipeline`.
+
+### If all layers confirmed clean
+Present completion summary table (all layers ✅) and propose next pipeline step.

package/template/.agent/workflows/remediate-pipeline.md

@@ -0,0 +1,55 @@
+---
+description: Audit existing pipeline layers with adversarial probing, remediate gaps layer by layer, and advance to the next unstarted layer
+pipeline:
+  position: utility
+  stage: quality-gate
+  predecessors: [] # callable from any stage
+  successors: [] # returns to caller
+  skills: [resolve-ambiguity, code-review-pro, technical-writer]
+  calls-bootstrap: false
+shards: [remediate-pipeline-assess, remediate-pipeline-execute]
+---
+
+# Remediate Pipeline
+
+Walk existing pipeline output layer by layer — audit with adversarial probing, remediate gaps, enforce the fresh-run rule, and advance only when each layer is genuinely clean.
+
+**Usage**: `/remediate-pipeline` — you'll be shown the current pipeline state and asked which layer to start from.
+
+**Optional**: `/remediate-pipeline @layer` — start at a specific layer (e.g., `/remediate-pipeline ia`). All upstream layers must be confirmed clean first.
+
+**When to use this**: When you have existing specs produced by a previous pipeline run (possibly with broken tooling, shallow rubrics, or self-grading bias) and need to bring them up to the current quality standard before continuing.
+
+**When NOT to use this**: If you're starting fresh — use `/ideate` instead. If you know exactly which layer is dirty — use `/audit-ambiguity [layer]` directly.
+
+---
+
+## Shard Overview
+
+| # | Shard | What It Does |
+|---|-------|--------------|
+| 1 | [`remediate-pipeline-assess`](.agent/workflows/remediate-pipeline-assess.md) | Scans pipeline state, identifies layers with content, checks existing audit reports, builds remediation plan |
+| 2 | [`remediate-pipeline-execute`](.agent/workflows/remediate-pipeline-execute.md) | Layer-by-layer audit → remediate → fresh-run instruction loop |
+
+---
+
+## Orchestration
+
+### Step A — Run `.agent/workflows/remediate-pipeline-assess.md`
+
+Scans all pipeline layers for existing content, checks `docs/audits/` for prior audit reports, classifies each layer (confirmed-clean / unverified-clean / needs-audit / no-content), determines the starting layer, presents the remediation plan to the user for approval, and writes `docs/audits/remediation-state.md`.
+
+### Step B — Run `.agent/workflows/remediate-pipeline-execute.md`
+
+Executes the remediation loop for the current layer: runs the full adversarial audit inline, classifies and remediates all gaps, persists re-verification metadata, and instructs the user to run `/audit-ambiguity [layer]` as a fresh invocation before advancing. On re-invocation, detects the confirmed-clean state and advances to the next layer automatically.
+
+---
+
+## Key Principles
+
+- **Audit before fix** — Never fix what you haven't measured. The audit score is the baseline.
+- **Layer order is mandatory** — Vision → Architecture → IA → BE → FE. Upstream gaps corrupt downstream specs. Never audit a downstream layer before its upstream is confirmed clean.
+- **Fresh-run rule is absolute** — The session that fixes gaps cannot confirm them clean. After remediation, the user must run `/audit-ambiguity [layer]` as a new invocation. This workflow stops after remediation and resumes on re-invocation.
+- **Judgment calls block advancement** — A layer cannot advance until all judgment-call gaps are resolved by the user. Mechanical fixes can be applied automatically with user approval.
+- **Stop at the first dirty layer** — Do not audit FE if BE has unresolved gaps. Fix upstream first.
+- **Don't delete, fix forward** — The goal is to bring existing work up to standard, not to discard it. Only recommend a full layer restart if >70% of its documents score ❌ on the majority of rubric dimensions.