@qball-inc/the-bulwark 1.2.0 → 1.3.0

package/.claude-plugin/plugin.json

@@ -1,42 +1,50 @@
-{
-  "name": "the-bulwark",
-  "version": "1.2.0",
-  "description": "Full-lifecycle SDLC guardrailing framework for Claude Code — from product ideation and planning through implementation, code review, and test validation. Enterprise-grade skills and agents for AI-human peer collaboration.",
-  "author": {
-    "name": "Ashay Kubal",
-    "url": "https://ashaykubal.com"
-  },
-  "homepage": "https://github.com/QBall-Inc",
-  "repository": "https://github.com/QBall-Inc/the-bulwark",
-  "license": "MIT",
-  "keywords": [
-    "claude-code",
-    "claude-code-plugin",
-    "sdlc",
-    "quality-enforcement",
-    "code-review",
-    "testing",
-    "governance",
-    "hooks",
-    "skills",
-    "agents",
-    "pipeline",
-    "ideation",
-    "product-ideation",
-    "product-management",
-    "market-research",
-    "competitive-research",
-    "brainstorming",
-    "brainstorm",
-    "planning",
-    "plan-creation",
-    "agent-design",
-    "skill-design",
-    "create-skill",
-    "create-agent",
-    "test-audit",
-    "test-coverage",
-    "statusline",
-    "agent-teams"
-  ]
-}
+{
+  "name": "the-bulwark",
+  "version": "1.3.0",
+  "description": "Full-lifecycle SDLC guardrailing framework for Claude Code — from product ideation and planning through implementation, code review, and test validation. Enterprise-grade skills and agents for AI-human peer collaboration.",
+  "author": {
+    "name": "Ashay Kubal",
+    "url": "https://ashaykubal.com"
+  },
+  "homepage": "https://github.com/QBall-Inc",
+  "repository": "https://github.com/QBall-Inc/the-bulwark",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "sdlc",
+    "quality-enforcement",
+    "code-review",
+    "testing",
+    "governance",
+    "hooks",
+    "skills",
+    "agents",
+    "pipeline",
+    "ideation",
+    "product-ideation",
+    "product-management",
+    "market-research",
+    "competitive-research",
+    "brainstorming",
+    "brainstorm",
+    "planning",
+    "plan-creation",
+    "agent-design",
+    "skill-design",
+    "create-skill",
+    "create-agent",
+    "test-audit",
+    "test-coverage",
+    "statusline",
+    "agent-teams"
+  ],
+  "userConfig": {
+    "enable_permission_bypass": {
+      "type": "boolean",
+      "title": "Auto-approve Bulwark bundled-asset access",
+      "description": "Skip permission prompts for Bulwark's own plugin scripts and bundled files (Read/Edit/Bash inside the plugin root). Writes and non-Bulwark paths are never auto-approved; path-traversal escapes are denied. Requires trusting Bulwark at install level. Default: off.",
+      "default": false
+    }
+  }
+}

package/CHANGELOG.md

@@ -15,54 +15,124 @@ No unreleased changes at this time.
 
 ---
 
