@ancleto/spec 0.6.5 → 0.6.7

package/skills/ancleto-upgrade/references/templates.md

@@ -1,66 +1,63 @@
-# Templates — Artefactos aspec
+# Templates — aspec artifacts
 
-Este archivo contiene los templates exactos para los cuatro artefactos que genera
-el skill. Leer este archivo en el Paso 6 y completar cada placeholder `{...}`.
+Exact templates for the four generated artifacts; fill each `{...}` placeholder.
 
 ---
 
 ## proposal.md
 
 ```markdown
-# Propuesta: Migración a {LIBRARY} v{TARGET_VERSION}
+# Proposal: Migration to {LIBRARY} v{TARGET_VERSION}
 
-## Contexto
+## Context
 
-{Descripción del estado actual: versión actual de LIBRARY instalada, razón para migrar
-(EOL, mejoras de performance, compatibilidad, nuevas features). Si se obtuvo documentación
-oficial, resumir los puntos más relevantes del changelog aquí.}
+{Installed version + migration reason (EOL, perf, compatibility, features); key changelog
+points if docs exist.}
 
-## Cobertura del análisis
+## Analysis coverage
 
-- source files analizados: {source_files_scanned}
-- test files analizados: {test_files_scanned}
-- config files analizados: {config_files_scanned}
-- archivos con matches: {files_with_matches}
-- archivos sin matches: {files_without_matches}
+- source files analyzed: {source_files_scanned}
+- test files analyzed: {test_files_scanned}
+- config files analyzed: {config_files_scanned}
+- files with matches: {files_with_matches}
+- files without matches: {files_without_matches}
 
-## Alcance del cambio
+## Change scope
 
-### Dependencias afectadas — {N} paquetes en {M} package.json
+### Affected dependencies — {N} packages in {M} package.json
 
-| package.json | Paquete | Versión actual | Versión objetivo |
-| ------------ | ------- | -------------- | ---------------- |
+| package.json | Package | Current version | Target version |
+| ------------ | ------- | --------------- | -------------- |
 
-{Una fila por cada entry en DEPENDENCY_CHANGES[]}
+{One row per DEPENDENCY_CHANGES[]}
 
-### Archivos de configuración a modificar — {N} archivos
+### Config files to modify — {N} files
 
-{Lista de archivos con descripción del cambio requerido. Si no hay, escribir "Ninguno."}
+{Change per file; if none: "None."}
 
-### Código fuente con breaking changes — {N} archivos
+### Source code with breaking changes — {N} files
 
-{Lista de archivos afectados con el breaking change detectado. Si no hay, escribir "Ninguno."}
+{Affected files + breaking change; if none: "None."}
 
-### Tests con breaking changes — {N} archivos
+### Tests with breaking changes — {N} files
 
-{Lista de archivos de test afectados. Si no hay, escribir "Ninguno."}
+{Affected test files; if none: "None."}
 
-## Evaluación de breaking changes
+## Breaking-change assessment
 
-{Para cada KNOWN_BREAK relevante a la migración:}
+- ✅ AFFECTED — {id}: {description} — {N} occurrences in {M} files
+- ✓ NOT AFFECTED — {id}: {description}
 
-- ✅ AFECTA — {id}: {description} — {N} ocurrencias en {M} archivos
-- ✓ NO AFECTA — {id}: {description}
+{Per relevant KNOWN_BREAK}
 
-## Matches de baja confianza
+## Low-confidence matches
 
-{Lista de UNSURE_MATCHES[] para revisión manual. Si no hay, escribir "Ninguno."}
+{UNSURE_MATCHES[]; if none: "None."}
 
-## Decisión
+## Decision
 
-Migrar {LIBRARY} {CURRENT_VERSION} → v{TARGET_VERSION}.
-
-Fuente de información: {DOCS_URL | "Búsqueda web: {query}" | "Knowledge base interna"}
+Migrate {LIBRARY} {CURRENT_VERSION} → v{TARGET_VERSION}.
+Source: {DOCS_URL | "Web search: {query}" | "Internal knowledge base"}
 ```
 
 ---
