@massa-ai/claude-plugin 1.63.1 → 1.64.0

package/skills/massa-ai/references/hook-enforcement.md

@@ -1,133 +0,0 @@
-# Hook Enforcement
-
-Maps the runtime hook layer (`apps/claude-plugin/hooks/`, its `hooks.json`) to massa-ai
-workflows and references, and documents the massa-ai dual-write/tag contract.
-Hooks **enforce** existing references and the gate the router already selected —
-they never re-author policy and never re-route. One canonical location per rule.
-
-## Platform Scoping
-
-The full hook graph installs for **Claude Code, Codex, and Cursor**. OpenCode has
-no hook model and keeps the `AGENTS.md` bootstrap only. The installer
-(each host plugin's `install.sh`) preserves unrelated user hooks on install and
-uninstall via managed-command tracking.
-
-Platform hook formats differ; the installer translates one canonical graph
-(`hooks/hooks.json`, PascalCase events) into each platform's native shape:
-
-| Platform | Format | Event names | Matcher notes |
-|---|---|---|---|
-| Claude Code | nested `settings.json` `hooks.<Event>[{matcher, hooks:[{type,command}]}]` | `PreToolUse`, `PostToolUse`, `Stop`, `PreCompact`, `SessionStart` (PascalCase) | `Edit\|Write` |
-| Codex | nested `hooks.json` (same shape as Claude) | same PascalCase events | same as Claude |
-| Cursor | flat `hooks.json` `hooks.<event>[{command, matcher?}]` | `preToolUse`, `postToolUse`, `stop`, `preCompact`, `sessionStart` (camelCase) | tool names differ: `Edit` → `Write` (no Edit tool in Cursor) |
-
-Blocking semantics: Claude and Codex honor the `{"decision":"block","reason"}`
-JSON output. Cursor's flat protocol differs; blocking hooks (`gateguard`,
-`config_protection`) still run and nudge, but Cursor's denial is best-effort.
-The non-blocking hooks (observe, context_monitor, suggest_compact,
-continuous_learning_evaluate, precompact_save_state, stop_evidence_gate) work
-identically across all three platforms (read stdin JSON, emit JSON, stderr
-nudge, exit 0).
-
-## Environment Flags
-
-| Flag | Values | Effect |
-|---|---|---|
-| `MASSA_AI_HOOK_PROFILE` | `minimal` \| `standard` \| `strict` | `minimal`: only blocking safety hooks (gateguard, config_protection). `standard` (default): blocking + nudges + observation + stop gate as nudge. `strict`: stop gate blocks once per session to force acknowledgment. |
-| `MASSA_AI_DISABLED_HOOKS` | comma-separated hook names | Skip named hooks entirely. |
-
-Every hook exits 0 on bad stdin or non-critical error. Blocking hooks are
-<200 ms and make no network calls. Observation hooks are non-blocking.
-
-## Hooks → Enforced Reference
-
-| Hook | Event | Enforces |
-|---|---|---|
-| `stop_evidence_gate.py` | Stop | `references/evidence-gate.md` |
-| `continuous_learning_evaluate.py` | Stop | `references/lessons.md`, `scripts/lessons.ts` |
-| `precompact_save_state.py` | PreCompact | `workflows/long-session.md`, `references/context-firewall.md` |
-| `suggest_compact.py` | PreToolUse(Edit\|Write) | `references/context-firewall.md` (compaction boundary) |
-| `gateguard_fact_force.py` | PreToolUse(Edit) | `references/context-firewall.md` (investigate-before-edit) |
-| `config_protection.py` | PreToolUse(Edit\|Write) | `references/verification-ladder.md` (scope) |
-| `observe_runner.py` | PostToolUse | `references/lessons.md` (observation buffer) |
-| `context_monitor.py` | PostToolUse | `references/verification-ladder.md` (task sizing/scope) |
-
-## Workflow-Aware Stop Gate
-
-`stop_evidence_gate.py` reads the active `workflow` from `.specs/project/STATE.md`
-and selects the workflow-specific gate. When `workflow` is unset or STATE is
-absent, it falls back to the flat evidence matrix (graceful degradation).
-
-| Workflow | `stop_evidence_gate` applies |
-|---|---|
-| `architecture-fix` | verification-fix gate (`references/verification-ladder.md`) |
-| `bugs-fix` | verification-fix gate |
-| `code-quality-fix` | verification-fix gate |
-| `implementation-fix` | verification-fix gate |
-| `mobile-figma-fix` | verification-fix gate |
-| `requirements-fix` | verification-fix gate |
-| `security-fix` | verification-fix gate |
-| `tests-fix` | verification-fix gate |
-| `spec-driven` | `validation.md` verdict = Pass; 3-iteration cap |
-| `debug` | reproduction no longer fails |
-| `feature` | lite evidence matrix (`references/evidence-gate.md`) |
-| `refactor` | lite evidence matrix |
-| `exploration` | no-mutation gate (read-only invariant) |
-| `architecture-audit` | flat evidence matrix |
-| `bugs-audit` | flat evidence matrix |
-| `code-quality-audit` | flat evidence matrix |
-| `implementation-audit` | flat evidence matrix |
-| `mobile-figma-audit` | flat evidence matrix |
-| `requirements-audit` | flat evidence matrix |
-| `security-audit` | flat evidence matrix |
-| `tests-audit` | flat evidence matrix |
-| `furps-refinement` | flat evidence matrix (findings-only; report written + DoR coverage gaps listed) |
-| `create-adr` | flat evidence matrix |
-| `commit` | flat evidence matrix |
-| `design` | flat evidence matrix |
-| `long-session` | flat evidence matrix |
-| `onboarding` | flat evidence matrix |
-| `create-rfc` | flat evidence matrix |
-| `create-tdd` | flat evidence matrix |
-| `the-fool` | flat evidence matrix |
-| `create-ticket` | flat evidence matrix |
-
-## massa-ai Dual-Write / Tag Contract
-
-The continuous-learning loop writes two stores, not one:
-
-- `lessons.ts add` / `import` — deterministic grounded file store
-  (`.specs/lessons.json`); refuses ungrounded lessons; promotion/quarantine.
-- `remember` — durable memory, best-effort via REST (`MASSA_AI_API_URL`),
-  file-only fallback when REST is unavailable.
-
-**Type:** always `pattern` (lessons are procedural knowledge) or `decision`
-(when a lesson captures a chosen trade-off). `procedural` is a **tag**, never a
-type — massa-ai supports only `critical | conversation | code | decision | pattern`
-(`references/mcp-tools.md`).
-
-**Tags:** every massa-ai lesson write carries the full massa-ai persistence
-contract: `project:<projectId>`, `session:<workflowSessionId>`,
-`workflow:<type>`, `entity:<name>`, `memory:procedural`. This puts lessons in
-the same recall namespace as massa-ai decisions/patterns, so future
-`recall` surfaces them at Specify/Design.
-
-`PreCompact` (`precompact_save_state.py`) writes a massa-ai `critical` memory
-tagged `memory:working` for the active objective + exact next step before the
-window compacts; file-only fallback when REST is unavailable.
-
-## No SessionStart Recall Duplication
-
-massa-ai's router already runs budgeted `recall` on startup. The hook
-layer adds **no** competing SessionStart recall. The installer keeps the
-existing SessionStart bootstrap (which transports `AGENTS.md` policy); memory
-recall stays owned by the router.
-
-## Graceful Degradation
-
-| Failure | Behavior |
-|---|---|
-| massa-ai REST unavailable | lesson still lands in `lessons.json`; the memory write is fire-and-forget and is dropped silently (a timeout emits a `deadline-on-fire` JSON breadcrumb on **stderr**, nothing is written to disk) |
-| `.specs/project/STATE.md` absent / workflow unset | stop gate falls back to flat matrix |
-| bad / malformed stdin | hook exits 0, never blocks |
-| hook non-critical error | exit 0, approve, degrade silently — there is no skip log file |

package/skills/massa-ai/references/spec-driven/lessons.md

@@ -1,5 +0,0 @@
-# Spec-Driven Lessons
-
-Use `references/lessons.md` for lesson loading, capture, and lifecycle. The lesson system is no longer spec-driven only — it applies to all implementation, fix, and debug workflows.
-
-See `references/lessons.md` for the full signal table, capture commands, loading commands, promotion lifecycle, and fallback behavior.