{
  "markdown": "# Blue Collar Governance Plugin\n\nA Claude Code plugin that enforces governance rules through deterministic local hooks — not just prompt instructions.\n\n> [!WARNING]\n> 🚧 Active Construction: This repository is currently being worked on.\n\n## What This Does\n\nThis plugin adds a runtime governance layer to Claude Code sessions:\n\n- **Fail-closed command hooks** over `Bash`, `Write`, and `Edit` — dangerous actions are blocked before execution, not after\n- **Control rod profiles** that classify every tool action against configurable domain rules (pricing, customer data, auth, destructive ops, and more)\n- **Session closeout gating** — the session cannot close cleanly if unresolved blocking findings exist\n- **Governance state preservation** — enforcement state survives context compaction and session restarts\n- **Operator-facing skills** for inspecting governance posture, forensic history, safety interlocks, session health, and the Work Order intake pilot chain during a live session\n\n## Why This Exists\n\nPrompt-based instructions alone do not reliably prevent dangerous actions at the moment a tool runs. They can be compacted away, ignored under pressure, or simply not loaded.\n\nThis plugin exists to make the load-bearing governance seams deterministic and local:\n\n- A hook that runs real code before every `Bash`, `Write`, or `Edit` call\n- Classification logic that maps tool actions to protected domains\n- Deny decisions that fire before the tool executes, not after\n- State that persists through compaction so enforcement doesn't silently disappear mid-session\n\n## How It Works\n\nThe plugin registers hooks for twenty-four Claude Code lifecycle events:\n\n| Event | What happens |\n|-------|-------------|\n| **SessionStart** | Injects governance context; rehydrates state after compaction |\n| **UserPromptSubmit** | Blocks prompts containing exact disallowed governance-bypass phrases |\n| **PreCompact** | Preserves governance state before context compaction |\n| **PostCompact** | Verifies governance state survived compaction; advisory only, no gating |\n| **PreToolUse** | Classifies the tool action; denies HARD_STOP domains; asks on SUPERVISED; appends on-disk HOLD/KILL advisory only on the existing SUPERVISED message path |\n| **PermissionRequest** | Resolves permission dialogs against the active control rod profile |\n| **PermissionDenied** | Records denied tool actions for governed domains to the forensic chain |\n| **PostToolUse** | Records completed tool actions on classified domains to the forensic chain |\n| **PostToolUseFailure** | Records failed tool actions on classified domains to the forensic chain |\n| **Notification** | Records notification events for governance observability |\n| **SubagentStart** | Records subagent start; maintains bounded active-subagent state |\n| **SubagentStop** | Bounded Mini-Walk gate; blocks if unresolved governance findings exist |\n| **TaskCreated** | Tracks a bounded session-local task registry keyed by `task_id` |\n| **TaskCompleted** | Observes completion against that registry; writes bounded additive evidence for matched, mismatch, or orphan completion |\n| **Stop** | Evaluates a Foreman's Walk; blocks closeout if blocking findings exist |\n| **StopFailure** | Records stop-failure error type and details to the forensic chain |\n| **TeammateIdle** | Observe-only idle signal; writes additive evidence only when related open tasks remain |\n| **SessionEnd** | Records session-end reason; clears active-subagent state |\n| **Elicitation** | Records bounded observe-only MCP input requests; no response control or raw payload dump |\n| **ElicitationResult** | Records bounded observe-only MCP input results; no response override or behavioral mutation |\n| **ConfigChange** | Blocks governed config sources; observes policy_settings and unknown sources |\n| **CwdChanged** | Records working-directory changes; notes when outside project root |\n| **FileChanged** | Detects external changes to governance-relevant files; records to forensic chain |\n| **InstructionsLoaded** | Records instruction-file load events for governance-layer presence observability |\n\nEvery hook path fails closed on internal error — a crash produces a deny/block decision, never a silent pass-through.\n\n### Control Rod Profiles\n\nThe plugin ships three starter profiles that define autonomy levels per domain:\n\n| Profile | HARD_STOP domains | SUPERVISED domains | FULL_AUTO domains |\n|---------|-------------------|--------------------|-------------------|\n| **conservative** | 5 (pricing, customer data, schema, auth, destructive ops) | 4 (existing files, new files, UI/styling, tests) | 1 (documentation) |\n| **balanced** | 4 | 2 | 4 |\n| **velocity** | 2 | 3 | 5 |\n\nCustom profiles are supported through the same domain-rule structure.\n\n## How to Use It\n\n### Plugin Mode\n\nLoad the repo as a local Claude Code plugin:\n\n```bash\nclaude --plugin-dir /path/to/blue-collar-governance-plugin\n```\n\nThis registers the hooks and makes the shipped skills available as `/blue-collar-governance-plugin:<skill-name>`.\n\n### Standalone Repo Mode\n\nThe plugin also works as a standalone project-local governance layer through:\n\n- `.claude/settings.json` — hook registration and deny rules\n- `.claude/hooks/run-governance-hook.js` — hook entrypoint\n\n### Mode Boundary\n\nPlugin mode and standalone mode are alternate loading paths. Do not run both simultaneously in the same session unless you have explicitly verified that combination — duplicate hook execution is possible.\n\n### Configuration\n\nThe active profile and matched tools are configured in `.claude/settings.json`:\n\n```json\n{\n  \"blueCollarGovernance\": {\n    \"hookRuntime\": {\n      \"profileId\": \"conservative\",\n      \"matchedTools\": [\"Bash\", \"Write\", \"Edit\"],\n      \"stateDirectory\": \".claude/runtime\",\n      \"blockingSeverities\": [\"CRITICAL\", \"HIGH\"]\n    }\n  }\n}\n```\n\n## What Ships Today\n\n- Claude plugin manifest at `.claude-plugin/plugin.json`\n- Plugin hook registry at `hooks/hooks.json`\n- Fail-closed hook runtime at `src/HookRuntime.js` and `src/HookRuntimeSlice2.js`\n- 35 operator-facing skills under `skills/<name>/SKILL.md`\n- Work Order pilot chain surfaces at `/work-order-intake`, `/work-order-scaffold`, and `/work-order-posture`\n- B' Phase 1 restoration surfaces at `/resolve` and `/restoration`, backed by `RestorationEngine` and `RestorationProjectionAdapter`\n- Confidence Gradient Packet 4 surfaces at `/confidence`, backed by `ConfidenceGradientEngine`, `MarkerContinuityEngine`, `MarkerTemporalSignalsEngine`, and `ConfidenceSkill`\n- Confidence Transition Evidence at `/confidence-transitions`, backed by `ConfidenceTransitionGenerator` and `ConfidenceTransitionsSkill`\n- Packet 7A advisory presence awareness in `PreToolUse` SUPERVISED asks only, backed by `ConfidenceAdvisor`\n- Standalone compatibility path at `.claude/settings.json`\n- Runtime governance modules under `src/`, including engines, skill surfaces, and hook adapters\n- Golden and live verification under `tests/`\n- CC-native render wrapper at `scripts/render-skill.js`\n\n## Work Order Pilot Chain\n\n- Governance remains the engine underneath the pilot chain. Wave 7 closes C1 `/walk`, C2 `/fire-break`, and C3 foreign-repo deny delivery without changing the repo's governance-first identity.\n- Work Order is the only intake pilot shipped in this repo. The existing Work Order skin/render surface still exists unchanged.\n- `/work-order-intake`, `/work-order-scaffold`, and `/work-order-posture` are shipped.\n- The chain stops at reviewed artifacts only: intake object, scaffold object, and posture map.\n- No SessionBrief bridge, hook-runtime integration, or execution path from intake/scaffold/posture is shipped.\n\n## B' Restoration Phase 1\n\n- B' Phase 1 ships `RestorationEngine`, `RestorationProjectionAdapter`, `/resolve`, and `/restoration`.\n- Verification states are exactly `UNVERIFIED` and `VERIFIED`; `PARTIAL` remains deferred.\n- Board projection is continuity-linked and verified-only.\n- Manual-only and walk-only restored items stay visible on `/restoration` and do not enter Board projection unless continuity-linked and verified.\n- No shared contract widening ships in Phase 1; `MIGRATIONS.md` remains unchanged.\n\n## Confidence Gradient Phase 1 + Packets 2/3/4\n\n- Confidence Gradient Phase 1 ships `ConfidenceGradientEngine` and `/confidence`.\n- Confidence Required Coverage (Packet 2) is explicit opt-in and additive over observed marker truth.\n- Packet 3 ships additive snapshot capture via `ConfidenceGradientEngine.buildSnapshot(files)` and deterministic file-local comparison via `MarkerContinuityEngine.compare(previousSnapshot, currentSnapshot)`.\n- Packet 4 ships additive temporal interpretation via `MarkerTemporalSignalsEngine.evaluateTimeline(timelineEntries, options)` and optional `/confidence` composition via `markerTemporalSignalsView`.\n- `/confidence` single-scan behavior remains unchanged when optional Packet 2/3/4 inputs are not supplied.\n- `/confidence` Packet 3 comparison behavior remains unchanged when only comparison input is supplied.\n- Packet 3 preserves explicit ambiguity by emitting `AMBIGUOUS` when candidate sets remain non-unique.\n- Packet 4 preserves explicit temporal ambiguity by emitting `TEMPORAL_LINEAGE_AMBIGUOUS` instead of forcing stronger claims.\n- Shipped marker family is slash only; semicolon family is reserved and not executable in Phase 1.\n- Tier ladder is fixed to `WATCH (///)`, `GAP (////)`, `HOLD (/////)`, and `KILL (//////)`.\n- Scanning is deterministic and stateless over explicit file snapshots only.\n- Scan fence is bounded to `src/`, `hooks/`, `scripts/`, `.claude/`, and `*.js`.\n- Parsing is line-leading only with structural delimiter rules.\n- `/confidence` is read/query/render-only with no mutation path.\n- Packet 3 remains file-local and slash-only; no rename-aware or cross-file continuity claim is shipped.\n- Packet 4 temporal interpretation uses explicit dated timeline input only and does not infer time from git, filesystem metadata, branch age, session date, or closeout date.\n- Packet 4 ships only bounded temporal findings `STALE_HOLD` and `UNRESOLVED_KILL` plus deterministic timeline/lineage errors.\n- Packet 3 and Packet 4 do not widen `ContinuityLedger`, `StandingRiskEngine`, `ForensicChain`, `ForemansWalk`, or hook/lifecycle behavior.\n- Packet 4 does not age Packet 2 required-coverage misses.\n- Packet 4 does not ship resolution semantics, standing-risk semantics, scores, priorities, or health math.\n- Required coverage policy file is repo-root `confidence-required-coverage.json`.\n- Required coverage policy targets are file-first exact-path entries only.\n- `/confidence` may compose required coverage findings additively while keeping observed marker truth separate.\n- Packet 3 does not depend on Packet 2 required coverage policy to function.\n- Packet 2 introduces no reviewed-clean semantics.\n- No shared contract widening ships in Phase 1; `MIGRATIONS.md` remains unchanged.\n- Hook/lifecycle/omission/chain/board integration and semicolon-family execution remain outside Phase 1.\n- Packet 2 introduces no package/install/marketplace claims.\n- The current repo has zero line-leading slash markers in the Phase 1 scan fence, so the real repo scan currently returns an empty report.\n\n## Packet 5 `/walk` Confidence Sidecar Composition\n\n- `/walk` may compose one optional precomputed `confidenceSidecarView` at render time.\n- Packet 5 sidecar v1 supports only `observedMarkers`, `requiredCoverage`, and `markerContinuity`.\n- The sidecar is informational only and does not change walk findings, severity, blocking posture, clean-closeout posture, `sessionOfRecordRef`, or `asBuiltStatusCounts`.\n- Foreman's Walk remains unchanged and no Walk Pass 6 is shipped.\n- Packet 5 sidecar composition remains independent from Packet 4 temporal signals.\n- The shipped `scripts/render-skill.js walk` wrapper/runtime path remains persisted-walk-only in Packet 5 and does not discover or compute sidecar input.\n- No persistence widening, hook-runtime widening, chain/board/standing-risk integration, or skin translation wave is introduced by Packet 5.\n- Unsupported skin + sidecar requests remain on raw canonical `/walk` fallback behavior.\n\n## Packet 6 Confidence Transition Evidence\n\n- Packet 6 ships `ConfidenceTransitionGenerator.generateConfidenceTransitionEntries(input)` and dedicated `/confidence-transitions` rendering via `ConfidenceTransitionsSkill.renderConfidenceTransitions(input)`.\n- `skills/confidence-transitions/SKILL.md` is the operator-facing skill, and golden proof lives at `tests/golden/ConfidenceTransitionGenerator.golden.test.js` and `tests/golden/ConfidenceTransitionsSkill.golden.test.js`.\n- Packet 6 maps explicit Packet 3 compare truth into neutral append-ready `FINDING` entries for only `NEWLY_OBSERVED`, `NO_LONGER_OBSERVED`, and `RETIERED`.\n- `/confidence-transitions` previews by default and appends only when the operator explicitly requests append through existing `ForensicChain.appendEntry(...)`.\n- `/confidence` remains read/query/render-only; Packet 6 adds no `/confidence` append behavior.\n- Packet 6 introduces no resolution semantics, no `RESOLVED`, no restoration crossover, no new `ForensicChain` entry types, and no linked history traversal.\n- Packet 6 truth lock lives at `docs/specs/PACKET6_TRANSITION_EVIDENCE_TRUTH_LOCK.md`, the skill spec lives at `docs/specs/CONFIDENCE_TRANSITIONS_SKILL.md`, and the closeout lives at `docs/PACKET6_TRANSITION_EVIDENCE_CLOSEOUT.md`.\n- No shared contract widening ships in Packet 6; `MIGRATIONS.md` remains unchanged.\n\n## Packet 7A Advisory Presence Awareness\n\n- Packet 7A ships `ConfidenceAdvisor.buildConfidenceAdvisory(filePath)` and `PreToolUse` SUPERVISED-only advisory composition through the existing `permissionDecisionReason` string.\n- Advisory reads only the current on-disk contents of one candidate file and reuses the existing slash-family confidence scan fence.\n- Advisory fires only for existing on-disk `HOLD` and `KILL` markers and only on `Write` / `Edit` actions that already resolved to `SUPERVISED`.\n- Missing, unreadable, and out-of-fence files remain silent; `WATCH` and `GAP` remain silent.\n- Deny paths, `FULL_AUTO` allow, permitted `HARD_STOP` allow, unclassified allow, `/confidence`, `PostToolUse`, chain writes, and host-facing hook response shape remain unchanged.\n- Packet 7A truth lock lives at `docs/specs/PACKET7A_ADVISORY_PRESENCE_TRUTH_LOCK.md`, the helper spec lives at `docs/specs/HOOK_CONFIDENCE_ADVISOR.md`, and the closeout lives at `docs/PACKET7A_ADVISORY_PRESENCE_CLOSEOUT.md`.\n- No shared contract widening ships in Packet 7A; `MIGRATIONS.md` remains unchanged.\n\n## What This Does Not Do\n\n- **No npm package or marketplace install.** There is no `package.json`. Load the repo directly with `--plugin-dir`.\n- **No intake-chain execution bridge.** The Work Order pilot does not create SessionBrief, mutate Control Rod settings, or start execution on its own.\n- **No second intake skin.** Work Order is the only intake pilot currently shipped.\n- **No Agent tool governance.** Hooks cover `Bash`, `Write`, and `Edit` only. `Agent` spawn semantics are not classified.\n- **No HTTP hooks or LLM-based decisions.** All hook logic is deterministic local code. No network calls, no model queries.\n- **No universal project compatibility claim.** The plugin has been proven on its own repo, on governed-workflow, and on one foreign production repo (FieldPoint). Broader compatibility is not yet validated.\n- **No multi-agent governance.** This is single-session, single-operator enforcement.\n- **No trust-transfer or certificate claims.** That work remains parked.\n- **No `PARTIAL` restoration verification state in Phase 1.** Verification states are locked to `UNVERIFIED` and `VERIFIED`.\n- **No removal-awareness or payload inspection in Packet 7A.** Advisory presence awareness reads current on-disk file truth only and does not inspect intended edits.\n\n## Proof\n\n- **Golden verification:** the current repo state passes 569 tests in full golden regression.\n- **Live enforcement proof:** A real `Write` to a pricing file on a foreign repo was classified into `pricing_quote_logic`, resolved to `HARD_STOP`, denied by `PreToolUse`, and never executed.\n- **Compaction survival proof:** Governance state is preserved through `PreCompact` and rehydrated on `SessionStart` with source `compact`.\n- **Fail-closed proof:** Corrupted state files, unknown hook events, and internal errors all produce deny/block decisions — never silent pass-through.\n- **Lifecycle expansion proof boundary:** 24 handled official lifecycle events are shipped; `TaskCreated`, `TaskCompleted`, and `TeammateIdle` now have bounded proof; `WorktreeCreate` and `WorktreeRemove` remain pending, and `Setup` remains unclaimed.\n- **Confidence Packet 4 boundary proof:** `/confidence` remains slash-only, deterministic, and read/query/render-only; Packet 3 comparison behavior remains additive/file-local with explicit ambiguity handling; Packet 4 temporal interpretation is explicit-timeline-only and bounded to `STALE_HOLD`/`UNRESOLVED_KILL`; semicolon-family execution, rename-aware/cross-file continuity, and hook/lifecycle integration remain deferred.\n- **Confidence Packet 6 boundary proof:** `/confidence-transitions` remains a dedicated preview-first surface; generated entries stay on existing `FINDING` only with `NEWLY_OBSERVED`, `NO_LONGER_OBSERVED`, and `RETIERED`; `/confidence` gained no append path; and no resolution semantics or `ForensicChain` contract widening shipped.\n- **Confidence Packet 7A boundary proof:** `ConfidenceAdvisor` reads one current on-disk file only, advisory appears only on SUPERVISED `Write` / `Edit` asks through existing `permissionDecisionReason`, `HOLD` / `KILL` are the only advisory tiers, `FULL_AUTO` / permitted `HARD_STOP` / deny paths remain silent, and advisor failure stays locally swallowed without changing governance decisions or exit behavior.\n\nDetailed proof documentation:\n\n- `docs/WAVE7_CLOSEOUT.md` — Wave 7 closeout evidence map\n- `docs/B_PRIME_RESTORATION_PHASE1_CLOSEOUT.md` — B' Phase 1 finish-lane closeout, acceptance status, and bounded HOLDs\n- `docs/CONFIDENCE_GRADIENT_PHASE1_CLOSEOUT.md` — Confidence Gradient Phase 1 finish-lane closeout, acceptance status, and bounded HOLDs\n- `docs/PACKET3_MARKER_CONTINUITY_CLOSEOUT.md` — Packet 3 marker continuity closeout, mandatory proof posture, and front-door sync status\n- `docs/PACKET4_TEMPORAL_SIGNALS_CLOSEOUT.md` — Packet 4 temporal signals closeout, mandatory proof posture, and front-door sync status\n- `docs/PACKET5_WALK_COMPOSITION_CLOSEOUT.md` — Packet 5 `/walk` confidence sidecar composition closeout, mandatory proof posture, and front-door sync status\n- `docs/PACKET6_TRANSITION_EVIDENCE_CLOSEOUT.md` — Packet 6 confidence transition evidence closeout, bounded lane split, and targeted recheck status\n- `docs/PACKET7A_ADVISORY_PRESENCE_CLOSEOUT.md` — Packet 7A advisory presence awareness closeout, bounded hook-runtime lane, and proof recheck status\n- `docs/PHASE3_LIFECYCLE_EXPANSION_CLOSEOUT.md` — Phase 3 finish-lane closeout, current 24-event posture, and public/history sync status\n- `docs/PHASE3_REMAINING_LIFECYCLE_SEAMS_CLOSEOUT.md` — Phase 3 structural closeout (Blocks A/B shipped, Block C held)\n- `docs/PHASE2_LIFECYCLE_EXPANSION_CLOSEOUT.md` — historical Phase 2 lifecycle expansion closeout and 21-event waypoint\n- `docs/PHASE1_LIFECYCLE_EXPANSION_CLOSEOUT.md` — historical Phase 1 lifecycle expansion closeout and 11-to-19 count note\n- `docs/BLUE_COLLAR_CODING_THESIS.md` — bounded thesis rider for the first front door\n- `docs/OWASP_AGENTIC_MAPPING.md` — public reviewer-facing OWASP agentic security mapping and positioning/proof artifact\n- `docs/WAVE6_PROOF_PACK.md` — Wave 6 proof pack (fail-closed, enforcement breadth, cross-repo governance)\n- `docs/PLUGIN_CONVERSION_PROOF.md` — plugin validation and local smoke runbook\n- `docs/specs/HOOK_RUNTIME_ENFORCEMENT_SPINE.md` — hook runtime contract baseline\n\n## Repository Layout\n\n```text\n.\n├── .claude-plugin/        # Claude plugin manifest\n├── hooks/                 # Plugin hook registry and wrapper\n├── .claude/               # Standalone path, project settings, deny rules\n├── skills/                # Operator-facing skills\n├── src/                   # Runtime governance modules: engines, skill surfaces, and hook runtime\n├── scripts/               # Render wrapper and utility scripts\n├── tests/                 # Golden and live verification\n├── docs/                  # Specs, proof artifacts, and indexes\n│   └── specs/             # Canonical contract baselines\n└── raw/                   # Reference-only methodology inputs (not canon)\n```\n\n## License\n\n[MIT](LICENSE)\n\n## Start Here\n\n1. `CLAUDE.md` — AI operating posture and repo truth\n2. `docs/WAVE7_CLOSEOUT.md` — Wave 7 shipped scope and remaining HOLDs\n3. `docs/BLUE_COLLAR_CODING_THESIS.md` — bounded thesis rider for the front-door shift\n4. `docs/specs/HOOK_RUNTIME_ENFORCEMENT_SPINE.md` — hook runtime contract\n5. `REPO_INDEX.md` — full repo navigation map\n",
  "bytes": 21046,
  "sha": "3803cdaed29e152be75964d6bfe1611f1e51dea27b2f4623e37807a0f02b834a",
  "repo_slug": "tde6541/blue-collar-governance-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_tde6541_blue_collar_governance_plugin_bl_037459e7/readme"
}