@qball-inc/the-bulwark 1.2.0 → 1.3.0

package/skills/bulwark-research/SKILL.md

@@ -1,5 +1,13 @@
 ---
 name: bulwark-research
+allowed-tools:
+  - AskUserQuestion
+  - Bash
+  - Glob
+  - Read
+  - Skill
+  - Task
+  - Write
 version: 1.0.1
 description: Structured multi-viewpoint research using 5 parallel Sonnet sub-agents. Use when deep research is needed on a complex topic before implementation planning.
 user-invocable: true

package/skills/bulwark-scaffold/SKILL.md

@@ -2,8 +2,15 @@
 name: bulwark-scaffold
 description: Initialize Bulwark infrastructure in a project: language-aware Justfile (8 langs), bun + eval-framework toolchain, logs/ subdirectories, and optional hooks.
 when_to_use: Use when the user asks to set up Bulwark in a project, scaffold a Justfile, configure Bulwark hooks, or initialize the eval framework. Do NOT auto-invoke during normal development — this writes files, runs installers, and modifies .gitignore. Also invoked by the Bulwark init skill when scaffolding is selected.
-argument-hint: "[--force] [--no-hooks] [--dry-run] [--lang=<node|python|rust|go|kotlin|swift|shell|generic>]"
+argument-hint: "[--force] [--no-hooks] [--with-permission-hook] [--dry-run] [--lang=<node|python|rust|go|kotlin|swift|shell|generic>]"
 user-invocable: true
+allowed-tools:
+  - AskUserQuestion
+  - Bash
+  - Edit
+  - Glob
+  - Read
+  - Write
 version: 1.0.1
 author: "Ashay Kubal @ Qball Inc."
 ---
@@ -20,7 +27,7 @@ Initialize Bulwark infrastructure in a project by generating Justfile templates,
 
 You are the orchestrator. Follow every item in order. Do NOT return to the user until all applicable items are checked.
 
-- [ ] **Step 1 — Parse arguments**: `--force`, `--no-hooks`, `--dry-run`, `--lang=<...>` extracted from `$ARGUMENTS`
+- [ ] **Step 1 — Parse arguments**: `--force`, `--no-hooks`, `--with-permission-hook`, `--dry-run`, `--lang=<...>` extracted from `$ARGUMENTS`
 - [ ] **Step 2 — Detect project language**: If `--lang` not supplied, project files inspected (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc.); defaults to `generic` when no signal found
 - [ ] **Step 3 — `just` runtime check**: `command -v just` runs; if missing, follow Step 3 install path
 - [ ] **Step 3.5a — `bun` runtime check**: `bash <resolved-installer-path> --verify` invoked (NOT `command -v bun` — that bypasses version check); follow Step 3.5 install path if exit non-zero
@@ -31,6 +38,7 @@ You are the orchestrator. Follow every item in order. Do NOT return to the user
 - [ ] **Step 6 — `logs/` subdirectories**: `diagnostics/`, `validations/`, `debug-reports/` created
 - [ ] **Step 7 — `.gitignore`**: Bulwark log patterns appended idempotently
 - [ ] **Step 8 — Hooks**: If plugin-level hooks active, SKIP `.claude/settings.json` hook injection (anti-duplication)
+- [ ] **Step 8a — Permission hook (opt-in)**: ONLY if `--with-permission-hook` — confirm trust (AskUserQuestion), merge `PreToolUse` entry into `.claude/settings.json`, copy `bulwark-permission-hook.sh`, record choice. Default (no flag) = NOT installed
 - [ ] **Step 9 — Scaffold log**: `logs/scaffold-{ts}.yaml` written with top-level `reviewed_files: [...]` (Stop-hook contract)
 - [ ] **Step 10 — Report results**: User-facing summary emitted listing files written, installer outcomes, and any skipped steps
 
@@ -45,6 +53,7 @@ You are the orchestrator. Follow every item in order. Do NOT return to the user
 **Options:**
 - `--force` - Overwrite existing Justfile (creates backup)
 - `--no-hooks` - Skip hook configuration (hooks are generated by default)
