cfsa-antigravity 1.0.0

package/template/.agent/workflows/resolve-ambiguity.md

@@ -0,0 +1,82 @@
+---
+description: Targeted ambiguity resolution for any pipeline document or layer
+pipeline:
+  position: utility
+  stage: quality-gate
+  predecessors: [] # callable from any stage
+  successors: [] # returns to caller
+  skills: [resolve-ambiguity]
+  calls-bootstrap: false
+---
+
+# Resolve Ambiguity
+
+Targeted ambiguity resolution for any pipeline document or layer. Uses the `resolve-ambiguity` skill to classify gaps and systematically resolve them.
+
+## Invocation patterns
+
+| Invocation | Behavior |
+|---|---|
+| `/resolve-ambiguity` | Interactive — asks which document or layer to resolve |
+| `/resolve-ambiguity vision` | Targets `docs/plans/vision.md` |
+| `/resolve-ambiguity architecture` | Targets the architecture design documents |
+| `/resolve-ambiguity @path/to/spec.md` | Targets a specific file |
+
+---
+
+## 1. Determine target
+
+If no argument was provided, ask the user which document or layer to resolve. Accept a layer name (`vision`, `architecture`, `ia`, `be`, `fe`) or a direct `@file` path.
+
+For layer names, resolve to the canonical document(s):
+- `vision` → `docs/plans/vision.md` + any `docs/plans/vision-appendix-*.md`
+- `architecture` → `docs/plans/YYYY-MM-DD-architecture-design.md` + `docs/plans/ENGINEERING-STANDARDS.md` + `docs/plans/data-placement-strategy.md`
+- `ia` → all files in `docs/plans/ia/` (excluding `index.md`)
+- `be` → all files in `docs/plans/be/` (excluding `index.md`)
+- `fe` → all files in `docs/plans/fe/` (excluding `index.md`)
+
+## 2. Load skill
+
+Read `.agent/skills/resolve-ambiguity/SKILL.md`. The skill contains the full methodology — this workflow orchestrates it.
+
+## 3. Load source document(s)
+
+Read the target document(s) in full based on the layer or file path determined in Step 1.
+
+## 4. Classify and resolve
+
+Apply the two-path classification model from the resolve-ambiguity skill:
+
+For each gap or ambiguity found, follow the skill's two-path classification:
+
+- **Technical/Factual gaps** → tiered lookup (Tiers 1–5): project docs, architecture files, upstream specs, official documentation, web search
+- **Intent/Choice gaps** → user clarification: present smart options ordered by recommendation, wait for user decision
+
+Resolve judgment calls first — they may change what mechanical fixes are needed.
+
+Present findings organized by type: judgment calls first, mechanical fixes second.
+
+## 5. Apply fixes
+
+Update the relevant spec documents with resolved content. Record each resolution so future readers don't hit the same ambiguity (per the skill's "Record" step).
+
+> **Resolution log**: After applying each fix, append a `## Resolution Log` entry to the target document:
+>
+> ```markdown
+> ## Resolution Log
+> | Date | Gap | Resolution | Source |
+> |------|-----|------------|--------|
+> | [date] | [gap description] | [what was changed] | [source that resolved it — project doc / user decision / upstream spec] |
+> ```
+>
+> If a `## Resolution Log` section already exists, append a new row to the table. This makes `/resolve-ambiguity` leave an audit trail so future readers know what was changed and why.
+
+> In addition to the Resolution Log, append a row to each modified spec's `## Changelog` table recording: today's date, `'Ambiguity resolution: [brief description]'`, `/resolve-ambiguity`, and the sections updated. If the spec does not yet have a `## Changelog` section, add one before appending.
+
+## 6. Propose next step
+
+Use `notify_user` to summarize what was resolved.
+
+### Proposed next step
+
+Ambiguity resolution complete. Next: Re-run `/audit-ambiguity [layer]` as a fresh invocation to verify the fixes. The session that fixed gaps cannot be the session that passes them.