@@ -68,55 +65,54 @@ Fuente de información: {DOCS_URL | "Búsqueda web: {query}" | "Knowledge base i
 ## specs/{LIBRARY_SLUG}{TARGET_VERSION}.md
 
 ```markdown
-# Especificaciones: {LIBRARY} v{TARGET_VERSION} Migration
+# Specs: {LIBRARY} v{TARGET_VERSION} Migration
+
+## ADDED Requirements
 
-## Dependencias
+### Requirement: Dependencies
 
-{Para cada entry en DEPENDENCY_CHANGES[]:}
+- REQ-D-{N}: The system SHALL use `{package_name}` at version `^{TARGET_VERSION}.0.0` in `{path}`
 
-- REQ-D-{N}: `{package_name}` en `{path}` SHALL usar versión `^{TARGET_VERSION}.0.0`
+{Per DEPENDENCY_CHANGES[]}
 
-## Configuración
+#### Scenario: dependencies installed
 
-{Para cada entry en CONFIG_CHANGES[]:}
+- **WHEN** dependencies are installed for the affected package
+- **THEN** `{package_name}` resolves to `^{TARGET_VERSION}.0.0`
 
-- REQ-C-{N}: `{file}` SHALL {descripción del cambio requerido}
+### Requirement: Configuration
 
-{Si CONFIG_CHANGES está vacío:}
-No se requieren cambios de configuración.
+- REQ-C-{N}: The system SHALL {required change} in `{file}`
 
-## Código fuente
+{Per CONFIG_CHANGES[]; empty → "No configuration requirements."}
 
-{Para cada entry en BREAKING_CHANGES_IN_CODE[]:}
+### Requirement: Source code
 
-- REQ-S-{N} [{break_id}]: {descripción del cambio requerido en el código}
-  Evidencia: `{file}:{line_number}` ({confidence})
+- REQ-S-{N} [{break_id}]: The system SHALL {required code change}
+  Evidence: `{file}:{line_number}` ({confidence})
 
-{Si BREAKING_CHANGES_IN_CODE está vacío:}
-No se detectaron breaking changes en código fuente.
+{Per BREAKING_CHANGES_IN_CODE[]; empty → "No source-code requirements."}
 
-## Tests
+### Requirement: Tests
 
-{Para cada entry en BREAKING_CHANGES_IN_TESTS[]:}
+- REQ-T-{N} [{break_id}]: The system SHALL {required test change}
+  Evidence: `{file}:{line_number}` ({confidence})
 
-- REQ-T-{N} [{break_id}]: {descripción del cambio requerido en los tests}
-  Evidencia: `{file}:{line_number}` ({confidence})
+{Per BREAKING_CHANGES_IN_TESTS[]; empty → "No test requirements."}
 
-{Si BREAKING_CHANGES_IN_TESTS está vacío:}
-No se detectaron breaking changes en tests.
+### Requirement: Verification
 
-## Verificación
+- REQ-V-001: The project SHALL compile without TypeScript errors
+- REQ-V-002: The project SHALL pass all tests after the migration
+- REQ-V-003: The project SHALL pass lint without errors
 
-- REQ-V-001: El proyecto SHALL compilar sin errores TypeScript
-- REQ-V-002: Todos los tests SHALL pasar luego de la migración
-  {Si lint script existe:}
-- REQ-V-003: El proyecto SHALL pasar lint sin errores
+{REQ-V-003 only if the lint script exists}
 
-## Cobertura
+### Requirement: Analysis coverage
 
-- REQ-X-001: El análisis SHALL incluir todo archivo de código fuente elegible (`.ts`, `.tsx`, `.js`) excluyendo `node_modules`, `dist` y artefactos generados
-- REQ-X-002: El análisis SHALL incluir todo archivo de tests elegible (`*.spec.*`, `*.test.*`)
-- REQ-X-003: El resultado SHALL reportar métricas de cobertura (`source_files_scanned`, `test_files_scanned`, `config_files_scanned`)
+- REQ-X-001: The analysis SHALL include every eligible source file (`.ts`, `.tsx`, `.js`), excluding `node_modules`, `dist` and generated artifacts
+- REQ-X-002: The analysis SHALL include every eligible test file (`*.spec.*`, `*.test.*`)
+- REQ-X-003: The result SHALL report coverage metrics (`source_files_scanned`, `test_files_scanned`, `config_files_scanned`)
 ```
 
 ---
@@ -126,132 +122,111 @@ No se detectaron breaking changes en tests.
 ````markdown
 # Tasks: {LIBRARY} v{TARGET_VERSION} Migration
 
-## Fase 1: Dependencias
+## Phase 1: Dependencies
 
-{Para cada entry en DEPENDENCY_CHANGES[]:}
+- [ ] **T-D-{N}** Update `{package_name}` in `{path}` from `{current_version}` to `^{TARGET_VERSION}.0.0`
 
-- [ ] **T-D-{N}** Actualizar `{package_name}` en `{path}` de `{current_version}` a `^{TARGET_VERSION}.0.0`
+{Per DEPENDENCY_CHANGES[]}
 
-- [ ] **T-D-LAST** Regenerar lockfile:
+- [ ] **T-D-LAST** Regenerate the lockfile:
   ```bash
   npm install
   ```
 ````
 
-## Fase 2: Infraestructura y runtime
-
-{Solo si IS_RUNTIME = true:}
-{Si .nvmrc existe o debe crearse:}
-
-- [ ] **T-I-001** {Crear | Actualizar} `.nvmrc` con el valor `{TARGET_VERSION}`
+## Phase 2: Infrastructure and runtime
 
-{Para cada CI file con nodeVersion a cambiar:}
+{Only if IS_RUNTIME = true; one T-I task per file found}
 
-- [ ] **T-I-002** Actualizar `nodeVersion` en `{CI_FILE}` de `{current}` a `{TARGET_VERSION}.x`
+- [ ] **T-I-001** {Create | Update} `.nvmrc` with value `{TARGET_VERSION}`
 
-{Para cada Dockerfile con FROM node:X:}
+- [ ] **T-I-002** Update `nodeVersion` in `{CI_FILE}` from `{current}` to `{TARGET_VERSION}.x`
 
-- [ ] **T-I-003** Actualizar imagen base en `{Dockerfile}`:
+- [ ] **T-I-003** Update the base image in `{Dockerfile}`:
   ```dockerfile
-  # Antes
+  # Before
   FROM node:{current}-alpine
-  # Después
+  # After
   FROM node:{TARGET_VERSION}-alpine
   ```
-  _(Ajustar variant según el Dockerfile existente: alpine, slim, bullseye, etc.)_
+  _(Match the existing variant: alpine, slim, bullseye, etc.)_
 
-{Para cada appSettings.json con "Runtime":}
+- [ ] **T-I-004** Update `Runtime` in `{appSettings.json}` to `NODEJS_{TARGET_VERSION}_X`
 
-- [ ] **T-I-004** Actualizar `Runtime` en `{appSettings.json}` a `NODEJS_{TARGET_VERSION}_X`
+{If IS_RUNTIME = false:}
+_(Not applicable to library migrations)_
 
-{Si IS*RUNTIME = false:}
-*(No aplica para migraciones de librería)\_
+## Phase 3: Build and test configuration
 
-## Fase 3: Configuración de build y tests
-
-{Para cada entry en CONFIG_CHANGES[]:}
-
-- [ ] **T-C-{N}** {Descripción concreta del cambio}
-      Archivo: `{file}`
+- [ ] **T-C-{N}** {Concrete change description}
+      File: `{file}`
   ```
-  // Antes
+  // Before
   {current_value}
-  // Después
+  // After
   {target_value}
   ```
 
-{Si CONFIG*CHANGES está vacío:}
-*(No se detectaron cambios de configuración necesarios)\_
+{Per CONFIG_CHANGES[]; empty →}
+_(No configuration changes detected)_
 
-## Fase 4: Breaking changes en código fuente
-
-{Para cada entry en BREAKING_CHANGES_IN_CODE[]:}
+## Phase 4: Breaking changes in source code
 
 - [ ] **T-S-{N}** [{break_id}] `{severity}` — {description}
       Fix: {fix}
-      Archivos afectados:
-      {Para cada {file, line_number, snippet}:}
+      Affected files:
   - `{file}:{line_number}` ({confidence}) — `{snippet}`
 
-{Si BREAKING*CHANGES_IN_CODE está vacío:}
-*(No se detectaron breaking changes en código fuente para esta migración)\_
-
-## Fase 5: Breaking changes en tests
+{Per BREAKING_CHANGES_IN_CODE[], one sub-bullet per file; empty →}
+_(No breaking changes detected in source code for this migration)_
 
-{Para cada entry en BREAKING_CHANGES_IN_TESTS[]:}
+## Phase 5: Breaking changes in tests
 
 - [ ] **T-T-{N}** [{break_id}] `{severity}` — {description}
       Fix: {fix}
-      Archivos afectados:
-      {Para cada {file, line_number, snippet}:}
+      Affected files:
   - `{file}:{line_number}` ({confidence}) — `{snippet}`
 
-{Si BREAKING*CHANGES_IN_TESTS está vacío:}
-*(No se detectaron breaking changes en tests para esta migración)\_
+{Per BREAKING_CHANGES_IN_TESTS[], one sub-bullet per file; empty →}
+_(No breaking changes detected in tests for this migration)_
 
-## Fase 6: Verificación
+## Phase 6: Verification
 
-- [ ] **T-V-001** Verificar compilación TypeScript:
+- [ ] **T-V-001** Verify TypeScript compilation:
   ```bash
   npx tsc --noEmit
-  # En monorepos Nx: npx nx affected --target=typecheck
+  # Nx monorepos: npx nx affected --target=typecheck
   ```
 
-{Si script "build" en SCRIPTS_AVAILABLE[]:}
-
-- [ ] **T-V-002** Verificar build:
+- [ ] **T-V-002** Verify build:
   ```bash
   npm run build
-  # En monorepos Nx: npx nx affected --target=build
+  # Nx monorepos: npx nx affected --target=build
   ```
 
-{Si script "lint" en SCRIPTS_AVAILABLE[]:}
-
-- [ ] **T-V-003** Ejecutar linter:
+- [ ] **T-V-003** Run the linter:
   ```bash
   npm run lint
-  # En monorepos Nx: npx nx affected:lint
+  # Nx monorepos: npx nx affected:lint
   ```
 
-{Si script "test" en SCRIPTS_AVAILABLE[]:}
-
-- [ ] **T-V-004** Correr suite de tests:
+- [ ] **T-V-004** Run the test suite:
   ```bash
   npm test
-  # En monorepos Nx: npx nx affected --target=test
+  # Nx monorepos: npx nx affected --target=test
   ```
 
-{Si script "test:ci" en SCRIPTS_AVAILABLE[]:}
-
-- [ ] **T-V-005** Correr tests en modo CI:
+- [ ] **T-V-005** Run tests in CI mode:
 
   ```bash
   npm run test:ci
   ```
 
-- [ ] **T-V-900** Validar cobertura del escaneo:
-  - confirmar conteo de archivos escaneados (source/tests/config)
-  - revisar `UNSURE_MATCHES[]` y clasificar cada caso
+- [ ] **T-V-900** Validate scan coverage:
+  - confirm scanned file counts (source/tests/config)
+  - review `UNSURE_MATCHES[]` and classify each case
+
+{T-V-002..T-V-005 only when the matching script exists in SCRIPTS_AVAILABLE[]}
 
 ````
 
@@ -262,59 +237,51 @@ No se detectaron breaking changes en tests.
 ```markdown
 # Design: {LIBRARY} v{TARGET_VERSION} Migration
 
-## Estrategia de migración
-
-{Explicar el enfoque en orden de las fases: primero dependencias (para detectar errores
-de compilación antes de tocar código), luego infraestructura, luego config, luego código.
-Describir el riesgo principal y cómo se mitiga.}
+## Migration strategy
 
-## Decisiones técnicas
+{Phase order: dependencies first (surface compilation errors before touching code), then
+infrastructure, config, code. Main risk and mitigation.}
 
-### Rango de versión — `^{TARGET_VERSION}.0.0`
+## Technical decisions
 
-Se usa caret (`^`) en lugar de pin exacto para recibir parches y minor automáticamente,
-manteniendo la estabilidad del major. Se evita `>=` para no aceptar accidentalmente el
-próximo major con potenciales breaking changes.
+### Version range — `^{TARGET_VERSION}.0.0`
 
-### Cambios de configuración
+Caret (`^`) instead of an exact pin receives patches and minors automatically while keeping
+major stability. `>=` is avoided so the next major is not accepted by accident.
 
-{Para cada CONFIG_CHANGE relevante: explicar el razonamiento técnico.}
-{Ej para MIDDY7-001: "Jest necesita transformIgnorePatterns porque @middy v7 publica
-ESM puro y Jest por defecto no transpila node_modules. Sin este cambio, los tests
-fallan con SyntaxError en el import."}
+### Configuration changes
 
-### Breaking changes — análisis de impacto
+{Per CONFIG_CHANGE: technical reasoning. E.g. MIDDY7-001: "Jest needs transformIgnorePatterns
+because @middy v7 ships pure ESM and does not transpile node_modules; without it, tests fail
+with a SyntaxError on import."}
 
-{Para cada breaking change encontrado: explicar el impacto técnico y por qué el fix
-propuesto es la solución correcta y no un workaround.}
+### Breaking changes — impact analysis
 
-{Si no hay breaking changes: "No se detectaron breaking changes en este repositorio
-para esta migración. El riesgo es bajo."}
+{Per breaking change: technical impact and why the fix is correct, not a workaround.}
+{If none: "No breaking changes were detected in this repository for this migration. Risk is low."}
 
-### Compatibilidad del ecosistema
+### Ecosystem compatibility
 
-{Mencionar dependencias relacionadas que pueden verse afectadas.}
-{Ej para Middy v7: listar middlewares de terceros y su estado de compatibilidad con v7.}
-{Si no aplica: "No se identificaron dependencias del ecosistema con riesgo de incompatibilidad."}
+{Related dependencies that may be affected (e.g. Middy v7 third-party middlewares). If none:
+"No ecosystem dependencies with incompatibility risk were identified."}
 
-### Calidad del análisis
+### Analysis quality
 
-- Cobertura: {source_files_scanned} source, {test_files_scanned} tests, {config_files_scanned} config
-- Matches de alta confianza: {N}
-- Matches de media confianza: {N}
-- Matches de baja confianza: {N}
-- Estrategia de revisión manual para baja confianza: {criterio aplicado}
+- Coverage: {source_files_scanned} source, {test_files_scanned} tests, {config_files_scanned} config
+- High-confidence matches: {N}
+- Medium-confidence matches: {N}
+- Low-confidence matches: {N}
+- Manual review strategy for low confidence: {criterion applied}
 
-## Tabla de cambios
+## Change table
 
-| Archivo | Campo / Patrón | Antes | Después |
-|---------|----------------|-------|---------|
-{Una fila por cada cambio concreto en DEPENDENCY_CHANGES[], CONFIG_CHANGES[],
-BREAKING_CHANGES_IN_CODE[] y BREAKING_CHANGES_IN_TESTS[]}
+| File | Field / Pattern | Before | After |
+|------|-----------------|--------|-------|
+{One row per change in DEPENDENCY_CHANGES[], CONFIG_CHANGES[], BREAKING_CHANGES_IN_CODE[], BREAKING_CHANGES_IN_TESTS[]}
 
-## Referencias
+## References
 
-- {DOCS_URL si está disponible}
-- {Links adicionales encontrados durante el análisis}
-- Knowledge base interna consultada: {lista de break_ids relevantes de known-breaks.md}
-````
+- {DOCS_URL if available}
+- {Additional links found during the analysis}
+- Internal knowledge base consulted: {relevant break_ids from known-breaks.md}
+```

package/skills/ancleto-verify/SKILL.md

@@ -10,81 +10,56 @@ metadata:
 
 # aspec Verify
 
-Verify that an implementation matches its change artifacts (proposal, design, tasks, delta specs) by reading the files directly. No external binaries are invoked.
+Verify an implementation against its change artifacts (proposal, design, tasks, delta specs) by reading files. No external binaries.
 
-**Input**: Optionally specify a change name (e.g., `add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous, list the directories under `aspec/changes/` that contain a `tasks.md` file and ask the user to select. Mark changes with incomplete tasks as "(In Progress)".
+**Input**: Optionally a change name (e.g., `add-auth`); if omitted, infer from context. If ambiguous, list `aspec/changes/` dirs containing `tasks.md` and ask the user to select. Mark incomplete-task changes "(In Progress)".
 
 **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
 
 ## Steps
 
-### 1. Load the change artifacts
+### 1. Load change artifacts
 
-Read everything under `aspec/changes/<name>/`:
+Read under `aspec/changes/<name>/`:
 
-- `tasks.md` — the checklist (required)
-- `proposal.md`, `design.md` — intent and decisions (if present)
+- `tasks.md` — checklist (required)
+- `proposal.md`, `design.md` — intent/decisions (if present)
 - `specs/` — delta requirements (if present)
 
-### 2. Verify Completeness
+### 2. Completeness
 
-**Task Completion:**
+**Tasks:** parse checkboxes (`- [ ]` incomplete vs `- [x]` complete); count. Each incomplete → CRITICAL: "Complete task: `<description>`" or "Mark as done if already implemented".
 
-- Parse checkboxes in `tasks.md`: `- [ ]` (incomplete) vs `- [x]` (complete).
-- Count complete vs total tasks.
-- For each incomplete task, add a CRITICAL issue: "Complete task: `<description>`" or "Mark as done if already implemented".
+**Spec coverage:** for each requirement (`### Requirement:`) in `specs/`, search the codebase for related keywords. Unimplemented → CRITICAL: "Requirement not found: `<requirement name>`" + "Implement requirement: `<description>`".
 
-**Spec Coverage:**
+### 3. Correctness
 
-- If delta specs exist in `aspec/changes/<name>/specs/`:
-  - Extract all requirements (marked with `### Requirement:`).
-  - For each requirement, search the codebase for keywords related to it and assess whether implementation likely exists.
-  - If a requirement appears unimplemented, add a CRITICAL issue: "Requirement not found: `<requirement name>`" with the recommendation "Implement requirement: `<description>`".
+**Mapping:** for each requirement, find implementation evidence; note file paths and lines. Divergence → WARNING: "Implementation may diverge from spec: `<details>`" + "Review `<file>:<lines>` against requirement X".
 
-### 3. Verify Correctness
+**Scenarios:** for each `#### Scenario:`, check code handles conditions and tests cover it. Uncovered → WARNING: "Scenario not covered: `<scenario name>`" + "Add test or implementation for scenario: `<description>`".
 
-**Requirement Implementation Mapping:**
+### 4. Coherence
 
-- For each requirement from delta specs, search the codebase for implementation evidence.
-- If found, note file paths and line ranges.
-- If divergence is detected, add a WARNING: "Implementation may diverge from spec: `<details>`" with "Review `<file>:<lines>` against requirement X".
+**Design:** if `design.md` exists, extract key decisions ("Decision:", "Approach:", "Architecture:") and verify adherence. Contradiction → WARNING: "Design decision not followed: `<decision>`" + "Update implementation or revise design.md to match reality". If absent, note "No design.md to verify against".
 
-**Scenario Coverage:**
-
-- For each scenario in delta specs (marked with `#### Scenario:`), check whether conditions are handled in code and whether tests cover the scenario.
-- If a scenario appears uncovered, add a WARNING: "Scenario not covered: `<scenario name>`" with "Add test or implementation for scenario: `<description>`".
-
-### 4. Verify Coherence
-
-**Design Adherence:**
-
-- If `design.md` exists, extract key decisions (sections like "Decision:", "Approach:", "Architecture:") and verify the implementation follows them.
-- If a contradiction is detected, add a WARNING: "Design decision not followed: `<decision>`" with "Update implementation or revise design.md to match reality".
-- If no `design.md` exists, skip this check and note "No design.md to verify against".
-
-**Code Pattern Consistency:**
-
-- Review new code for consistency with project patterns (file naming, directory structure, coding style).
-- Significant deviations get a SUGGESTION: "Code pattern deviation: `<details>`" with "Consider following project pattern: `<example>`".
+**Patterns:** review new code against project patterns (file naming, dirs, style). Significant deviation → SUGGESTION: "Code pattern deviation: `<details>`" + "Consider following project pattern: `<example>`".
 
 ### 5. Capture findings into persistent memory
 
-For every WARNING or CRITICAL issue that reveals an architectural decision, a standing rule, or a reusable lesson, record it with the memory tools:
+For every WARNING/CRITICAL revealing an architectural decision, standing rule, or reusable lesson:
 
-- Standing rules, constraints, or conventions the team must keep following → `recordRule`, e.g.:
+- Standing rules/constraints/conventions → `recordRule`:
   ```
   recordRule({ memory_key: "<kebab-topic>", content: "<the rule>", justification: "<evidence>" })
   ```
-- Design decisions, trade-offs, and why one path was taken → `recordDecision`, e.g.:
+- Design decisions/trade-offs and why → `recordDecision`:
   ```
   recordDecision({ memory_key: "<kebab-topic>", content: "<the decision>", justification: "<reason>" })
   ```
 
-Record only findings that would save future investigation. Do not record the verification outcome itself. If no finding meets the bar, record nothing and say so.
+Record only what saves future investigation; not the verification outcome. If nothing meets the bar, record nothing and say so.
 
-### 6. Generate the Verification Report
-
-**Summary Scorecard:**
+### 6. Verification Report
 
 ```
 ## Verification Report: <change-name>
@@ -97,36 +72,31 @@ Record only findings that would save future investigation. Do not record the ver
 | Coherence    | Followed/Issues  |
 ```
 
-**Issues by Priority:**
+**Issues by priority** — each needs a specific, actionable recommendation:
 
-1. **CRITICAL** (must fix before archive): incomplete tasks, missing requirement implementations — each with a specific, actionable recommendation.
-2. **WARNING** (should fix): spec/design divergences, missing scenario coverage — each with a specific recommendation.
+1. **CRITICAL** (block archive): incomplete tasks, missing requirement implementations.
+2. **WARNING** (should fix): spec/design divergences, missing scenario coverage.
 3. **SUGGESTION** (nice to fix): pattern inconsistencies, minor improvements.
 
-**Final Assessment:**
-
-- If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
-- If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
-- If all clear: "All checks passed. Ready for archive."
-- Plus a line listing which memories were recorded in step 5 (or "No findings recorded").
+**Assessment:** CRITICAL → "X critical issue(s) found. Fix before archiving."; only warnings → "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."; clean → "All checks passed. Ready for archive." Plus which memories were recorded in step 5 (or "No findings recorded").
 
-## Verification Heuristics
+## Heuristics
 
-- **Completeness**: focus on objective checklist items (checkboxes, requirements list).
-- **Correctness**: use keyword search, file path analysis, reasonable inference — don't require perfect certainty.
-- **Coherence**: look for glaring inconsistencies, don't nitpick style.
-- **False Positives**: when uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL.
-- **Actionability**: every issue must have a specific recommendation with file/line references where applicable.
+- **Completeness**: objective checklist items only.
+- **Correctness**: keyword search, path analysis, reasonable inference — no perfect certainty required.
+- **Coherence**: glaring inconsistencies only; don't nitpick style.
+- **False positives**: when uncertain, prefer SUGGESTION > WARNING > CRITICAL.
+- **Actionability**: every issue carries a specific recommendation with file/line refs.
 
 ## Graceful Degradation
 
-- If only `tasks.md` exists: verify task completion only, skip spec/design checks.
-- If tasks + specs exist: verify completeness and correctness, skip design.
-- If full artifacts: verify all three dimensions.
-- Always note which checks were skipped and why.
+- Only `tasks.md` → task completion, skip spec/design.
+- Tasks + specs → completeness + correctness, skip design.
+- Full artifacts → all three dimensions.
+- Always note skipped checks and why.
 
 ## Guardrails
 
-- Use code references in format `file.ts:123`.
-- No vague suggestions like "consider reviewing" — every issue needs a specific recommendation.
+- Reference code as `file.ts:123`.
+- No vague suggestions ("consider reviewing") — every issue needs a specific recommendation.
 - `recordRule`/`recordDecision` accept only `memory_key`, `content`, `justification`, `scope`. Never send `source`, `confidence`, `status` or `id` — the runtime manages those.