+- `--with-permission-hook` - Also install the opt-in PreToolUse permission-bypass hook (auto-approves Bulwark's own bundled-asset reads/edits/scripts). Default: NOT installed
 - `--dry-run` - Show what would be generated without writing files
 - `--lang=<node|python|rust|go|kotlin|swift|shell|generic>` - Override language detection
 
@@ -52,6 +61,7 @@ You are the orchestrator. Follow every item in order. Do NOT return to the user
 - `/bulwark-scaffold` - Full scaffold with Justfile + logs/ + hooks
 - `/bulwark-scaffold --force` - Overwrite existing Justfile
 - `/bulwark-scaffold --no-hooks` - Skip hook configuration
+- `/bulwark-scaffold --with-permission-hook` - Scaffold + install the opt-in permission-bypass hook
 - `/bulwark-scaffold --dry-run` - Preview changes
 
 ---
@@ -63,6 +73,7 @@ You are the orchestrator. Follow every item in order. Do NOT return to the user
 Extract options from `$ARGUMENTS`:
 - `--force` → FORCE_OVERWRITE=true
 - `--no-hooks` → SKIP_HOOKS=true
+- `--with-permission-hook` → WITH_PERMISSION_HOOK=true (default: false)
 - `--dry-run` → DRY_RUN=true
 - `--lang=X` → LANG_OVERRIDE=X
 
@@ -194,6 +205,10 @@ If DRY_RUN is true, display preview and exit:
 - scripts/hooks/enforce-quality.sh
 - scripts/hooks/suggest-pipeline-stop.sh
 {ENDIF}
+{IF WITH_PERMISSION_HOOK}
+- scripts/hooks/bulwark-permission-hook.sh
+- .claude/settings.json (PreToolUse permission-bypass entry — merged independently of --no-hooks)
+{ENDIF}
 
 **Would update:**
 - .gitignore (add Bulwark patterns)
@@ -365,6 +380,56 @@ Check if `.claude/settings.json` exists:
 
 Create parent directories as needed (`mkdir -p`).
 
+### Step 8a: Optional Permission-Bypass Hook (opt-in)
+
+ONLY if `WITH_PERMISSION_HOOK` is true (the `--with-permission-hook` flag). Default (no flag) → **SKIP this entire step**; the permission hook is NOT installed and nothing below runs. Set `PERMISSION_HOOK=not_requested` and continue to Step 9.
+
+This installs `bulwark-permission-hook.sh` as a **project-scope** `PreToolUse` hook that auto-approves Read/Edit/Bash operations on **Bulwark's own bundled assets** — skipping the per-file permission prompts CC raises on plugin-bundled files the user already trusted at install. It is a scoped workaround for upstream CC permission bugs (retire when `#29285` lands; see `docs/reference/hooks.md`).
+
+**Runs independently of `SKIP_HOOKS`** — a user may pass `--no-hooks --with-permission-hook` (no governance hooks, but yes permission-bypass). If Step 8 was skipped and `.claude/settings.json` does not exist, create it here.
+
+**1. Confirm the trust decision (REQUIRED — security-sensitive).** Installing a permission-bypass hook is a trust decision, so confirm explicitly even though the flag was passed. Use **AskUserQuestion**:
+
+> **Install the Bulwark permission-bypass hook?**
+> It auto-approves Read/Edit/Bash on Bulwark's **own bundled assets** (under the plugin cache root / `${CLAUDE_PLUGIN_ROOT}`), so you stop seeing permission prompts for them. Everything else still prompts as normal. **Writes are never auto-approved.** Path-traversal that escapes the plugin root is denied. Requires trusting Bulwark at install level.
+>
+> Options: **Install** / **Skip**
+
+If the user picks **Skip** (or declines): do NOT install; set `PERMISSION_HOOK=declined`; continue to Step 9.
+
+**2. On Install:**
+
+  **a. Idempotency check.** If `.claude/settings.json` already registers `bulwark-permission-hook.sh` under `PreToolUse`, skip re-adding (set `PERMISSION_HOOK=already_present`) and proceed to step (c) to ensure the script copy exists.
+
+  **b. Merge the `PreToolUse` entry** into `.claude/settings.json` (create the file and/or the `hooks` key if absent; preserve all existing settings — same merge discipline as Step 8):
+
+  ```json
+  {
+    "hooks": {
+      "PreToolUse": [
+        {
+          "matcher": "Read|Edit|Bash",
+          "hooks": [
+            {
+              "type": "command",
+              "command": "${CLAUDE_PROJECT_DIR}/scripts/hooks/bulwark-permission-hook.sh",
+              "timeout": 5
+            }
+          ]
+        }
+      ]
+    }
+  }
+  ```
+
+  **c. Copy the hook script:** copy `scripts/hooks/bulwark-permission-hook.sh` to `${CLAUDE_PROJECT_DIR}/scripts/hooks/` and ensure it is executable (`chmod +x`). Create parent dirs with `mkdir -p`.
+
+  **d.** Set `PERMISSION_HOOK=installed`.
+
+**Why there is no env-var gate in the project entry:** the hook self-gates on `$CLAUDE_PLUGIN_OPTION_ENABLE_PERMISSION_BYPASS`, but project-scope installs do not set that var — the script treats an **unset** gate as **active** (`bulwark-permission-hook.sh` opt-in gate), so the entry's presence in `settings.json` IS the opt-in. (The env-var gate only matters for the plugin-level install, which defaults it to `false`.)
+
+**3. Record the choice** in the scaffold log (Step 9): add `scripts/hooks/bulwark-permission-hook.sh` to `reviewed_files` when copied, and set `actions.permission_hook.action` to the `PERMISSION_HOOK` value.
+
 ### Step 9: Write Scaffold Log
 
 Write to `logs/scaffold-{YYYYMMDD-HHMMSS}.yaml`:
@@ -410,6 +475,11 @@ actions:
     action: created|merged|skipped
     path: .claude/settings.json
     skipped_reason: {reason if skipped}
+  permission_hook:
+    # --with-permission-hook opt-in (Step 8a). not_requested when the flag is absent.
+    action: installed|declined|already_present|not_requested
+    path: .claude/settings.json
+    script: scripts/hooks/bulwark-permission-hook.sh
 
 summary: |
   Scaffold complete for {DETECTED_LANG} project.
@@ -427,6 +497,7 @@ Present summary to user:
 **logs/:** Created with subdirectories (diagnostics, validations, debug-reports)
 **.gitignore:** {updated|created|unchanged}
 **Hooks:** {created|merged|skipped (--no-hooks)}
+**Permission hook:** {installed|declined|already present|not installed}
 **Governance:** {installed|skipped} - Protocol injected at session start
 
 Run `just` to see available recipes:
@@ -469,6 +540,7 @@ invocation: "{full command}"
 inputs:
   force: {true|false}
   no_hooks: {true|false}
+  with_permission_hook: {true|false}
   dry_run: {true|false}
   lang_override: {value or null}
 detection:
@@ -479,5 +551,6 @@ outputs:
   logs_created: {true|false}
   gitignore_updated: {true|false}
   hooks_configured: {true|false}
+  permission_hook_configured: {true|false}
 errors: []
 ```

package/skills/bulwark-statusline/SKILL.md

@@ -6,9 +6,11 @@ argument-hint: "<init|minimal|developer|cost>"
 arguments: subcommand
 user-invocable: true
 allowed-tools:
+  - AskUserQuestion
   - Bash
-  - Read
   - Edit
+  - Read
+  - Task
 version: 1.0.2
 author: "Ashay Kubal @ Qball Inc."
 ---

package/skills/bulwark-verify/SKILL.md

@@ -6,6 +6,15 @@ skills:
   - assertion-patterns
   - component-patterns
   - bug-magnet-data
+allowed-tools:
+  - AskUserQuestion
+  - Bash
+  - Glob
+  - Grep
+  - Read
+  - Skill
+  - Task
+  - Write
 version: 1.0.1
 author: "Ashay Kubal @ Qball Inc."
 ---

package/skills/code-review/SKILL.md

@@ -5,7 +5,13 @@ user-invocable: true
 skills:
   - subagent-prompting
   - subagent-output-templating
-version: 1.1.0
+allowed-tools:
+  - Bash
+  - Glob
+  - Grep
+  - Read
+  - Write
+version: 1.2.0
 author: "Ashay Kubal @ Qball Inc."
 ---
 
@@ -43,6 +49,7 @@ This skill references supporting files. Understanding what's required vs optiona
 | **Pattern references** | `references/{section}-patterns.md` | **REQUIRED** | Always load for each enabled section |
 | **Framework patterns** | `frameworks/{detected}.md` | **CONDITIONALLY REQUIRED** | If framework detected → MUST load; if not detected → skip |
 | **Examples** | `examples/anti-patterns/*.ts`, `examples/recommended/*.ts` | OPTIONAL | For calibration on ambiguous cases; kept for model portability |
+| **Diagnostic schema** | `references/diagnostic-schema.md` | **REQUIRED for Phase 3** | When emitting the diagnostic log (full schema, field rules, examples, Stage-5 aggregation) |
 
 **Fallback behavior:**
 - If framework detected → Loading `frameworks/{name}.md` is REQUIRED
@@ -78,21 +85,31 @@ This skill references supporting files. Understanding what's required vs optiona
 **CRITICAL**: All three phases are REQUIRED. Do not skip any phase.
 
 ```
-Phase 1: Static Analysis (Deterministic)
-├── Run: just typecheck → capture output
-├── Run: just lint → capture output
-└── If failures: STOP, return to user (fail fast)
-
-Phase 2: LLM Review (Judgment-Based)
-├── Load references/{section}-patterns.md for each enabled section (REQUIRED)
+Phase 1: Static Analysis (Deterministic, language-aware)
+├── For each file in scope, detect language from extension → run matching recipe(s):
+│   ├── .ts/.tsx/.js/.jsx → just typecheck ; just lint
+│   ├── .py               → just typecheck-py ; just lint-py
+│   ├── .sh/.bash         → just lint          (shellcheck)
+│   ├── .json             → just validate-json
+│   ├── .yaml/.yml        → just validate-yaml
+│   └── (other/unknown)   → just typecheck ; just lint  (project default)
+├── Tool present AND reports problems → STOP, return to user (fail fast)
+└── Tool absent (recipe prints "… not installed; skipping") → log warning, continue (graceful degrade)
+
+Phase 2: LLM Review (Judgment-Based, applicability-gated)
+├── Detect each file's language (extends Framework Detection — same mechanism, per-file)
+├── For each (section, language): consult the Language Applicability table
+│   ├── ✅ apply normally · partial apply + Caveat · ❌ skip (record skip_rationale)
+├── Load references/{section}-patterns.md for each APPLIED section (REQUIRED)
 ├── If framework detected: Load frameworks/{detected}.md (REQUIRED)
 ├── If no framework detected: Skip framework patterns
-├── Apply each enabled section using loaded patterns
+├── Apply each applied section using loaded patterns
 └── Output findings to user
 
 Phase 3: Write Diagnostic Log (REQUIRED)
 ├── Write to: logs/diagnostics/code-review-{timestamp}.yaml
-├── Include: invocation details, static analysis results, findings summary
+├── Include: invocation details, static analysis results, findings summary,
+│            language_applicability (per-file applied/skipped sections)
 └── This phase is MANDATORY - do not return to user without completing it
 ```
 
@@ -121,6 +138,25 @@ Each section is independently referenceable by pipeline agents via `--section=<n
 | Linting | Style requiring judgment | Complexity, naming, structure | Important-Suggestion |
 | Coding Standards | Conventions & architecture | Patterns, documentation | Important-Suggestion |
 
+### Language Applicability
+
+Not every section applies to every language. Before running a section on a file, detect the file's language (see [Framework Detection](#framework-detection)) and consult this table. This prevents hallucinated findings (e.g., "type safety" on a bash script) and wasted passes.
+
+| Section | TS/JS | Python | Bash | JSON/YAML | Rust | Go | Java/Kotlin | Reason |
+|---------|-------|--------|------|-----------|------|-----|-------------|--------|
+| **Security** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | OWASP concepts are language-agnostic |
+| **Type Safety** | ✅ | partial | ❌ | ❌ | ✅ | ✅ | ✅ | TS/Python/Rust/Go/JVM have type systems; bash + data formats don't |
+| **Linting** | ✅ | ✅ | ✅ if shellcheck | partial | ✅ if clippy | ✅ if golangci-lint | ✅ if ktlint | Always conceptually applicable; tool varies |
+| **Coding Standards** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | CS1–CS4 from Rules.md are language-agnostic |
+
+**Section-selection rule** — for each file in scope:
+1. Detect language from file extension (this extends [Framework Detection](#framework-detection) — same mechanism, file-level granularity).
+2. For each of the 4 sections, look up the (section, language) cell:
+   - **✅** — apply the section normally.
+   - **partial** — apply with reduced scope and attach a `Caveat` to any finding (e.g., Python type hints are optional, not enforced; data formats have schema-shaped structure, not a type system).
+   - **❌** — skip the section; record the file + skipped section in the Phase 3 diagnostic's `language_applicability.sections_skipped` with a `skip_rationale`.
+3. Record applied + skipped sections per file in the Phase 3 diagnostic (`language_applicability` field — see [Diagnostic Output](#diagnostic-output-required)).
+
 ---
 
 ## Security
@@ -298,6 +334,26 @@ fastapi                   → fastapi
 (none of above)           → (no framework)
 ```
 
+### Language Detection (Per-File)
+
+Framework detection above is **project-level** (which `frameworks/{name}.md` to load). Language detection is **file-level**: it drives the Phase 1 recipe to run and the Language Applicability lookup (which sections apply). It **extends** this mechanism — same detection pass, finer granularity — rather than introducing a parallel detection paradigm.
+
+```
+extension                        → language
+──────────────────────────────────────────────
+.ts .tsx .js .jsx .mjs .cjs      → typescript/javascript
+.py .pyi                         → python
+.sh .bash                        → bash
+.json                            → json   (data format)
+.yaml .yml                       → yaml   (data format)
+.rs                              → rust
+.go                              → go
+.java .kt .kts                   → java/kotlin
+(unrecognized)                   → project default (apply all sections)
+```
+
+For each file: detect language → run the matching Phase 1 recipe → gate each section through the [Language Applicability](#language-applicability) table.
+
 ### Override
 Use `--framework=<name>` to override detection.
 
@@ -393,86 +449,13 @@ Write diagnostic output to:
 logs/diagnostics/code-review-{timestamp}.yaml
 ```
 
-Format:
-```yaml
-diagnostic:
-  skill: code-review
-  timestamp: 2026-01-31T12:00:00Z
-  invocation:
-    mode: comprehensive | quick
-    sections_run: [security, type_safety, linting, standards]
-    framework_detected: react
-    framework_override: null
-    files_count: 5
-    lines_total: 450
-  static_analysis:
-    typecheck: passed | failed | skipped
-    lint: passed | failed | skipped
-  findings_summary:
-    critical: 1
-    important: 3
-    suggestion: 5
-  duration_ms: 1200
-# Files reviewed (top-level field — consumed by the Stop hook for per-file
-# pipeline-recursion suppression). MUST be a flat list of paths relative
-# to ${CLAUDE_PROJECT_DIR}. Empty list `[]` is valid if the diagnostic
-# was emitted with no specific file scope. Missing field = strict mode
-# disables suppression for this log.
-reviewed_files:
-  - src/auth/token.ts
-  - src/api/users.ts
-
-# Followup edits expected (top-level field — consumed by the Stop hook
-# grace-window logic, P10.22). OPTIONAL list-of-mappings. Emit one entry
-# per file that received at least one critical or important finding.
-# Subsequent edits to a listed file within grace_window_seconds of this
-# log being written are treated as pre-covered (no re-fire).
-followup_edits_expected:
-  - file: src/auth/token.ts
-    grace_window_seconds: 1800
-    finding_ids: [SEC-001]
-    rationale: "1 critical (SQL injection); user-applied fix expected within grace window"
-```
-
----
-
-## Followup Edits Expected (Stop Hook Grace Window — P10.22)
-
-**Purpose**: When a code-review run produces actionable findings (severity `critical` or `important`), the user typically applies fixes immediately after reviewing the output. Without this metadata, those fix-edits trigger a fresh Stop hook fire because the pipeline log was written BEFORE the fix-edits — recursion. The `followup_edits_expected` field tells the Stop hook coverage check that edits to the listed files within the grace window are pre-covered.
-
-**When to emit** — emit one entry per file with at least one finding of severity `critical` or `important`. Files with `suggestion`-only findings do NOT need a followup entry (suggestions are cosmetic and user-driven).
-
-**Field schema**:
-- `file` (required) — path relative to `${CLAUDE_PROJECT_DIR}`. Must match exactly the path used in `reviewed_files` for the same file.
-- `grace_window_seconds` (optional, default 1800) — duration in seconds after this log is written during which subsequent edits to the file are treated as covered. 1800 (30 min) accommodates user deliberation + multi-fix application.
-- `finding_ids` (optional, informational) — list of finding identifiers driving the followup expectation. Used for diagnostic clarity; not consulted by coverage logic.
-- `rationale` (optional, informational) — human-readable explanation. Surfaced in diagnostic output.
-
-**When NOT to emit** — if a review pass produces zero `critical` or `important` findings, omit the field entirely (or emit `followup_edits_expected: []`). Suggestions-only output should NOT register followup expectations.
-
-**Example**:
-```yaml
-followup_edits_expected:
-  - file: src/auth/token.ts
-    grace_window_seconds: 1800
-    finding_ids: [SEC-001]
-    rationale: "1 critical SQL injection finding; user-applied fix expected"
-  - file: src/api/users.ts
-    grace_window_seconds: 1800
-    finding_ids: [TYPE-001, SEC-002]
-    rationale: "1 important type-safety + 1 important auth check"
-```
-
-**Pipeline-stage emission**: when code-review runs as a pipeline (`SecurityReviewer |> TypeSafetyReviewer |> LintReviewer |> StandardsReviewer |> ReviewSynthesizer`), each section reviewer emits its own `followup_edits_expected` in its sectional output (per `templates/output-pipeline.yaml`). The orchestrator's Stage 5 ReviewSynthesizer aggregates across all 4 reviewer logs into the consolidated `logs/diagnostics/code-review-{timestamp}.yaml`.
-
-**Stage 5 aggregation algorithm** — consolidate the 4 sectional `followup_edits_expected` lists into one top-level list:
-1. **Group by `file`** (string equality on path). For each unique file mentioned in any of the 4 reviewer logs:
-2. **Union `finding_ids`** across all reviewer entries for that file (deduplicate; preserve order: security first, then type_safety, linting, standards).
-3. **Max `grace_window_seconds`** — take the largest grace window declared by any reviewer for that file. Reviewers with stricter (smaller) windows are subsumed by reviewers with longer windows.
-4. **Concatenate `rationale`** with `; ` separator, prefixed by section name (e.g., `"security: 1 critical (SQL inj); type_safety: 1 important (any usage)"`).
-5. **Skip files with zero entries** — if no reviewer emitted a followup for a file, do not include it in the synthesized list.
+The log MUST include these top-level fields:
+- `diagnostic` — skill / timestamp / invocation / static_analysis / findings_summary.
+- `reviewed_files` — flat list of reviewed paths relative to `${CLAUDE_PROJECT_DIR}` (Stop-hook per-file suppression contract; `[]` is valid, missing field = strict no-suppress).
+- `language_applicability` (P10.21) — per-file `detected_language` + `sections_applied` / `sections_skipped` (+ `skip_rationale`); record `partial` by suffixing the section (e.g. `type_safety_partial`).
+- `followup_edits_expected` (P10.22) — one entry per file with a `critical`/`important` finding; omit or `[]` for suggestions-only runs.
 
-Emit the aggregated list as the top-level `followup_edits_expected` field of the synthesis log. The Stop hook's `coverage_check.py:parse_followup_edits_expected()` reads this consolidated field directly; per-reviewer logs are also scanned independently, so partial coverage is preserved if synthesis is skipped.
+**Full schema, field rules, worked examples, and the pipeline Stage-5 aggregation algorithm live in [`references/diagnostic-schema.md`](references/diagnostic-schema.md) — load it when emitting Phase 3 output.**
 
 ---
 

package/skills/code-review/references/diagnostic-schema.md

@@ -0,0 +1,119 @@
+# Diagnostic Schema (Phase 3 Output)
+
+Full schema, field rules, and examples for the code-review Phase 3 diagnostic log. Load this when emitting diagnostic output. The SKILL.md `## Diagnostic Output` section carries the binding contract (where to write + which top-level fields are mandatory); this file is the detailed reference.
+
+Write diagnostic output to: `logs/diagnostics/code-review-{timestamp}.yaml` (ISO-8601 timestamp, hyphens for filename safety).
+
+---
+
+## Full Format
+
+```yaml
+diagnostic:
+  skill: code-review
+  timestamp: 2026-01-31T12:00:00Z
+  invocation:
+    mode: comprehensive | quick
+    sections_run: [security, type_safety, linting, standards]
+    framework_detected: react
+    framework_override: null
+    files_count: 5
+    lines_total: 450
+  static_analysis:
+    typecheck: passed | failed | skipped
+    lint: passed | failed | skipped
+  findings_summary:
+    critical: 1
+    important: 3
+    suggestion: 5
+  duration_ms: 1200
+
+# Files reviewed (top-level field — consumed by the Stop hook for per-file
+# pipeline-recursion suppression). MUST be a flat list of paths relative
+# to ${CLAUDE_PROJECT_DIR}. Empty list `[]` is valid if the diagnostic
+# was emitted with no specific file scope. Missing field = strict mode
+# disables suppression for this log.
+reviewed_files:
+  - src/auth/token.ts
+  - src/api/users.ts
+
+# Language applicability (top-level field — P10.21). Per-file record of which
+# review sections were applied vs skipped, the detected language, and a rationale
+# for any skip. Lets pipeline orchestration + audits confirm that, e.g., Type
+# Safety was deliberately skipped on a bash file rather than silently missed.
+# `partial` is recorded by suffixing the section name (e.g., type_safety_partial).
+language_applicability:
+  - file: scripts/foo.py
+    detected_language: python
+    sections_applied: [security, type_safety_partial, linting, standards]
+    sections_skipped: []
+  - file: scripts/foo.sh
+    detected_language: bash
+    sections_applied: [security, linting, standards]
+    sections_skipped: [type_safety]
+    skip_rationale: "Bash has no static type system"
+
+# Followup edits expected (top-level field — consumed by the Stop hook
+# grace-window logic, P10.22). OPTIONAL list-of-mappings. Emit one entry
+# per file that received at least one critical or important finding.
+# Subsequent edits to a listed file within grace_window_seconds of this
+# log being written are treated as pre-covered (no re-fire).
+followup_edits_expected:
+  - file: src/auth/token.ts
+    grace_window_seconds: 1800
+    finding_ids: [SEC-001]
+    rationale: "1 critical (SQL injection); user-applied fix expected within grace window"
+```
+
+---
+
+## Followup Edits Expected (Stop Hook Grace Window — P10.22)
+
+**Purpose**: When a code-review run produces actionable findings (severity `critical` or `important`), the user typically applies fixes immediately after reviewing the output. Without this metadata, those fix-edits trigger a fresh Stop hook fire because the pipeline log was written BEFORE the fix-edits — recursion. The `followup_edits_expected` field tells the Stop hook coverage check that edits to the listed files within the grace window are pre-covered.
+
+**When to emit** — emit one entry per file with at least one finding of severity `critical` or `important`. Files with `suggestion`-only findings do NOT need a followup entry (suggestions are cosmetic and user-driven).
+
+**Field schema**:
+- `file` (required) — path relative to `${CLAUDE_PROJECT_DIR}`. Must match exactly the path used in `reviewed_files` for the same file.
+- `grace_window_seconds` (optional, default 1800) — duration in seconds after this log is written during which subsequent edits to the file are treated as covered. 1800 (30 min) accommodates user deliberation + multi-fix application.
+- `finding_ids` (optional, informational) — list of finding identifiers driving the followup expectation. Used for diagnostic clarity; not consulted by coverage logic.
+- `rationale` (optional, informational) — human-readable explanation. Surfaced in diagnostic output.
+
+**When NOT to emit** — if a review pass produces zero `critical` or `important` findings, omit the field entirely (or emit `followup_edits_expected: []`). Suggestions-only output should NOT register followup expectations.
+
+**Example**:
+```yaml
+followup_edits_expected:
+  - file: src/auth/token.ts
+    grace_window_seconds: 1800
+    finding_ids: [SEC-001]
+    rationale: "1 critical SQL injection finding; user-applied fix expected"
+  - file: src/api/users.ts
+    grace_window_seconds: 1800
+    finding_ids: [TYPE-001, SEC-002]
+    rationale: "1 important type-safety + 1 important auth check"
+```
+
+**Pipeline-stage emission**: when code-review runs as a pipeline (`SecurityReviewer |> TypeSafetyReviewer |> LintReviewer |> StandardsReviewer |> ReviewSynthesizer`), each section reviewer emits its own `followup_edits_expected` in its sectional output (per `templates/output-pipeline.yaml`). The orchestrator's Stage 5 ReviewSynthesizer aggregates across all 4 reviewer logs into the consolidated `logs/diagnostics/code-review-{timestamp}.yaml`.
+
+**Stage 5 aggregation algorithm** — consolidate the 4 sectional `followup_edits_expected` lists into one top-level list:
+1. **Group by `file`** (string equality on path). For each unique file mentioned in any of the 4 reviewer logs:
+2. **Union `finding_ids`** across all reviewer entries for that file (deduplicate; preserve order: security first, then type_safety, linting, standards).
+3. **Max `grace_window_seconds`** — take the largest grace window declared by any reviewer for that file. Reviewers with stricter (smaller) windows are subsumed by reviewers with longer windows.
+4. **Concatenate `rationale`** with `; ` separator, prefixed by section name (e.g., `"security: 1 critical (SQL inj); type_safety: 1 important (any usage)"`).
+5. **Skip files with zero entries** — if no reviewer emitted a followup for a file, do not include it in the synthesized list.
+
+Emit the aggregated list as the top-level `followup_edits_expected` field of the synthesis log. The Stop hook's `coverage_check.py:parse_followup_edits_expected()` reads this consolidated field directly; per-reviewer logs are also scanned independently, so partial coverage is preserved if synthesis is skipped.
+
+---
+
+## Language Applicability (P10.21)
+
+Per-file record of which review sections ran. Shape:
+- `file` — path relative to `${CLAUDE_PROJECT_DIR}` (match `reviewed_files`).
+- `detected_language` — from file extension (see SKILL.md `## Framework Detection` → Language Detection).
+- `sections_applied` — list of applied sections; record `partial` applicability by suffixing the section name (e.g., `type_safety_partial`).
+- `sections_skipped` — list of skipped sections.
+- `skip_rationale` (when any section skipped) — one-line reason (e.g., `"Bash has no static type system"`).
+
+In **pipeline-stage** output (`templates/output-pipeline.yaml`), each reviewer records ITS single section's per-file `decision` (applied | partial | skipped); ReviewSynthesizer (Stage 5) consolidates these into the `sections_applied`/`sections_skipped` shape above.

package/skills/component-patterns/SKILL.md

@@ -2,6 +2,9 @@
 name: component-patterns
 description: Per-component-type verification approaches. Use when generating verification scripts for different component types.
 user-invocable: false
+allowed-tools:
+  - Read
+  - Write
 version: 1.0.0
 author: "Ashay Kubal @ Qball Inc."
 ---

package/skills/continuous-feedback/SKILL.md

@@ -5,6 +5,15 @@ user-invocable: true
 argument-hint: "<target-skill-or-path> [--sources <paths>] [--since <session-N>]"
 skills:
   - subagent-prompting
+allowed-tools:
+  - AskUserQuestion
+  - Bash
+  - Glob
+  - Grep
+  - Read
+  - Skill
+  - Task
+  - Write
 version: 1.0.0
 author: "Ashay Kubal @ Qball Inc."
 ---

package/skills/create-skill/SKILL.md

@@ -1,5 +1,14 @@
 ---
 name: create-skill
+allowed-tools:
+  - AskUserQuestion
+  - Bash
+  - Glob
+  - Grep
+  - Read
+  - Skill
+  - Task
+  - Write
 version: 1.2.5
 author: "Ashay Kubal @ Qball Inc."
 description: Generates Claude Code skills from requirements using adaptive interview, complexity classification, and iterative validation. Use when creating new skills, scaffolding skill structure, or generating skills with sub-agent orchestration.

package/skills/create-subagent/SKILL.md

@@ -6,6 +6,13 @@ argument-hint: "<description-or-name> [--doc <requirements-path>]"
 skills:
   - subagent-prompting
   - anthropic-validator
+allowed-tools:
+  - AskUserQuestion
+  - Bash
+  - Read
+  - Skill
+  - Task
+  - Write
 version: 1.0.0
 author: "Ashay Kubal @ Qball Inc."
 ---

package/skills/fix-bug/SKILL.md

@@ -2,6 +2,10 @@
 name: fix-bug
 description: Run the Fix Validation pipeline to investigate, fix, and validate a bug. Ensures deterministic pipeline execution with IssueAnalyzer, FixWriter, TestWriter (conditional), TestAudit (conditional), and FixValidator stages.
 user-invocable: true
+allowed-tools:
+  - Read
+  - Skill
+  - Task
 version: 1.0.0
 author: "Ashay Kubal @ Qball Inc."
 ---

package/skills/governance-protocol/SKILL.md

@@ -2,6 +2,7 @@
 name: governance-protocol
 description: Session governance protocol injected at startup via SessionStart hook
 user-invocable: false
+allowed-tools: []
 version: 1.0.0
 author: "Ashay Kubal @ Qball Inc."
 ---

package/skills/init/SKILL.md

@@ -3,6 +3,12 @@ name: init
 description: Initialize, verify, or update Bulwark governance in a project. Sets up CLAUDE.md, rules.md, and optional tooling (statusline, LSP, scaffold). --update reviews canonical template changes interactively per-section.
 user-invocable: true
 argument-hint: "[--scope=project|user] [--verify | --update] [target-dir]"
+allowed-tools:
+  - AskUserQuestion
+  - Bash
+  - Read
+  - Skill
+  - Write
 version: 1.2.0
 author: "Ashay Kubal @ Qball Inc."
 ---

package/skills/issue-debugging/SKILL.md

@@ -2,6 +2,9 @@
 name: issue-debugging
 description: Systematic methodology for issue debugging including root cause analysis, impact mapping, tiered validation plans, and confidence assessment. Use when analyzing bugs, fixing issues, or validating fixes.
 user-invocable: false
+allowed-tools:
+  - Read
+  - Write
 version: 1.0.0
 author: "Ashay Kubal @ Qball Inc."
 ---

package/skills/mock-detection/SKILL.md

@@ -2,6 +2,11 @@
 name: mock-detection
 description: Deep mock appropriateness analysis for Test Audit pipeline
 user-invocable: false
+allowed-tools:
+  - Bash
+  - Read
+  - Task
+  - Write
 version: 1.0.1
 author: "Ashay Kubal @ Qball Inc."
 ---