@jaguilar87/gaia 5.0.0-rc.2

package/skills/gaia-release/reference.md

@@ -0,0 +1,92 @@
+# Gaia Release Reference
+
+Detailed commands for dry-run, beta, and release modes. Read on-demand during release validation.
+
+## Dry-Run Steps (LOCAL)
+
+The fastest path is `npm run gaia:verify-install:local` -- it packs, installs into `/tmp/gaia-sandbox-<ts>/`, runs the 8-check harness, and cleans up. Use the manual sequence below only when you need to poke at the sandbox interactively.
+
+1. Build both plugins:
+   `npm run build:plugins`
+2. Validate build:
+   `npm run pre-publish:validate`
+3. Run the harness (does pack + install + checks):
+   `npm run gaia:verify-install:local`
+   - Or for a registry version: `npm run gaia:verify-install:rc` / `gaia:verify-install:latest`
+   - Harness uses `$WORKSPACE/node_modules/.bin/gaia` directly via PATH (no `npx` indirection).
+4. For manual inspection, run with `--stay` to keep the sandbox:
+   ```
+   npm pack
+   bash bin/validate-sandbox.sh --tarball ./jaguilar87-gaia-*.tgz --target sandbox --stay
+   ```
+   Sandbox path prints on exit; inspect `.claude/`, rerun checks, then `rm -rf` manually.
+5. Test BOTH modes (requires restarting `claude` in the sandbox dir):
+   - Default (ops): start `claude`, verify orchestrator, delegation, T3 nonce approval
+   - Security: `GAIA_PLUGIN_MODE=security claude`, verify no agents, native T3 dialog
+6. Test plugin channel (if applicable):
+   `claude --plugin-dir /path/to/gaia-ops-dev/dist/gaia-ops`
+7. Run test pyramid:
+   - L1: `npm test` (from gaia-ops-dev, not test project)
+   - Routing: `python3 tools/gaia_simulator/cli.py "<test prompt>"`
+
+**Default path:** `/tmp/gaia-sandbox-<unix-ts>-<pid>/` (created by harness).
+**Cleanup:** Automatic unless `--stay` is passed.
+
+## Beta Steps (PIPELINE)
+
+1. All dry-run steps must pass locally first
+2. Version bump with pre-release tag:
+   `npm version preminor --preid=beta` (or `premajor` for breaking changes)
+3. Commit and push the version bump (PR or direct to main)
+4. Create a GitHub Release:
+   - Tag: the version from package.json (e.g., `v5.3.0-beta.0`)
+   - Title: version number
+   - Mark as pre-release
+5. `publish.yml` triggers automatically and publishes with `--tag beta`
+6. Verify from npm (harness path -- installs into `/tmp/` sandbox and runs the 8 checks):
+   ```
+   bash bin/validate-sandbox.sh --version "@jaguilar87/gaia@beta" --target sandbox
+   ```
+
+**To promote beta to latest:** `npm dist-tag add @jaguilar87/gaia@X.Y.Z latest`
+
+## Release Steps (PIPELINE)
+
+1. All dry-run steps must pass locally first
+2. Version bump:
+   `npm version minor` (or `major` / `patch` as appropriate)
+3. Commit and push the version bump to main
+4. Create a GitHub Release:
+   - Tag: the version from package.json (e.g., `v5.3.0`)
+   - Title: version number
+   - Generate release notes from commits
+5. `publish.yml` triggers automatically and publishes with `--tag latest`
+6. Verify from npm (harness path -- installs into `/tmp/` sandbox and runs the 8 checks):
+   ```
+   npm run gaia:verify-install:latest
+   ```
+
+## Pipeline Details
+
+The `publish.yml` workflow (`.github/workflows/publish.yml`) runs on every GitHub Release event. It:
+- Checks out the exact tagged commit
+- Installs deps with `npm ci`
+- Builds plugins with `npm run build:plugins`
+- Verifies all expected artifacts in `dist/`
+- Commits built artifacts back if changed
+- Runs `npm run pre-publish:validate`
+- Auto-detects npm tag from version string:
+  - `*-beta.*` -> `--tag beta`
+  - `*-rc.*` -> `--tag rc`
+  - `*-alpha.*` -> `--tag alpha`
+  - everything else -> `--tag latest`
+- Publishes with `npm publish --access public --tag <detected>`
+- `NPM_TOKEN` is stored in GitHub Secrets (never local)
+
+## Path Defaults
+
+| User says | Path used |
+|-----------|-----------|
+| "here" / "this session" / "this project" / live mode | Nearest `.claude/` ancestor of cwd with a Gaia marker, falling back to `$HOME/ws/me/` if present |
+| "in project X" / specific path | Pass `--workspace /absolute/path/to/project` to `bin/validate-sandbox.sh` (bypasses auto-detect) |
+| Nothing specified (dry-run/beta verify) | `/tmp/gaia-sandbox-<unix-ts>-<pid>/` (auto-cleanup unless `--stay`) |