+## [1.3.0] - 2026-06-23
+
+Fewer prompts, sharper reviews. This release cuts permission-prompt friction for
+Bulwark's own bundled assets, makes the `code-review` skill language-aware so it
+only runs checks that apply to each file, and adds an opt-in hook that
+auto-approves tool calls scoped to the plugin's own files.
+
+### Added
+
+- **Opt-in permission-bypass hook** (`bulwark-permission-hook.sh`, PreToolUse) —
+  auto-approves Read/Edit/Bash calls whose targets resolve **inside the plugin's
+  own cache root**, so Bulwark's bundled skills and agents stop prompting for
+  access to their own files. Off by default and never auto-installed; opt in per
+  project via `bulwark-scaffold --with-permission-hook`. Path-traversal that
+  spoofs a plugin prefix but escapes the root is blocked, and any target outside
+  the plugin cache (for example `/etc/passwd` or a network `curl`) still prompts
+  normally. Documented as a separate, default-off hook — the always-on set
+  remains eight hooks.
+- **`bulwark-scaffold --with-permission-hook` flag** — installs the opt-in
+  permission hook at project scope during scaffolding.
+- **Universal per-language `code-review` recipes** across all eight Justfile
+  templates and the root Justfile — `typecheck-py`, `lint-py`, `validate-json` /
+  `validate-yaml`, and `shellcheck`. Each recipe degrades gracefully: it skips
+  and exits 0 when the underlying tool is absent, and propagates the tool's exit
+  status when present.
+
+### Changed
+
+- **`code-review` skill is now language-aware** — it detects each changed file's
+  language and gates review sections via a Language Applicability table, so it
+  runs only the checks relevant to the files under review instead of assuming a
+  single stack.
+- **`allowed-tools` declared on all 30 skills; `tools` audited on all 15
+  agents** — every skill now pre-authorizes exactly the tools it needs, removing
+  routine permission prompts during normal skill execution. (`allowed-tools`
+  *pre-authorizes*, it does not restrict; `disallowed-tools` remains the
+  restriction field.)
+
+---
+
+## [1.2.1] - 2026-05-17
+
+Hotfix for SessionStart and Stop hooks failing with `Permission denied` on
+fresh v1.2.0 installs.
+
+### Fixed
+
+- **Hook scripts shipped without executable bit** — three hooks
+  (`cleanup-review-registry.sh`, `check-template-drift.sh`,
+  `suggest-pipeline-stop.sh`) were stored in the v1.2.0 tree at mode `100644`
+  instead of `100755`, causing the Claude Code plugin runtime to fail with
+  `Permission denied` on direct execve. Five additional non-hook scripts shared
+  the same defect but were invoked via `bash <path>` wrappers and unaffected
+  at the user level. Root cause: the release sync workflow ran with
+  `core.fileMode = false` (inherited from the WSL/NTFS development repo via
+  worktree config sharing), causing `git add` to stage new `.sh` files at the
+  default mode `100644`. *(GitHub issue [#1](https://github.com/QBall-Inc/the-bulwark/issues/1))*
+- **`sync-to-public.sh` mode preservation** — the publish script now scans
+  every tracked `.sh` file in the staging worktree and calls
+  `git update-index --chmod=+x` on each, bypassing `core.fileMode` entirely.
+  Idempotent and safe under any local git config.
+
+### Upgrade notes
+
+For users on a fresh v1.2.0 install affected by the hook failure, upgrading
+to v1.2.1 via `/plugin update the-bulwark@qball-inc` (or a fresh install) will
+restore correct hook execution. No project-level changes required.
+
+---
+
 ## [1.2.0] - 2026-05-17
 
-Hardening + observability bundle covering 13+ phases of post-launch reliability,
+Hardening and observability bundle covering post-launch reliability,
 governance, and tooling enhancements built between v1.1.0 and v1.2.0.
 
 ### Added
 
-- **`plan-to-tasks` skill** — transforms `plan-creation` output into CLEAR-compatible execution structure (`tasks.yaml` + `workpackages/`). Supports parent/child plan linkage. *(P10.5)*
-- **`spec-drift-check` skill** — audits work package briefs, plan docs, and memory entries for drift against current code state. Extracts claims, verifies each, emits PROCEED/STOP verdict with a structured verification log. *(P10.18)*
-- **`SD1` (Spec Drift) rule** in `Rules.md` — mandatory pre-WP drift check before any new or resumed implementation. *(P10.18, P10.20)*
-- **`init --update` mode** — guided drift remediation for stale `CLAUDE.md` / `Rules.md` sections. Batched/tabbed `AskUserQuestion` UX for ≥4 drifting sections. Parent/child anchor handling. *(P10.20, P10.24, P10.25)*
-- **`check-template-drift.sh` SessionStart hook** — detects when project's `CLAUDE.md` or `Rules.md` have drifted from canonical templates and surfaces them for review. *(P10.20)*
-- **`cleanup-review-registry.sh` SessionStart hook** — wipes stale review-accumulator state at session start so pipeline gating works across sessions. *(P10.16)*
-- **`.bulwark/init-marker.yaml`** — written on first `/the-bulwark:init` run; consumed by `check-template-drift.sh` to scope drift detection. *(P10.20)*
-- **`install-bun.sh`** — platform-aware, idempotent bun runtime installer (preparation for the evaluation framework). *(P10.11)*
-- **Justfile recipes for evaluation framework** — `install-bun`, `verify-bun`, `eval-skill`, `eval-grade`, `eval`. *(P10.14)*
+- **`plan-to-tasks` skill** — transforms `plan-creation` output into an execution-ready structure (`tasks.yaml` + `workpackages/`). Supports parent/child plan linkage.
+- **`spec-drift-check` skill** — audits work package briefs, plan docs, and memory entries for drift against current code state. Extracts claims, verifies each, emits PROCEED/STOP verdict with a structured verification log.
+- **`SD1` (Spec Drift) rule** in `Rules.md` — mandatory pre-WP drift check before any new or resumed implementation.
+- **`init --update` mode** — guided drift remediation for stale `CLAUDE.md` / `Rules.md` sections. Batched/tabbed `AskUserQuestion` UX for ≥4 drifting sections. Parent/child anchor handling.
+- **`check-template-drift.sh` SessionStart hook** — detects when project's `CLAUDE.md` or `Rules.md` have drifted from canonical templates and surfaces them for review.
+- **`cleanup-review-registry.sh` SessionStart hook** — wipes stale review-accumulator state at session start so pipeline gating works across sessions.
+- **`.bulwark/init-marker.yaml`** — written on first `/the-bulwark:init` run; consumed by `check-template-drift.sh` to scope drift detection.
+- **`install-bun.sh`** — platform-aware, idempotent bun runtime installer (preparation for the evaluation framework).
+- **Justfile recipes for evaluation framework** — `install-bun`, `verify-bun`, `eval-skill`, `eval-grade`, `eval`.
 
 ### Changed
 
-- **`Stop` hook (`suggest-pipeline-stop.sh`)** — re-architected with per-file registry, file-type-aware pipeline routing, log-pattern suppression, and post-fix grace period. Reduces false-positive pipeline suggestions on doc-only or test-only changes. *(P10.12, P10.15, P10.19, P10.22)*
-- **`PostToolUse` matcher** widened from `Write|Edit` to `Write|Edit|MultiEdit` — quality enforcement now applies to all three mutation tools. *(P10.16)*
-- **`enforce-quality.sh`** — defensive `jq` fallback for malformed stdin, symlink rejection on accumulator write, atomic registry writes. *(P10.16)*
-- **`code-review` skill** — hook output schema validation, file-type-aware pipeline mapping, grace-window coverage aggregation. *(P10.10, P10.19, P10.22)*
-- **`test-audit` skill** — schema migration, grace-window coverage. *(P10.10, P10.22)*
-- **`plan-creation` and `bulwark-brainstorm`** — Agent Teams mode synthesis-gate fixes (CC-ALL, Work-Complete, Re-Entry gates). Resolves premature synthesis exit in dual-mode pipelines. *(P10.6)*
-- **`anthropic-validator`** — `SKILL.md` refactored to ≤500 lines, per-asset-type detail pushed to `references/`. Added `when_to_use` frontmatter for clearer triggering. *(P10.13)*
-- **`bulwark-statusline`** — uses `--no-optional-locks` to avoid `.git/index.lock` contention. *(P10.16)*
+- **`Stop` hook (`suggest-pipeline-stop.sh`)** — re-architected with per-file registry, file-type-aware pipeline routing, log-pattern suppression, and post-fix grace period. Reduces false-positive pipeline suggestions on doc-only or test-only changes.
+- **`PostToolUse` matcher** widened from `Write|Edit` to `Write|Edit|MultiEdit` — quality enforcement now applies to all three mutation tools.
+- **`enforce-quality.sh`** — defensive `jq` fallback for malformed stdin, symlink rejection on accumulator write, atomic registry writes.
+- **`code-review` skill** — hook output schema validation, file-type-aware pipeline mapping, grace-window coverage aggregation.
+- **`test-audit` skill** — schema migration, grace-window coverage.
+- **`plan-creation` and `bulwark-brainstorm`** — Agent Teams mode synthesis-gate fixes (CC-ALL, Work-Complete, Re-Entry gates). Resolves premature synthesis exit in dual-mode pipelines.
+- **`anthropic-validator`** — `SKILL.md` refactored to ≤500 lines, per-asset-type detail pushed to `references/`. Added `when_to_use` frontmatter for clearer triggering.
+- **`bulwark-statusline`** — uses `--no-optional-locks` to avoid `.git/index.lock` contention.
 
 ### Fixed
 
-- **`init --update`: parent/child anchor duplicate** — when both a top-level (`## Section`) and a nested (`### Subsection`) anchor drifted, the child was applied twice (once at EOF via fallback, once nested under parent). Fix suppresses child drift entries when their canonical parent is also drifting; parent's section extraction naturally brings nested children along. *(P10.25, BUG-S11-APPLY-001)*
-- **`init --update`: CRLF handling** — `apply-section.sh` now uses POSIX `sub(/\r$/, "")` for cross-platform CRLF stripping (gawk + mawk + BSD awk on macOS). Replaces `RS = "\r?\n"` which is gawk-only. *(P10.24)*
-- **`init --update`: early-exit on FALLBACK** — `apply-section.sh` no longer crashes on predecessor-lookup failure; cleanly falls through to EOF append path. *(P10.24)*
-- **`update.sh` and `check-template-drift.sh`: parallel CRLF risk** — same POSIX `sub(/\r$/, "")` pattern applied to all three scripts. *(P10.24)*
-- **`scripts/update.sh`: flag-prefix anchors** — `grep -Fxq --` end-of-options separator + herestring conversion prevent flag-shaped anchor names (`-n`, `-e`, `-E` prefixes) from being misinterpreted as command flags. *(P10.25, CR-SYN-001)*
-- **`bulwark-statusline`**: 3 anthropic-validator findings on frontmatter clarity. *(S119)*
+- **`init --update`: parent/child anchor duplicate** — when both a top-level (`## Section`) and a nested (`### Subsection`) anchor drifted, the child was applied twice (once at EOF via fallback, once nested under parent). Fix suppresses child drift entries when their canonical parent is also drifting; parent's section extraction naturally brings nested children along.
+- **`init --update`: CRLF handling** — `apply-section.sh` now uses POSIX `sub(/\r$/, "")` for cross-platform CRLF stripping (gawk + mawk + BSD awk on macOS). Replaces `RS = "\r?\n"` which is gawk-only.
+- **`init --update`: early-exit on FALLBACK** — `apply-section.sh` no longer crashes on predecessor-lookup failure; cleanly falls through to EOF append path.
+- **`update.sh` and `check-template-drift.sh`: parallel CRLF risk** — same POSIX `sub(/\r$/, "")` pattern applied to all three scripts.
+- **`scripts/update.sh`: flag-prefix anchors** — `grep -Fxq --` end-of-options separator + herestring conversion prevent flag-shaped anchor names (`-n`, `-e`, `-E` prefixes) from being misinterpreted as command flags.
+- **`bulwark-statusline`**: 3 anthropic-validator findings on frontmatter clarity.
 
 ### Security
 
-- **Path validation hardening** in `suggest-pipeline-stop.sh` and `cleanup-review-registry.sh` — symlink rejection on registry write, file-size caps, atomic-write guarantee. *(P10.15 self-test, S116-S117)*
-- **Environment variable validation** in registry-emitting hooks (`SEC-005`, `SEC-007`). *(P10.15)*
-- **`grep`/`sed`/`awk` end-of-options separator (`--`)** for user-controlled values, defending against flag-prefix attack vectors. *(P10.25)*
+- **Path validation hardening** in `suggest-pipeline-stop.sh` and `cleanup-review-registry.sh` — symlink rejection on registry write, file-size caps, atomic-write guarantee.
+- **Environment variable validation** in registry-emitting hooks.
+- **`grep`/`sed`/`awk` end-of-options separator (`--`)** for user-controlled values, defending against flag-prefix attack vectors.
 
 ---
 
 ## [1.1.0] - 2026-04-21
 
-P10.1 — Stop hook redesign + Justfile infrastructure rollout.
+Stop hook redesign + Justfile infrastructure rollout.
 
 ### Added
 
@@ -73,7 +143,7 @@ P10.1 — Stop hook redesign + Justfile infrastructure rollout.
 ### Changed
 
 - **Plugin manifest** (`.claude-plugin/plugin.json`) — adopted minimal schema; removed redundant `skills`/`agents`/`hooks` arrays now that Claude Code auto-discovers them. Resolves duplicate-hooks loading error reported by early users.
-- **`Stop` hook output** — removed invalid `hookSpecificOutput` field that violated the Claude Code hook JSON schema. *(P10.10 root-cause-of-symptom)*
+- **`Stop` hook output** — removed invalid `hookSpecificOutput` field that violated the Claude Code hook JSON schema.
 
 ### Fixed
 
@@ -114,7 +184,9 @@ Initial public release.
 
 ---
 
-[Unreleased]: https://github.com/QBall-Inc/the-bulwark/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/QBall-Inc/the-bulwark/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/QBall-Inc/the-bulwark/compare/v1.2.1...v1.3.0
+[1.2.1]: https://github.com/QBall-Inc/the-bulwark/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/QBall-Inc/the-bulwark/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/QBall-Inc/the-bulwark/compare/v1.0.1...v1.1.0
 [1.0.1]: https://github.com/QBall-Inc/the-bulwark/compare/v1.0.0...v1.0.1

package/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to The Bulwark
+
+Thanks for your interest in improving The Bulwark. Issues and pull requests are both welcome — this guide explains how contributions flow, because the repository model is a little different from a typical single-repo project.
+
+## How this repository works
+
+This public repository (`QBall-Inc/the-bulwark`) is a **mirror**. Active development happens in a private repository, and the user-facing plugin assets are synced here. That means:
+
+- The code you see here is the published plugin surface, not the full development history.
+- Changes merged here are **ported back** into the private repo by the maintainer, which then re-syncs. This keeps the two repositories from diverging.
+
+## Opening an issue
+
+Issues are open to everyone and are the fastest way to help. Please use the structured templates:
+
+- **Bug report** — include reproduction steps, expected vs actual behavior, your plugin version, Claude Code version, OS/platform (WSL / macOS / Linux), and the relevant hook or skill.
+- **Feature request** — describe the problem, your proposed solution, and any alternatives you considered.
+
+[Open an issue →](https://github.com/QBall-Inc/the-bulwark/issues/new/choose)
+
+## Submitting a pull request
+
+PRs are **accepted on this public repository.** Here's the flow:
+
+1. Fork the repo and create a branch from `main`.
+2. Make your change. Keep it focused — one logical change per PR.
+3. If you touch a Claude Code asset (skill, agent, hook, plugin manifest), make sure it still follows the [conventions](docs/reference/conventions.md) and validates against Anthropic's standards.
+4. Open the PR against `main` with a clear description of what changed and why.
+
+### What happens after you open a PR
+
+- The maintainer reviews the PR here on the public repo.
+- When it's accepted, the change is **merged here and then ported into the private dev repo**, which becomes the source of truth for the next sync. Your contribution is preserved and you are credited.
+- Because syncing flows private → public, the porting step is **mandatory** — without it, a later sync would overwrite a merged public PR. The maintainer owns this step; you don't need to do anything beyond opening the PR.
+
+> **Note for the maintainer:** a merged public PR lives only on the public repo until it is ported into the private repo. Port it *before* the next `sync-to-public.sh` run, or the sync will clobber it.
+
+## Development conventions
+
+If you're proposing a code or asset change, it's worth knowing the standards the project enforces on itself:
+
+- **[Conventions](docs/reference/conventions.md)** — the CS / T / V / ID rules (coding standards, testing, verification, issue debugging).
+- **[How it works](docs/guides/how-it-works.md)** and **[architecture.md](docs/architecture.md)** — the design model.
+- Markdown and shell files use **LF line endings** only.
+
+## Code of conduct
+
+Please be respectful and constructive in issues and PRs. We aim to keep this a welcoming project for contributors of all backgrounds.
+
+## Questions
+
+If something here is unclear, [open an issue](https://github.com/QBall-Inc/the-bulwark/issues) and ask — clarifying questions are welcome.