package/template/.agent/workflows/sync-kit.md

@@ -0,0 +1,209 @@
+---
+description: Sync improvements from the upstream starter kit into this project's .agent folder — semantic merge preserving project-specific values
+---
+
+# Sync Kit
+
+Pull improvements from the upstream [Anti-MVP-Vibe-Pipeline](https://github.com/RepairYourTech/Anti-MVP-Vibe-Pipeline) kit into this project. The sync covers the **entire upstream repo** — `.agent/` directory, root-level files (`AGENTS.md`, `GEMINI.md`, `KIT-*.md`), and `docs/` scaffolding.
+
+**The problem:** The kit was born from this project, but has since evolved past it. The kit uses `{{PLACEHOLDER}}` markers; this project has real values. A blind copy would destroy project-specific content. This workflow does a semantic merge — apply the kit's *intent* while preserving project values.
+
+**Input:** Upstream kit repo (default: `RepairYourTech/Anti-MVP-Vibe-Pipeline`, branch `main`)
+**Output:** Updated project with kit improvements merged, sync state recorded
+
+---
+
+## 0. Read sync state
+
+Read `.agent/kit-sync.md` in the project root.
+
+- **File exists** → extract `last_synced_commit` and `upstream` values. Use **incremental mode** (Step 1a).
+- **File missing** → this is a **first sync**. Use **full diff mode** (Step 1b). The tracking file will be created in Step 9.
+
+---
+
+## 1. Identify what changed
+
+// turbo
+
+### 1a. Incremental sync (commit-scoped)
+
+Run `git log <last_synced_commit>..HEAD --name-only` on the upstream to get only the changed files. Work only with those files in Steps 2–7.
+
+If the command returns no files: report "No changes since last sync (commit `<hash>`)" and skip to Step 8.5.
+
+### 1b. First sync (full comparison)
+
+Compare the **entire upstream repo** against the project. Scan at minimum:
+
+| Upstream Path | What to Compare |
+|--------------|-----------------|
+| Root files | `AGENTS.md`, `GEMINI.md`, `KIT-ARCHITECTURE.md`, `KIT-README.md` |
+| `.agent/instructions/` | All 5 markdown files |
+| `.agent/rules/` | All 9 markdown files |
+| `.agent/workflows/` | All workflow files |
+| `.agent/skills/` | All skill directories (SKILL.md + sub-files) |
+| `.agent/skill-library/` | MANIFEST.md, README.md, subdirectories |
+| `.agent/progress/` | Directory structure |
+| `docs/` | README.md, audits/, plans/ scaffolding |
+
+Compare using SHA hashes or byte-level diff. Classify each file per Step 2.
+
+---
+
+## 2. Classify each changed file
+
+| Classification | Action | Example |
+|---------------|--------|---------|
+| **NET-NEW in kit** | Copy directly (Step 4) | New workflow, new skill directory |
+| **PROJECT-ONLY** | Leave alone — project-specific | `skills/surrealdb-expert/`, project workflows |
+| **BOTH EXIST — kit has `{{PLACEHOLDER}}`** | Semantic merge (Step 3) | `AGENTS.md`, `instructions/workflow.md` |
+| **BOTH EXIST — kit content changed** | Overwrite with upstream | Workflows with no project values |
+| **BOTH EXIST — identical** | Skip | — |
+
+**Key distinction for "BOTH EXIST":** If the project file has **no project-specific values** (just boilerplate), overwrite directly. If it has filled `{{PLACEHOLDER}}` values, semantic merge.
+
+---
+
+## 3. Semantic merge (files with project-specific values)
+
+For each file classified as "BOTH EXIST — kit has `{{PLACEHOLDER}}`":
+
+Read .agent/skills/technical-writer/SKILL.md and follow its methodology.
+
+### 3a. Read both versions side by side
+
+### 3b. Identify change regions
+- **Template regions** — lines with `{{PLACEHOLDER}}` in kit → project has real values. **PRESERVE project values.**
+- **Kit content regions** — pure boilerplate (no placeholders) that changed upstream. **APPLY kit changes.**
+
+### 3c. Apply changes surgically
+For each changed kit content region:
+1. Find the corresponding region in the project file
+2. Replace old boilerplate with new kit boilerplate
+3. **DO NOT touch any line with project-specific content**
+
+### 3d. Handle structural changes
+If the kit restructured content *around* a placeholder (e.g., rewrote the sentence containing `{{VALIDATION_COMMAND}}`):
+1. Take the kit's new structure
+2. Re-insert the project's specific value into the new structure
+3. Verify the result reads correctly
+
+---
+
+## 4. Copy net-new files
+
+// turbo
+
+For files that only exist in the kit, copy them into the **corresponding location** in the project:
+- Root files → project root
+- `.agent/workflows/` → project `.agent/workflows/`
+- `.agent/skills/<name>/` → copy entire skill directory (SKILL.md + references/, resources/, scripts/)
+- `docs/` → project `docs/`
+
+Only copy files identified as net-new in Step 1. Do not overwrite existing files.
+
+---
+
+## 5. Audit project-specific files for integration gaps
+
+Project-specific files were written **before** the kit's latest improvements. Check for missing integration points with new kit content.
+
+### 5a. Scan each project-only file
+
+| Question | Example |
+|----------|---------|
+| Does this file enforce rules that now have nuance? | Rule file bans placeholders — does it know about `// BOUNDARY:` stubs? |
+| Does this file describe processes that could use new skills? | Setup workflow → could `parallel-agents` parallelize verification? |
+| Does this file reference concepts the kit renamed or evolved? | Old terminology → now uses different naming |
+| Does this file's domain intersect new kit content? | Security rule → should it reference new kit security skills? |
+
+### 5b. Apply integration updates
+- Add cross-references to new rules/skills where relevant
+- Update terminology to match kit evolution
+- **DO NOT change project-specific values or domain logic** — only add integration surface
+
+---
+
+## 6. Update reference files
+
+Root files serve dual roles: they contain both **kit boilerplate** (pipeline table, rule tables) and **project-specific values** (project name, tech stack, validation command). After Steps 3–4, verify these reference files reflect the merged state:
+
+- **GEMINI.md** — pipeline workflow table, rule table, note about utility commands
+- **AGENTS.md** — pipeline workflow table, rule table, note about utility commands
+- **Any index files** that enumerate available skills, rules, or workflows
+
+Every new rule, skill, and workflow from this sync must appear in the tables.
+
+---
+
+## 7. Validate
+
+// turbo
+
+Run the project's configured validation command (see `.agent/instructions/commands.md`).
+
+If the validation command is not yet configured (unfilled `{{VALIDATION_COMMAND}}` placeholder): skip validation and flag it for remediation in Step 8.5.
+
+---
+
+## 8. Review diff
+
+Review the complete diff of changes made. Verify:
+- No `{{PLACEHOLDER}}` markers leaked into the project
+- No project-specific values were overwritten
+- All net-new files are present
+- All cross-references are valid
+- Project-specific files have integration points with new kit content (Step 5)
+
+---
+
+## 8.5. Scan for remaining unfilled placeholders
+
+Scan these files for any literal `{{` characters:
+
+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 unfilled patterns found** — list each with remediation:
+
+| File(s) | Remediation |
+|---------|-------------|
+| `structure.md` | Run `/create-prd-compile` Step 9.5 |
+| `patterns.md` | Run `/bootstrap-agents-provision` |
+| `AGENTS.md`, `GEMINI.md`, or others | Run `/bootstrap-agents-fill` |
+
+**If none found** — confirm "All instruction files fully configured."
+
+---
+
+## 9. Update sync state
+
+Write or update `.agent/kit-sync.md`:
+
+```markdown
+# Kit Sync State
+
+upstream: https://github.com/RepairYourTech/Anti-MVP-Vibe-Pipeline
+last_synced_commit: <current HEAD commit hash>
+last_synced_at: <ISO 8601 timestamp>
+kit_version: main
+```
+
+This file is committed to the project repo — it records which kit version the project is on and serves as the baseline for the next sync.
+
+---
+
+## Quick Reference
+
+| File Type | Content Action | Integration Action |
+|-----------|---------------|-------------------|
+| **Net-new from kit** | Copy directly | N/A |
+| **Both exist — no project values** | Overwrite with upstream | N/A |
+| **Both exist — has project values** | Semantic merge (Step 3) | N/A |
+| **Project-only** | **DO NOT overwrite** | **DO audit for integration gaps** (Step 5) |

package/template/.agent/workflows/update-architecture-map.md

@@ -0,0 +1,74 @@
+---
+description: Analyzes the codebase and generates or updates a living architecture document.
+pipeline:
+  position: 8.5
+  stage: verification
+  predecessors: [validate-phase]
+  successors: [plan-phase]
+  loop: true
+  skills: [architecture-mapping]
+  calls-bootstrap: false
+---
+
+# Update Architecture Map
+
+This workflow scans the current state of the repository and produces a "living" map of its architecture. It should be run periodically or at the end of a major phase to ensure `docs/ARCHITECTURE.md` accurately reflects the codebase.
+
+---
+
+**Prerequisite**: Verify that `/validate-phase` passed for the current phase before updating the architecture map. Read `docs/audits/phase-N-validation.md` (where N is the current phase number) and confirm the verdict is PASS. If the phase has not been validated or the verdict is FAIL → **STOP**: "Run `/validate-phase` for Phase N and ensure it passes before updating the architecture map."
+
+## 0. Load architecture mapping skill
+
+Read the skill before proceeding:
+1. `.agent/skills/architecture-mapping/SKILL.md` — Defines how to perform the mapping.
+
+---
+
+## 1. File Reconnaissance & Deep Reading
+
+Read .agent/skills/architecture-mapping/SKILL.md and follow its file reconnaissance methodology.
+
+Analyze the project structure using file exploration tools. Do not just stop at finding directories; you must read the source code.
+1. Identify core directories (`src/`, `lib/`, `api/`, etc.)
+2. Use `view_file` to read the exact contents of entry points (e.g., `src/api/worker.ts`, `src/pages/index.astro`).
+3. Locate and read configuration files (`package.json`, `astro.config.mjs`, `wrangler.toml`).
+
+## 2. Component & Schema Analysis
+
+Read .agent/skills/architecture-mapping/SKILL.md and follow its component analysis methodology.
+
+Group files logically into components, but extract their exact contracts:
+- Use `grep_search` to find `z.object` or `interface` definitions.
+- Document exact schema names, required environment variables, and binding names (e.g., KV namespaces, R2 buckets).
+
+## 3. Map Explicit Data Flow and Relationships
+
+Read .agent/skills/architecture-mapping/SKILL.md and follow its data flow mapping methodology.
+
+Trace exactly how data moves through the system.
+- Read database clients or query files to see exactly how state is managed (e.g., SurrealDB queries, Firebase Auth hooks).
+- Document exact API routes, rate limiting logic, and CORS constraints present in the code.
+
+## 4. Extract Key Patterns with Evidence
+
+Read .agent/skills/architecture-mapping/SKILL.md and follow its pattern extraction methodology.
+
+Identify recurring architectural patterns used in the codebase (e.g., CFPA, React Islands, utility-first CSS). 
+- Provide exact file paths that prove these patterns are in use (e.g., "React Islands are used in `src/components/Header.tsx` via the `client:load` directive").
+
+## 5. Write/Update Document
+
+Create or update `docs/ARCHITECTURE.md`.
+- If it doesn't exist, create it using the structure outlined in the `architecture-mapping` skill.
+- If it exists, integrate your new findings holistically. Do not just append to the end. Update the "Last Updated" timestamp.
+
+Ensure the document is human-readable, well-structured, and focuses on high-level system interactions rather than low-level functional documentation.
+
+## 6. Present Results and Next Steps
+
+Use `notify_user` to present a summary of the architecture map updates.
+
+### Proposed next steps
+
+"Architecture map updated. Next: Run `/plan-phase` for the next phase, or if all phases are complete, the project is ready for deployment — refer to your CI/CD pipeline configuration and the deployment procedures documented in `docs/plans/ENGINEERING-STANDARDS.md`."

package/template/.agent/workflows/validate-phase.md

@@ -0,0 +1,219 @@
+---
+description: Full validation of a completed phase — all tests, coverage thresholds, lint, type-check, build
+pipeline:
+  position: 8
+  stage: verification
+  predecessors: [implement-slice]
+  successors: [update-architecture-map]
+  loop: true # one validate per phase
+  skills: [testing-strategist, code-review-pro, deployment-procedures]
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Validate Phase
+
+Comprehensive validation of a completed implementation phase.
+
+---
+
+## 0. Load validation skills
+
+Read these skills before running checks:
+1. `.agent/skills/testing-strategist/SKILL.md` — Coverage strategy and test quality
+2. `.agent/skills/code-review-pro/SKILL.md` — Review checklist for self-audit
+3. `.agent/skills/deployment-procedures/SKILL.md` — Build and release readiness
+
+---
+
+## 0.5. Parallel dispatch option
+
+If the phase contains independent slices that don't share files, validation can run in parallel:
+
+1. **Identify independent slices** — slices that don't import from or export to each other
+2. **Dispatch parallel validation** — run Steps 1–5 concurrently for independent slices using the `parallel-agents` skill
+3. **Sequential for shared** — slices that share contracts or utilities must validate sequentially
+
+This is an optimization, not a requirement. Sequential validation is always correct.
+
+## 1. Run test suite
+
+Read .agent/skills/{{E2E_TESTING_SKILL}}/SKILL.md and follow its E2E test conventions.
+
+Run `{{TEST_COMMAND}}`.
+
+All tests must pass. Zero tolerance for failing tests.
+
+## 2. Check coverage
+
+Read .agent/skills/{{UNIT_TESTING_SKILL}}/SKILL.md and follow its test writing conventions.
+
+Run `{{TEST_COVERAGE_COMMAND}}`.
+
+Read `docs/plans/ENGINEERING-STANDARDS.md` and use the coverage thresholds defined in the "Test Coverage" section. If the file doesn't exist or thresholds aren't defined, fall back to these defaults:
+- Statements: 80%
+- Branches: 90% (critical paths: auth, payments, data mutations, permission checks), 75% (non-critical paths)
+- Functions: 80%
+- Lines: 80%
+
+Critical paths are defined as: auth flows, payment processing, data mutations, and permission/authorization checks.
+
+## 3. Lint
+
+Run `{{LINT_COMMAND}}`.
+
+Zero lint errors. Warnings should be reviewed and addressed.
+
+## 4. Type check
+
+Run `{{TYPE_CHECK_COMMAND}}`.
+
+Zero type errors. Strict mode must be enabled.
+
+## 5. Build
+
+Run `{{BUILD_COMMAND}}`.
+
+Build must succeed with no errors.
+
+---
+
+## 5.5. CI/CD pipeline verification
+
+Read .agent/skills/{{CI_CD_SKILL}}/SKILL.md and follow its pipeline configuration conventions.
+
+Verify the CI/CD pipeline is green for this phase's changes:
+
+1. Check that a CI/CD configuration file exists (e.g., `.github/workflows/`, `.gitlab-ci.yml`)
+2. Verify the pipeline has run for the latest commit in this phase
+3. Verify ALL CI/CD jobs are passing (not just the test job — include lint, type-check, build, and any deployment jobs)
+
+**If CI/CD is red** → red path: **STOP immediately.** Do not mark this phase as complete. List the failing jobs and their error output. Fix them and re-run `/validate-phase` after fixes.
+
+**Pass criteria**: CI/CD pipeline is green for the latest commit in this phase.
+
+---
+
+## 5.6. Staging deployment gate
+
+Read .agent/skills/{{HOSTING_SKILL}}/SKILL.md and follow its deployment conventions.
+
+1. Deploy to staging using the deployment skill (`.agent/skills/deployment-procedures/SKILL.md`)
+2. Verify deployment succeeded (no rollback triggered, no error logs in the deployment output)
+3. Run smoke tests against the staging environment:
+   - Health check endpoint returns 200
+   - At least one authenticated route works with a valid token
+   - At least one protected route returns 401/403 for unauthenticated requests
+4. **If smoke tests fail** → red path: Capture the failing test output, rollback the staging deployment, and fix the issue before re-running `/validate-phase`
+5. **If deployment fails** → red path: Do not mark this phase as complete — diagnose the deployment failure, fix it, and re-run `/validate-phase`
+
+**Pass criteria**: Staging deployment succeeds and all smoke tests pass.
+
+---
+
+## 5.7. Migration verification
+
+Read .agent/skills/{{ORM_SKILL}}/SKILL.md and follow its migration and schema conventions.
+
+1. Run the migration status command (e.g., `prisma migrate status`, `drizzle-kit status`, or equivalent for your ORM)
+2. Verify there are no pending migrations and no failed migrations
+3. Verify the CI/CD pipeline ran migrations successfully as part of this phase's deployment
+4. Check that rollback scripts exist for each migration in this phase
+5. If migrations are pending or failed → red path: do not mark this phase as complete — run the pending migrations, verify they succeed, and re-run `/validate-phase`
+
+**Pass criteria**: Migration status is clean. All migrations from this phase ran successfully in the CI/CD environment. Rollback scripts are present.
+
+---
+
+## 5.8. Spec coverage sweep
+
+This step verifies that the phase's implementation actually delivered what the specs required — not just that the tests pass.
+
+For each slice in the phase plan (`docs/plans/phases/phase-N.md`):
+
+1. Read the slice's acceptance criteria
+2. Identify the FE spec(s) referenced by this slice (via the FE spec's `## Source Map`)
+3. For each named user flow in the relevant FE spec `## Interaction Specification` section that belongs to this slice:
+   - Verify a test exists in the test suite that covers this flow by name or by its acceptance criterion
+   - Verify the flow is implemented (not stubbed with `BOUNDARY:`) unless a valid boundary stub exists with a tracking issue
+4. Identify the BE spec section(s) for each endpoint in this slice
+5. For each endpoint:
+   - Verify every Zod-validated field in the BE spec has a corresponding test
+   - Verify every error code defined in the BE spec has a corresponding test
+   - Verify every auth rule (role, ownership check) defined in the BE spec has a corresponding permission test
+6. For each slice in the phase plan, identify which IA shard(s) the slice's features originate from (using either the phase plan's domain references or the FE spec's `## Source Map`). For each identified IA shard:
+   - Read the shard's `## Accessibility` section (surface-conditional: apply only for `web`, `mobile`, or `desktop` surfaces). For each accessibility requirement named there, verify a corresponding test exists (e.g., axe-core check, keyboard navigation test, screen reader label test).
+   - Read the shard's acceptance criteria or testability section (look for Given/When/Then format or numbered acceptance criteria). For each Given/When/Then criterion, verify it maps to at least one named test in the test suite.
+   - Flag any IA criterion with no test coverage as an uncovered item — apply the **same hard-stop rule** below: list the uncovered criterion and either write the missing test or document it as a valid boundary stub with a tracking issue.
+
+**If any flow, field, error code, auth rule, IA acceptance criterion, or accessibility requirement has no corresponding test:**
+
+> ❌ STOP — Do not mark this phase as complete. List the uncovered items. Either write the missing tests and re-run `{{TEST_COMMAND}}`, or if the item was genuinely deferred (valid boundary stub + tracking issue), document the deferral explicitly in the phase validation report.
+
+**Pass criteria**: Every named user flow, BE endpoint field, error code, auth rule, IA acceptance criterion, and accessibility requirement in the phase's scope has a corresponding passing test or a documented valid boundary stub.
+
+> Update report (`docs/audits/phase-N-validation.md`): Add a `## Spec Coverage` section listing the sweep results — covered items, uncovered items, boundary stubs, accessibility coverage, IA testability trace results, and the pass/fail verdict for this step.
+
+---
+
+## 6. Accessibility audit (if UI changes)
+
+Read .agent/skills/accessibility/SKILL.md and follow its methodology.
+Audit all new UI components in this phase for WCAG 2.1 AA compliance.
+
+## 7. Performance check (if web surface exists)
+
+Check if the `web-performance-optimization` skill is installed (look for `.agent/skills/web-performance-optimization/SKILL.md`).
+
+**If installed**:
+1. Read `.agent/skills/web-performance-optimization/SKILL.md`
+2. Run the skill's audit protocol against the phase's changed pages/routes
+3. Compare results to the targets in `docs/plans/ENGINEERING-STANDARDS.md` (LCP, FID, CLS, bundle size)
+4. Report any metrics that exceed the defined thresholds
+
+**If not installed**:
+- Note: "No web performance skill installed. Skipping automated performance audit."
+- Manually verify that no obviously expensive operations were added (large synchronous imports, unoptimized images, missing lazy loading)
+- If performance is critical for this project, recommend installing the skill via `find-skills`
+
+## 8. Security review
+
+Read .agent/skills/security-scanning-security-hardening/SKILL.md and run its full defense-in-depth audit protocol against the phase's changes (new endpoints, new data flows, new auth checks). Report findings with severity levels. Block the phase if any Critical or High severity issues are found.
+
+**Supplemental security checks (conditional)**: After the core audit completes, check for stack-specific security skills. For each of the following that exists, read it and run its audit protocol as a supplement to the core audit:
+- `.agent/skills/owasp-web-security/SKILL.md`
+- `.agent/skills/api-security-checklist/SKILL.md`
+- `.agent/skills/crypto-patterns/SKILL.md`
+- `.agent/skills/csp-cors-headers/SKILL.md`
+- `.agent/skills/input-sanitization/SKILL.md`
+- `.agent/skills/dependency-auditing/SKILL.md`
+
+Report any additional findings from supplemental audits with the same severity classification.
+
+## 9. Document results
+
+**Note on report file**: `docs/audits/phase-N-validation.md` is written progressively. Step 5.8 creates the file and appends the `## Spec Coverage` section. Step 9 appends all remaining sections. Do not recreate or overwrite the file in Step 9 — append only.
+
+- Test results and coverage
+- Lint and type-check status
+- Build status
+- Accessibility findings
+- Performance findings
+- Security review findings
+- CI/CD pipeline status
+- Staging deployment result
+- Migration verification status
+- Pass/fail verdict
+
+## 10. Present results and next steps
+
+Read .agent/skills/verification-before-completion/SKILL.md and follow its methodology.
+
+Use `notify_user` to present the validation report.
+
+### Proposed next steps
+
+- **If all checks pass**: "Phase N validation complete. Next: Run `/update-architecture-map` to ensure the project's living architecture document is up-to-date."
+- **If any checks fail**: "Fix the failures listed in the validation report and re-run `/validate-phase` for Phase N."
+- **If new requirements were discovered during validation** (scope gaps, missing features, behavioral corrections): Use `/evolve-feature` to add them at the correct entry point layer. Do not attempt to add them directly to specs — evolution must go through the classify → cascade flow to maintain layer consistency.