package/skills/gaia-self-check/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: gaia-self-check
+description: Use when the user asks to validate Gaia internal consistency, audit the local installation, or check that skills, agents, and commands in .claude/ are coherent
+metadata:
+  user-invocable: true
+  type: technique
+---
+
+# Gaia Self-Check
+
+## Overview
+
+Validates the internal consistency of a Gaia installation by inspecting only
+`.claude/` on disk. The skill has one job: inventory the components, compare
+their declared state against their physical state, and surface discrepancies.
+It never reaches outside the installation -- no external repo, no network, no
+cloud API.
+
+The principle that keeps this skill safe is **ask-before-fix**: the skill may
+detect a broken cross-reference and know exactly how to repair it, but it
+never applies the fix on its own. Every proposed change is presented to the
+user as a concrete propuesta and waits for explicit aprobación before any
+edit happens.
+
+## When to activate
+
+The user says things like:
+- "check gaia", "valida consistencia", "audita la instalación"
+- "mis skills están rotas?", "hay referencias colgantes?"
+- "gaia self-check", "self-check", "sanity check de .claude"
+
+If the intent is to verify the install **pipeline** (npm, dry-run, beta,
+release), that is `gaia-verify`, not this skill. If the intent is to diagnose
+a symlink or path problem at the CLI level, that is `gaia-doctor`.
+
+## The 3-step cycle
+
+Every run follows the same three phases. Detailed operational instructions
+for each phase live in `reference.md`.
+
+### 1. Inventario
+
+Walk `.claude/skills/`, `.claude/agents/`, `.claude/commands/` and build a
+list of every component present. Read each component's frontmatter and
+record declared metadata (name, description, references). Hooks are only
+inventoried if `settings.json` references them. Nothing outside `.claude/`
+is touched.
+
+*[expanded in T2 -- details on which directories to scan and how to parse
+frontmatter tolerantly]*
+
+### 2. Checks de consistencia
+
+For each component, compare declared state against physical state. The
+categories of checks are:
+
+- **Frontmatter validity** -- YAML parses, required fields present.
+- **Name vs dirname** -- the `name` field matches the directory or file name.
+- **Cross-references** -- skill-to-skill or agent-to-skill references point
+  to components that exist physically.
+- **Routing consistency** -- agents mentioned in routing config exist.
+- **README listings** -- if a README exists, listed files are present and
+  present files are listed.
+
+*[expanded in T2 -- full per-category check rules and report format]*
+
+### 3. Propuesta con aprobación
+
+For every inconsistency found, build a concrete propuesta: which file, what
+change, what effect. Present the list to the user and wait for explicit
+aprobación per item (or a global confirmation if the mechanism does not
+support per-item). Record which fixes were aprobado and which were rechazado.
+Never apply a change without this approval step -- that is the
+ask-before-fix guard.
+
+*[expanded in T3 -- full propuesta format, approval mechanism, handling of
+ambiguous cases]*
+
+## Operating principle: ask-before-fix
+
+The skill is allowed to be wrong. A proposed fix may misread the user's
+intent, may touch a file the user wanted stale on purpose, or may conflict
+with an in-flight change. The ask-before-fix principle exists precisely
+because the skill cannot distinguish "inconsistency" from "deliberate
+deviation" on its own.
+
+Practical consequence: the output of this skill is always a **report + a
+list of propuestas**, never a mutated file. The skill surfaces findings and
+waits. The user decides.
+
+## Output shape
+
+The terminal output is the report. Structure and examples live in
+`reference.md` under "Output Format". The short version: one table per
+category, columns for component, type, inconsistencia, and fix propuesto.
+
+## Out of scope
+
+- Anything outside `.claude/` -- no cloning repos, no fetching remotes.
+- Running tests or builds -- consistency checks only, no execution.
+- Applying fixes automatically -- ask-before-fix applies always.
+- Network access of any kind.
+
+## Anti-patterns
+
+- **Auto-fixing "obvious" issues** -- every auto-fix bypasses ask-before-fix
+  and teaches the skill that some categories of change are safe to take
+  unilaterally. None are.
+- **Hard-failing on one bad frontmatter** -- one malformed YAML should be
+  reported as an inconsistency, not stop the whole scan.
+- **Cross-referencing external state** -- the moment the skill reads outside
+  `.claude/`, it stops being a self-check and becomes an environment audit.
+- **Silent propuestas** -- a fix that is not shown to the user in
+  human-readable form cannot be aprobado with informed consent.

package/skills/gaia-self-check/reference.md

@@ -0,0 +1,453 @@
+# Gaia Self-Check -- Reference
+
+Operational detail for the three phases of the self-check cycle. The main
+SKILL.md defines the cycle and the ask-before-fix principle; this file
+holds the per-category check rules, output format, and propuesta mechanics.
+
+This reference is intentionally a scaffold. T2 expands the per-category
+check rules. T3 expands the propuesta + aprobación flow. Placeholders below
+mark where each expansion lands.
+
+## Scope
+
+The skill operates exclusively on `.claude/`. The inventory walk covers:
+
+| Directory | Component | Always scanned |
+|-----------|-----------|----------------|
+| `.claude/skills/` | Skills | Yes |
+| `.claude/agents/` | Agents | Yes |
+| `.claude/commands/` | Slash commands | Yes |
+| `.claude/hooks/` | Hooks | Yes |
+
+No path outside `.claude/` is read, regardless of what a component's
+frontmatter references.
+
+## Output Format
+
+The report is terminal-friendly markdown: one section per category, each
+with a table. Empty categories are reported as "OK" so the user can see
+the scan covered them.
+
+Columns:
+
+| Column | Meaning |
+|--------|---------|
+| Componente | File or directory name |
+| Tipo | Skill / Agent / Command / Hook |
+| Inconsistencia | One-line description of what is wrong |
+| Fix propuesto | One-line description of the proposed change |
+
+Each category section below contains a concrete example table. An empty
+category (no findings) is reported as a single "OK" row so the user can
+confirm the scan covered it.
+
+At the end of the report, a summary line: `N inconsistencias encontradas
+en M componentes. Propuesta pendiente de aprobación.`
+
+## Categorías de checks
+
+Each category describes: what to verify, how to detect it, and what a
+positive finding (inconsistency) looks like. The agent reads the relevant
+files using Read and Glob tools -- no shell commands, no external state.
+
+### Frontmatter validity
+
+**Qué verifica:** Every `SKILL.md` (in `skills/*/`), `*.md` agent file (in
+`agents/`), and `*.md` command file (in `commands/`) must have a YAML
+frontmatter block delimited by `---` that parses without error.
+
+**Cómo detectarlo:**
+
+```
+for each component file:
+  content = Read(file)
+  if content does not contain '---' at start and again later:
+    FINDING: missing frontmatter block
+  else:
+    block = text between first and second '---'
+    try parse as YAML:
+      if parse error: FINDING: malformed YAML frontmatter
+      if required fields missing (name, description):
+        FINDING: missing required field <field>
+```
+
+Required fields by component type:
+
+| Type | Required fields | Notes |
+|------|----------------|-------|
+| Skill (`SKILL.md`) | `name`, `description` | |
+| Agent (`agents/*.md`) | `name`, `description`, `tools` | `tools` is the correct field; `allowed-tools` is not valid here |
+| Command (`commands/*.md`) | `name`, `description` | Commands use `allowed-tools` (not `tools`) for tool restrictions -- both field names are valid depending on whether the command is a CC slash command or an agent-facing command |
+
+**Convención `tools` vs `allowed-tools`:** Agent frontmatters declare their tool access with `tools`. Command frontmatters (slash commands) use `allowed-tools` when restricting tool access. These are two distinct conventions for two distinct component types. When validating frontmatter, apply the correct expected field per component type -- flagging `allowed-tools` in a command as "wrong field" is a false positive.
+
+**Ejemplo de finding:**
+
+| Componente | Tipo | Inconsistencia | Fix propuesto |
+|------------|------|----------------|---------------|
+| `skills/my-skill/SKILL.md` | Skill | Frontmatter YAML inválido: mapping values not allowed here (line 3) | Corregir indentación YAML en el frontmatter |
+| `agents/my-agent.md` | Agent | Campo requerido `tools` ausente del frontmatter | Agregar `tools:` con la lista de herramientas del agent |
+
+---
+
+### Name-directory match (dirname)
+
+**Qué verifica:** The `name` field in the frontmatter must match the
+component's directory name (for skills) or file stem (for agents and
+commands).
+
+**Cómo detectarlo:**
+
+```
+skills:
+  for each dir in .claude/skills/ (skip README.md, reference.md):
+    skill_file = dir / SKILL.md
+    name_in_frontmatter = yaml(skill_file).get('name')
+    expected = dir.name          # e.g. "gaia-self-check"
+    if name_in_frontmatter != expected:
+      FINDING: name mismatch
+
+agents:
+  for each file in .claude/agents/*.md:
+    name_in_frontmatter = yaml(file).get('name')
+    expected = file.stem         # e.g. "gaia-system" from "gaia-system.md"
+    if name_in_frontmatter != expected:
+      FINDING: name mismatch
+
+commands: same pattern as agents
+```
+
+**Ejemplo de finding:**
+
+| Componente | Tipo | Inconsistencia | Fix propuesto |
+|------------|------|----------------|---------------|
+| `skills/gaia-ops/SKILL.md` | Skill | `name: gaia_ops` en frontmatter, directorio es `gaia-ops` | Cambiar `name` a `gaia-ops` en el frontmatter |
+| `agents/terraform.md` | Agent | `name: terraform-architect` en frontmatter, archivo es `terraform.md` | Renombrar archivo a `terraform-architect.md` o corregir `name` |
+
+---
+
+### Cross-references resolvables (cross-reference)
+
+**Qué verifica:** References from a component's frontmatter to other skills
+must point to directories that exist physically in `.claude/skills/`. This
+catches renamed or deleted skills that are still listed as dependencies.
+
+**Cómo detectarlo:**
+
+```
+for each SKILL.md:
+  yaml_data = parse frontmatter
+  refs = yaml_data.get('skills', [])       # list of skill names
+  for each ref in refs:
+    target = .claude/skills/<ref>/
+    if target directory does not exist:
+      FINDING: cross-reference to missing skill
+```
+
+Also check narrative cross-references in the body: if the file body
+mentions a `skills/<name>/` path, verify that path exists under `.claude/`.
+This is best-effort -- report only paths that look like structured
+references (e.g., `` `skills/foo/SKILL.md` ``), not every mention of a name.
+
+**Ejemplo de finding:**
+
+| Componente | Tipo | Inconsistencia | Fix propuesto |
+|------------|------|----------------|---------------|
+| `agents/gaia-system.md` | Agent | Skill `nah-patterns` referenciada en frontmatter no existe en `.claude/skills/` | Eliminar `nah-patterns` del frontmatter o crear la skill |
+
+---
+
+### Orphan/listed consistency (routing)
+
+**Qué verifica:** Three independent sub-checks. Each sub-check targets a
+distinct source of truth that drifts independently.
+
+#### Sub-check A: Orphan detection (skills)
+
+A skill is an orphan only when it meets both conditions simultaneously:
+
+1. No agent frontmatter anywhere in `.claude/agents/` lists it under `skills:`.
+2. It is absent from the directory tree in `skills/README.md`.
+
+If the skill appears in at least one agent's `skills:` list, it is a
+**referenced skill** -- not an orphan. It may still be missing from the README
+tree (that is doc drift, see Sub-check B), but it is not orphaned.
+
+```
+skills_on_disk   = {dir.name for dir in .claude/skills/ if (dir/SKILL.md).exists()}
+agent_referenced = {skill for each agent in .claude/agents/*.md
+                         for skill in yaml(agent).get('skills', [])}
+skills_in_tree   = {name parsed from directory tree section of skills/README.md}
+
+orphans          = skills_on_disk - agent_referenced - skills_in_tree
+doc_drift        = (skills_on_disk & agent_referenced) - skills_in_tree
+```
+
+`orphans` -> FINDING: skill not referenced by any agent and absent from README
+`doc_drift` -> FINDING (lower severity): skill is referenced by agents but missing from README tree
+
+#### Sub-check B: README sources of truth
+
+`skills/README.md` contains two distinct structures that drift independently:
+
+1. **Directory tree**: the visual listing of skill directories.
+2. **Skill-to-agent assignment matrix**: which skills are assigned to which agents.
+
+Verify both explicitly:
+
+```
+# Tree check
+skills_in_tree   = {name from directory tree section}
+skills_on_disk   = {dir.name for dir in .claude/skills/ if (dir/SKILL.md).exists()}
+missing_from_tree = skills_on_disk - skills_in_tree
+stale_in_tree    = skills_in_tree - skills_on_disk
+
+# Matrix check
+skills_in_matrix = {name from each row of the assignment table}
+for each skill in skills_in_matrix:
+  if skill not in skills_on_disk:
+    FINDING: matrix references skill that does not exist on disk
+```
+
+Report tree drift and matrix drift as separate findings -- they require
+different fixes (update the tree listing vs update the assignment table).
+
+The same two-source check applies to `agents/README.md` and
+`commands/README.md`: each surface has its own README and each may contain
+both a directory listing and cross-reference tables.
+
+#### Sub-check C: READMEs for all three surfaces
+
+The check covers all three surface READMEs explicitly:
+
+| README | Surface | What to check |
+|--------|---------|---------------|
+| `skills/README.md` | Skills | Directory tree + assignment matrix |
+| `agents/README.md` | Agents | Directory listing vs `.claude/agents/*.md` |
+| `commands/README.md` | Commands | Directory listing vs `.claude/commands/*.md` |
+
+If a README does not exist for a surface, report "README absent for
+`<surface>/`" rather than skipping silently.
+
+#### Sub-check D: Routing config
+
+If `.claude/config/surface-routing.json` exists, each `primary_agent` value
+must match a file stem in `.claude/agents/`. A routing entry pointing to a
+non-existent agent is a broken cross-reference between config and agents.
+
+```
+routing        = parse .claude/config/surface-routing.json
+agents_on_disk = {f.stem for f in .claude/agents/*.md}
+for each surface in routing.surfaces:
+  agent = surface.primary_agent
+  if agent not in agents_on_disk:
+    FINDING: routing references missing agent
+```
+
+**Ejemplo de finding:**
+
+| Componente | Tipo | Inconsistencia | Fix propuesto |
+|------------|------|----------------|---------------|
+| `skills/gaia-self-check/` | Skill | En disco y referenciada por agents, ausente del árbol en `skills/README.md` | Agregar al árbol de directorios en `skills/README.md` (doc drift, no orphan) |
+| `skills/draft-skill/` | Skill | En disco, sin referencias en ningún agent, ausente del README | requires_human_review: ¿skill en construcción o puede eliminarse? |
+| `skills/README.md` | Doc | `nah-skill` en la matriz de asignación pero directorio ausente en disco | Eliminar `nah-skill` de la matriz o restaurar la skill |
+| `skills/old-skill/` | Skill | Listado en árbol del README pero directorio ausente en disco | Eliminar entrada del árbol en el README o restaurar la skill |
+| `agents/README.md` | Doc | README ausente para la superficie `agents/` | Crear `agents/README.md` con listado de agents |
+| `config/surface-routing.json` | Config | `primary_agent: ghost-agent` no existe en `.claude/agents/` | Actualizar `primary_agent` o crear `ghost-agent.md` |
+
+---
+
+### hooks/ (siempre)
+
+**Qué verifica:** Hooks are always part of the scan. Two directions:
+
+1. **settings.json -> disk**: Every hook file declared in `settings.json`
+   must exist on disk. A hook registered but missing on disk causes silent
+   runtime failures -- the harness calls the hook and gets a file-not-found
+   error.
+2. **disk -> settings.json**: Every file under `.claude/hooks/` must be
+   registered in `settings.json`. A hook file present on disk but not
+   registered is dead code -- it runs nowhere.
+
+**Cómo detectarlo:**
+
+```
+# Parse settings.json (may not exist)
+if .claude/settings.json does not exist:
+  report: "no active hooks detected -- settings.json absent"
+  skip hooks check
+else:
+  settings = parse .claude/settings.json
+  hooks_in_settings = {resolve path from each hook entry in settings.hooks}
+
+  # Direction 1: registered -> disk
+  for each path in hooks_in_settings:
+    if file does not exist at path:
+      FINDING: hook registered in settings.json but file missing on disk
+
+  # Direction 2: disk -> registered
+  hooks_on_disk = {f for f in .claude/hooks/*.py}
+  for each file in hooks_on_disk:
+    if file not in hooks_in_settings:
+      FINDING: hook file on disk but not registered in settings.json
+
+  if hooks_in_settings is empty:
+    report: "no active hooks detected -- settings.json present but no hooks entries"
+```
+
+**Ejemplo de finding:**
+
+| Componente | Tipo | Inconsistencia | Fix propuesto |
+|------------|------|----------------|---------------|
+| `settings.json` | Config | Hook `.claude/hooks/post_tool_use.py` registrado pero archivo no existe en disco | Crear el archivo del hook o eliminar la entrada de `settings.json` |
+| `hooks/pre_tool_use.py` | Hook | Archivo presente en disco pero no registrado en `settings.json` | Agregar entrada en `settings.json` o eliminar el archivo |
+
+## Propuesta y Aprobación
+
+The ask-before-fix principle governs every corrective action the skill
+might take. The skill is allowed to detect, describe, and propose --
+never to apply. Aprobación explícita del usuario is the only gate that
+unlocks a fix. This section operationalizes that principle into a
+repeatable flow.
+
+### El flujo completo
+
+```
+Inconsistencia detectada
+        |
+        v
+Construir propuesta (qué archivo, qué cambio exacto, qué efecto)
+        |
+        v
+Presentar al usuario via AskUserQuestion (una por finding)
+        |
+        v
+  aprobado?  ----yes----> Aplicar fix + registrar como aprobado
+     |
+     no
+     |
+     v
+  Sin cambios + registrar como "ignored by user"
+```
+
+One approval per delta. Each finding is its own propuesta -- no bulk
+approval. If the user approves items 1 and 3 but rejects item 2, fixes
+1 and 3 are applied and item 2 is left untouched.
+
+### Plantilla de propuesta
+
+Every propuesta presented to the user must include these fields:
+
+```
+Finding:   <one-line description of the inconsistency detected>
+Archivo:   <absolute path of the file to be modified>
+Fix:       <exact change -- field value to set, line to add/remove, etc.>
+Efecto:    <what changes after the fix is applied>
+Rollback:  <how to undo -- typically "revert <field> to previous value">
+```
+
+Do not omit any field. A propuesta missing "Rollback" or "Efecto" cannot
+be aprobado with informed consent -- silent propuestas violate
+ask-before-fix as much as auto-fixes do.
+
+### Ejemplo concreto
+
+The agent detects that `skills/gaia-ops/SKILL.md` has `name: gaia_ops`
+but the directory is named `gaia-ops`. The propuesta presented to the
+user looks like this:
+
+---
+
+**Propuesta 1 de 3**
+
+```
+Finding:   name en frontmatter no coincide con el nombre del directorio
+Archivo:   /home/jorge/.claude/skills/gaia-ops/SKILL.md
+Fix:       Cambiar `name: gaia_ops` a `name: gaia-ops` en el frontmatter
+Efecto:    El self-check ya no reportará este mismatch; cross-references
+           que usen "gaia-ops" resolverán correctamente
+Rollback:  Revertir `name` a `gaia_ops` en el frontmatter
+```
+
+Aprobar este fix? [s/n]
+
+---
+
+That message block is the minimum. The agent may add context (e.g., "this
+field is used by the orchestrator to route skill injection") but must not
+omit any of the 5 fields.
+
+### Mecanismo de aprobación
+
+**Preferred:** `AskUserQuestion` per finding. The agent pauses after each
+propuesta and waits for the user's answer before moving to the next.
+
+**Fallback (when per-item mechanism is unavailable):** Present all
+propuestas as a numbered list in a single message, then ask the user to
+reply with the numbers they approve (e.g., "Apruebo: 1, 3"). Items not
+listed are treated as rechazado.
+
+Never apply any fix before receiving the user's answer. The skill must
+wait -- it cannot infer "likely approved" from silence or from the fact
+that the fix looks trivial.
+
+### Estado post-flow
+
+After all propuestas have been answered:
+
+| Resultado | Acción | Registro |
+|-----------|--------|----------|
+| `aprobado` | Aplicar el fix (Edit/Write) | Log: "Fix aplicado: <finding>" |
+| `rechazado` | Nada se toca | Log: "Ignored by user: <finding>" |
+
+The final report summary line must reflect both counts:
+
+```
+Fixes aplicados: N aprobados, M ignorados por el usuario.
+```
+
+If a fix fails after aprobación (e.g., the file changed between scan and
+apply), report the failure explicitly and stop. Do not silently skip.
+
+### Edge cases: requires_human_review
+
+Some findings are ambiguous -- the skill cannot determine the correct fix
+without context only the user has. In these cases the skill must not
+propose a fix at all. Instead, mark the finding as `requires_human_review`
+in the report and describe what is unclear.
+
+Situations that trigger `requires_human_review`:
+
+| Situation | Why it is ambiguous |
+|-----------|---------------------|
+| Orphan skill directory (has `SKILL.md`, not referenced in any agent frontmatter, absent from README) | Could be deliberate (WIP skill not yet published) or a forgotten leftover |
+| Agent `name` vs file stem mismatch where both the name and the stem look intentional | Renaming the file or the field both produce valid results -- only the user knows the intent |
+| Cross-reference to a skill that existed and was deleted (deletion was recent per git blame) | Could be a stale ref or could be that the user intends to restore the skill |
+| Routing entry for an agent with no skills list | Might be a new agent mid-construction or a misconfiguration |
+
+When marking `requires_human_review`, the report row looks like:
+
+| Componente | Tipo | Inconsistencia | Fix propuesto |
+|------------|------|----------------|---------------|
+| `skills/draft-skill/` | Skill | Directorio presente en disco, ausente del README -- propósito incierto | requires_human_review: ¿es una skill en construcción o puede eliminarse? |
+
+The agent should describe the ambiguity in plain language so the user can
+make an informed decision. After the user clarifies, the agent may
+construct and present a normal propuesta for the now-unambiguous fix.
+
+### Cross-reference
+
+The approval mechanism used here is semantically equivalent to the one
+in `skills/request-approval/SKILL.md` (operation / exact_content /
+scope / risk / rollback fields). The difference is context: `request-
+approval` handles hook-blocked Bash commands; this flow handles
+documentation and frontmatter fixes. The same informed-consent principle
+applies to both.
+
+## Notes
+
+- Tolerance: a malformed frontmatter is itself an inconsistency, not a
+  fatal error. The scan continues and reports the component as broken.
+- No external state: the skill never reads outside `.claude/`. Any
+  reference to an external path is reported as an inconsistency, not
+  followed.