@massa-ai/cursor-plugin 1.21.0 → 1.22.0

package/.cursor-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "massa-ai",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "massa-ai — semantic code search, memory, and context compression for Cursor"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/cursor-plugin",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
   "files": [
     "agents",

package/skills/massa-ai/references/evidence-gate.md

@@ -38,7 +38,7 @@ Use this compact shape when closing docs or skill work:
 ✅ [Verified] Skill validation and stale-reference scans passed.
 🏁 [Finished] Updated massa-ai references. Memory outcome: durable decision stored. Remaining risk: none found.
 
-Evidence: `rtk python3 skills/skill-architect/scripts/validate_skill.py skills/massa-ai --format json` passed; stale-reference and local-link scans passed.
+Evidence: `bun run scripts/generate-skill-artifacts.ts --check` passed; stale-reference and local-link scans passed.
 Changed artifacts: `skills/massa-ai/SKILL.md`, `workflows/spec-driven.md`, `references/spec-driven/`, and `references/memory-policy.md`.
 Memory outcome: wrote decision memory `dec_...`; no failed memory writes.
 Residual risk: none found.

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

@@ -44,7 +44,7 @@ Every hook exits 0 on bad stdin or non-critical error. Blocking hooks are
 | Hook | Event | Enforces |
 |---|---|---|
 | `stop_evidence_gate.py` | Stop | `references/evidence-gate.md` |
-| `continuous_learning_evaluate.py` | Stop | `references/lessons.md`, `scripts/lessons.py` |
+| `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) |
@@ -100,7 +100,7 @@ absent, it falls back to the flat evidence matrix (graceful degradation).
 
 The continuous-learning loop writes two stores, not one:
 
-- `lessons.py add` / `import` — deterministic grounded file store
+- `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.

package/skills/massa-ai/references/implementation-delivery.md

@@ -22,8 +22,8 @@ human chose to merge it".
 | 1 | Isolate | `git fetch origin <base> && git worktree add -b <type>/<slug> <path> origin/<base>` | Branch name taken → suffix `-2`. Worktree path taken → reuse it only if its branch matches |
 | 2 | Implement | one task → gate → `git commit` | Gate red → fix before committing. Never commit through a failing gate |
 | 3 | Push | `git push -u origin <type>/<slug>` | Rejected non-fast-forward → `git fetch` + rebase, never force-push a shared branch |
-| 3.5 | Deliver specs | `python3 skills/massa-ai/scripts/check_specs_delivered.py <feature> [--root .]` | Non-zero → commit the missing `.specs/` updates (a `docs(specs):`-type commit is normal), push, re-run. Defensive fallback — should not fire when the close-out task already committed `.specs/` before the first push |
-| 4 | Propose — precondition: Stage 3.5 (`check_specs_delivered.py`) green | `gh pr create --base <base> --title <t> --body <b>` | `gh` absent/unauthenticated → degraded path |
+| 3.5 | Deliver specs | `bun skills/massa-ai/scripts/check_specs_delivered.ts <feature> [--root .]` | Non-zero → commit the missing `.specs/` updates (a `docs(specs):`-type commit is normal), push, re-run. Defensive fallback — should not fire when the close-out task already committed `.specs/` before the first push |
+| 4 | Propose — precondition: Stage 3.5 (`check_specs_delivered.ts`) green | `gh pr create --base <base> --title <t> --body <b>` | `gh` absent/unauthenticated → degraded path |
 | 5 | Watch | `gh pr checks --watch` | No checks configured → say so; do not claim CI passed |
 | 6 | Repair | fix on the branch, commit, return to stage 5 | Capped at 3 iterations, then stop as `Blocked` |
 | 7 | **Ask** | report the PR URL and the green check list, then **stop** | — |
@@ -76,7 +76,7 @@ One explicit delivery authorization per feature, obtained before implementation
 
 ### Stage 3.5 — deliver specs before PR (defensive fallback)
 
-Between Push and Propose, all feature `.specs/` artifacts (`spec/context/design/tasks/validation` as applicable), `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `.specs/project/FEATURES.json` must be updated and committed on the branch. **Deterministic backing (run it, do not eyeball it):** `python3 skills/massa-ai/scripts/check_specs_delivered.py <feature> [--root .]` — a non-zero exit blocks Propose. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+Between Push and Propose, all feature `.specs/` artifacts (`spec/context/design/tasks/validation` as applicable), `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `.specs/project/FEATURES.json` must be updated and committed on the branch. **Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/check_specs_delivered.ts <feature> [--root .]` — a non-zero exit blocks Propose. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
 
 **Nominal path: this stage should never fire.** The feature's own close-out task (the last task before delivery — see `workflows/spec-driven.md` step 7) commits `.specs/` updates **before** the first push, so stage 3.5's remediation is a defensive fallback for the rare case something slipped through, not the normal place `.specs/` gets committed. On failure: commit the missing `.specs/` updates (a `docs(specs):`-type commit is normal), push, re-run this stage. No commits may land between the close-out commit and PR creation.
 

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

@@ -4,9 +4,8 @@ Use this reference when loading confirmed project lessons during startup, or rec
 
 ## Artifacts
 
-- `.specs/lessons.json` — canonical machine-owned lesson state. Read it; do not hand-edit.
-- `.specs/LESSONS.md` — rendered playbook generated by the script. Read it; do not hand-edit.
-- `skills/massa-ai/scripts/lessons.py` — deterministic bookkeeping script.
+- `.specs/lessons.json` — canonical machine-owned lesson state, the single lessons store. Read it; do not hand-edit.
+- `skills/massa-ai/scripts/lessons.ts` — deterministic bookkeeping script; `lessons list` is the on-demand view.
 
 ## Lesson Signal Table
 
@@ -23,7 +22,7 @@ Use this reference when loading confirmed project lessons during startup, or rec
 After a workflow's verification step finds a concrete reusable signal, record it:
 
 ```bash
-python3 skills/massa-ai/scripts/lessons.py --root . add \
+bun skills/massa-ai/scripts/lessons.ts --root . add \
   --feature "<feature-slug>" \
   --signal "<ac_gap|surviving_mutant|spec_precision_gap|spec_deviation|gate_fail>" \
   --source "<validation.md source, AC id, file:line, mutant id, or SPEC_DEVIATION ref>" \
@@ -51,7 +50,7 @@ Run this self-check after verification: if a failed acceptance criterion, surviv
 During startup of any applicable workflow, load confirmed lessons when `.specs/lessons.json` exists:
 
 ```bash
-python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed [--scope <relevant>]
+bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed [--scope <relevant>]
 ```
 
 - Use `--scope` or `--query` to keep the loaded set small.
@@ -69,7 +68,7 @@ python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed [--s
 
 ## No-Script Fallback
 
-If `lessons.py` is unavailable or cannot run, record `Lessons: skipped - script unavailable` in the validation report or evidence gate, keep the raw signal in the report, and do not hand-edit `lessons.json` or `LESSONS.md`. A future run with the script can import the validated signal.
+If `lessons.ts` is unavailable or cannot run, record `Lessons: skipped - script unavailable` in the validation report or evidence gate, keep the raw signal in the report, and do not hand-edit `lessons.json`. A future run with the script can import the validated signal.
 
 ## Continuous-Learning Loop (hook-fed)
 
@@ -82,13 +81,13 @@ The lessons layer is a closed loop, not manual-only. Two runtime hooks
 2. **evaluate** — `continuous_learning_evaluate.py` (Stop) reads the active
    massa-ai context from `.specs/project/STATE.md` and the observations
    buffer. For each observation that already carries grounded fields
-   (`signal`, `text`, `source`, `feature`), it calls `lessons.py add` with the
+   (`signal`, `text`, `source`, `feature`), it calls `lessons.ts add` with the
    `--project`/`--session`/`--workflow`/`--entity` context. Ungrounded
    observations are left in the buffer for agent input and logged as skipped.
 
 ### massa-ai Dual-Write
 
-`lessons.py add` and `import` best-effort write massa-ai memory so the file store
+`lessons.ts add` and `import` best-effort write massa-ai memory so the file store
 and durable memory stay consistent:
 
 - **type** is always `pattern` (lessons are procedural knowledge). `procedural`
@@ -105,8 +104,8 @@ and durable memory stay consistent:
 ### Round-Trip
 
 ```bash
-python3 skills/massa-ai/scripts/lessons.py --root . export --out lessons.export.json
-python3 skills/massa-ai/scripts/lessons.py --root . import --in lessons.export.json
+bun skills/massa-ai/scripts/lessons.ts --root . export --out lessons.export.json
+bun skills/massa-ai/scripts/lessons.ts --root . import --in lessons.export.json
 ```
 
 `export`/`import` round-trip the file store; `import` re-emits massa-ai memory

package/skills/massa-ai/references/mcp-tools.md

@@ -285,7 +285,7 @@ delay. Preferred shell pattern:
 MASSA_AI_API_URL="${MASSA_AI_API_URL:-http://localhost:3333}"
 for i in $(seq 1 40); do
   result=$(rtk curl -s "$MASSA_AI_API_URL/api/v1/project/index/status/JOB_ID")
-  status=$(printf '%s' "$result" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['status'])")
+  status=$(printf '%s' "$result" | bun -e "console.log(JSON.parse(await Bun.stdin.text()).data.status)")
   printf '[%s] status=%s\n' "$i" "$status"
   [ "$status" = "completed" ] || [ "$status" = "failed" ] && break
   sleep 15

package/skills/massa-ai/references/project-context.md

@@ -23,7 +23,7 @@ continue only when the next decision still needs more.
 | 2 — Host config | `.claude/` (`settings.json`, `settings.local.json`, `commands/`, `agents/`, `skills/`, `hooks/`), `.cursor/` (`rules/`, `mcp.json`), `.github/copilot-instructions.md`, `.opencode/`, `.codex/` | Permissions, hooks, host-specific tooling, MCP registrations |
 | 3 — Product docs | `README.md`, `CONTRIBUTING.md`, `docs/`, `ARCHITECTURE.md` | Install/run/build surface, contribution protocol, architecture |
 | 4 — Delivery config | `.github/workflows/`, `CHANGELOG.md`, `package.json` / `Cargo.toml` / `build.gradle*` / `pyproject.toml`, `.tool-versions`, `mise.toml`, `Makefile` | CI gates, release rules, runtime and toolchain pins, task commands |
-| 5 — Live state | `.specs/project/STATE.md`, `.specs/project/FEATURES.json`, `.specs/HANDOFF.md`, `.specs/LESSONS.md` | In-flight work, decisions already made, confirmed lessons |
+| 5 — Live state | `.specs/project/STATE.md`, `.specs/project/FEATURES.json`, `.specs/HANDOFF.md`, `.specs/lessons.json` (single store; `lessons list` is the on-demand view) | In-flight work, decisions already made, confirmed lessons |
 
 Tier 1 and Tier 3 (`README.md`) are mandatory in every workflow. Tiers 2, 4, and
 5 are read when the task touches host tooling, a gate/release surface, or

package/skills/massa-ai/references/spec-driven/artifact-store.md

@@ -27,8 +27,7 @@ Use these logical paths:
 - `.specs/features/<slug>/validation.md` — feature validation report
 - `.specs/quick/NNN-slug/TASK.md` — quick-mode task (one-line intent + acceptance)
 - `.specs/quick/NNN-slug/SUMMARY.md` — quick-mode result (files changed + gate evidence)
-- `.specs/lessons.json` — machine-owned lesson state (managed by `lessons.py`)
-- `.specs/LESSONS.md` — rendered lesson playbook (read-only, generated by `lessons.py`)
+- `.specs/lessons.json` — the single lessons store, machine-owned (managed by `lessons.ts`); `lessons list` is the on-demand view
 
 ## Quick Artifacts
 
@@ -61,21 +60,21 @@ Quick tasks are also listed in the STATE.md Quick Tasks table (see `references/s
 
 Load only what you need. Prefer metadata-only inspection before loading full content.
 
-- **Feature registry status:** `cat .specs/project/FEATURES.json | python3 -c "import json,sys; d=json.load(sys.stdin); print('active:', d.get('active_feature')); [print(f['id'], f['status']) for f in d.get('features',[])]"`
+- **Feature registry status:** `bun -e "const d=await Bun.file('.specs/project/FEATURES.json').json(); console.log('active:', d.active_feature); for (const f of d.features??[]) console.log(f.id, f.status);"`
 - **Full feature registry:** `cat .specs/project/FEATURES.json`
 - **Project state:** `cat .specs/project/STATE.md`
 - **Handoff:** `cat .specs/HANDOFF.md`
 - **Feature spec:** `cat .specs/features/<slug>/spec.md`
-- **Confirmed lessons:** `python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed [--scope <relevant>]`
+- **Confirmed lessons:** `bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed [--scope <relevant>]`
 
 ## Writing Artifacts
 
-Write artifacts directly to `.specs/` files. Use a here-doc or `printf` for Markdown, or `python3 -c` for JSON mutations.
+Write artifacts directly to `.specs/` files. Use a here-doc or `printf` for Markdown, or `bun -e` for JSON mutations.
 
 - **Update state:** `printf '...' > .specs/project/STATE.md`
 - **Update handoff:** `printf '...' > .specs/HANDOFF.md`
 - **Write feature artifact:** `printf '...' > .specs/features/<slug>/design.md`
-- **Update feature registry:** use `python3 -c` to read-modify-write `FEATURES.json`
+- **Update feature registry:** use `bun -e` to read-modify-write `FEATURES.json`
 
 Feature activate/complete flows update `.specs/project/FEATURES.json`, `.specs/project/STATE.md`, and `.specs/HANDOFF.md` through file writes.
 
@@ -83,7 +82,7 @@ Feature activate/complete flows update `.specs/project/FEATURES.json`, `.specs/p
 
 - Feature artifacts under `.specs/features/<slug>/` are versioned by design (one file per slug).
 - `.specs/project/FEATURES.json` and `.specs/project/STATE.md` are append-only versioned by their git history.
-- `lessons.json` versioning is managed automatically by `lessons.py`.
+- `lessons.json` versioning is managed automatically by `lessons.ts`.
 - When content must be superseded (e.g., a decision), update the existing file and rely on git history for the prior version.
 
 ## Debug Exports
@@ -94,5 +93,5 @@ Exports under `.specs-exports/` are optional, untracked review aids. Use `cp -r
 
 - `.specs/` directory missing or not writable: block spec-driven state mutation; do not fall back to memory or chat.
 - Required artifact missing: create it on first write or block unless it is an approved initial creation.
-- `lessons.py` unavailable: skip lessons loading/recording, record skipped reason in validation report.
+- `lessons.ts` unavailable: skip lessons loading/recording, record skipped reason in validation report.
 .specs/ files

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

@@ -35,7 +35,7 @@ Read `.specs/features/<slug>/spec.md` before designing. If `.specs/features/<slu
 
 Silently ignoring an active decision is not an option — it creates invisible inconsistency across features.
 
-**Also load confirmed lessons** relevant to this feature: `python3 skills/massa-ai/scripts/lessons.py list --status confirmed` (filter with `--scope`/`--query`). These are past verification failures distilled into guidance — apply them while designing. Load only `confirmed`. Skip silently if no store or no code tool. See [lessons.md](lessons.md).
+**Also load confirmed lessons** relevant to this feature: `bun skills/massa-ai/scripts/lessons.ts list --status confirmed` (filter with `--scope`/`--query`). These are past verification failures distilled into guidance — apply them while designing. Load only `confirmed`. Skip silently if no store or no code tool. See [lessons.md](lessons.md).
 
 ### 1.5. Research (Optional but Recommended)
 

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

@@ -302,13 +302,13 @@ for reuse across multiple endpoints.
 - Never sneak in "while I'm here" changes.
 - If tests are part of the task, include them in the same commit.
 
-**Deterministic backing (run it, do not eyeball it):** `python3 skills/massa-ai/scripts/check_commit.py --message "<your message>"` before committing. A non-zero exit means fix the format first — this makes the format rule enforceable instead of memory-dependent. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+**Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/check_commit.ts --message "<your message>"` before committing. A non-zero exit means fix the format first — this makes the format rule enforceable instead of memory-dependent. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
 
 **Optional git-level guard (git only, no agent dependency).** In a git repo the same check can run on every commit by wiring it as a `commit-msg` hook, so a malformed message is rejected regardless of who or what drives the commit:
 
 ```bash
 # from the repo root, one time:
-ln -sf skills/massa-ai/scripts/check_commit.py .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
+ln -sf skills/massa-ai/scripts/check_commit.ts .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
 ```
 
 This is a plain git hook, not tied to any editor or assistant. Skip it if the project manages hooks its own way (for example a pre-commit framework); the manual check above still applies.
@@ -316,14 +316,14 @@ This is a plain git hook, not tied to any editor or assistant. Skip it if the pr
 **Distill a confirmed lesson** when a task produced a reusable signal (an unexpected failure mode, a confirmed pattern, a corrected assumption):
 
 ```
-python3 skills/massa-ai/scripts/lessons.py --root . add \
+bun skills/massa-ai/scripts/lessons.ts --root . add \
   --feature <slug> --signal <S> --source <src> --text "<T>" --scope <O>
 ```
 
 `--source` is mandatory (grounding gate). Load applicable confirmed lessons before starting a task:
 
 ```
-python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed [--scope <relevant>]
+bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed [--scope <relevant>]
 ```
 
 ### 8. Scope Guardrail / Scope Control
@@ -452,7 +452,7 @@ Then run `references/spec-driven/validate.md` as the final Execute gate. The ver
 **Status**: ✅ Complete | ❌ Blocked | ⚠️ Partial
 ```
 
-**After the LAST task:** dispatch the Verifier sub-agent (see step 9 and [sub-agents.md](sub-agents.md)) for independent feature-level validation, including the spec-anchored check and discrimination sensor. Validation always runs automatically — never prompted. Execute is not done until the Verifier reports PASS and the validation report is written, confirmed deterministically by `python3 skills/massa-ai/scripts/validate_state.py <feature> [--root .]` (exit non-zero = not done); see [validate.md](validate.md). If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+**After the LAST task:** dispatch the Verifier sub-agent (see step 9 and [sub-agents.md](sub-agents.md)) for independent feature-level validation, including the spec-anchored check and discrimination sensor. Validation always runs automatically — never prompted. Execute is not done until the Verifier reports PASS and the validation report is written, confirmed deterministically by `bun skills/massa-ai/scripts/validate_state.ts <feature> [--root .]` (exit non-zero = not done); see [validate.md](validate.md). If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
 
 ---
 

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

@@ -9,7 +9,7 @@ If the feature has ambiguous gray areas (multiple valid approaches for user-faci
 - First user request and any supplied requirement source.
 - Current repository source and docs needed to understand scope.
 - Existing `.specs/features/<slug>/` artifacts when resuming.
-- `.specs/LESSONS.md` only when lessons are enabled by existing lesson artifacts.
+- `.specs/lessons.json` (via `lessons list`) only when lessons are enabled by existing lesson artifacts.
 
 ## Required Sections
 
@@ -65,7 +65,7 @@ The table is canonical; the prose is the applied sweep. **Large/Complex** work m
 
 ### 1. Clarify Requirements
 
-**Load confirmed lessons first:** Before clarifying, load the project's confirmed lessons so past verification failures shape this spec instead of repeating. Run `python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed` (optionally `--scope [area]` or `--query [term]` for the area this feature touches) and apply what comes back as guidance. Load only `confirmed` — never `candidate` or `quarantined`. If no store exists yet or no code tool is available, skip silently. See [lessons.md](../lessons.md).
+**Load confirmed lessons first:** Before clarifying, load the project's confirmed lessons so past verification failures shape this spec instead of repeating. Run `bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed` (optionally `--scope [area]` or `--query [term]` for the area this feature touches) and apply what comes back as guidance. Load only `confirmed` — never `candidate` or `quarantined`. If no store exists yet or no code tool is available, skip silently. See [lessons.md](../lessons.md).
 
 **Lightweight context scan first (Knowledge Verification Chain Step 1):** Before asking questions, briefly scan existing code, patterns, and neighboring features relevant to this feature. Prefer massa-ai tooling first (`list_projects`, `search`, `project_map`, `optimized_context`) before `ast-grep`/`rg`/`grep`, honoring freshness and source-precedence (current source overrides stale index/memory). Use what you find to ground your clarifying questions in reality — not to constrain the spec to current implementation. Keep it lightweight (stay within the <40k token budget; reuse the chain, no new machinery). The spec captures WHAT is needed, not only what exists.
 
@@ -115,7 +115,7 @@ Write every acceptance criterion in **EARS** (Easy Approach to Requirements Synt
 
 **Why patterns beat one shape:** failure states, state transitions, and optional behavior become first-class criteria instead of footnotes squeezed into WHEN/THEN. The patterns map onto the implicit-requirement dimensions above: state-transition integrity to State-driven; failure and external-dependency failure to Unwanted-behavior; feature flags to Optional-feature.
 
-**Rules:** one requirement per criterion (never bundle two behaviors); use concrete values (a specific status code, a specific message, a bound) rather than "quickly" or "gracefully"; every criterion contains a SHALL and is measurable. `python3 skills/massa-ai/scripts/validate_spec.py` flags any criterion without a SHALL and any that matches no recognized pattern.
+**Rules:** one requirement per criterion (never bundle two behaviors); use concrete values (a specific status code, a specific message, a bound) rather than "quickly" or "gracefully"; every criterion contains a SHALL and is measurable. `bun skills/massa-ai/scripts/validate_spec.ts` flags any criterion without a SHALL and any that matches no recognized pattern.
 
 ### 4. Requirement Closure Gate (before confirm)
 
@@ -135,7 +135,7 @@ Before Design, Tasks, or Execute — and before presenting the spec for confirma
 
 6. **Continue only when** the Open Questions table is empty or every row has an accepted assumption.
 
-7. **Deterministic backing (run it, do not eyeball it):** `python3 skills/massa-ai/scripts/validate_spec.py <feature> [--root .]` checks that required sections exist, every AC is EARS-shaped (has a SHALL), no Assumptions row has an empty default or rationale, and requirement IDs are well-formed. A non-zero exit means fix before confirming — the script checks structure; the judgment calls (is the interpretation right, is the outcome precise) stay yours. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+7. **Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/validate_spec.ts <feature> [--root .]` checks that required sections exist, every AC is EARS-shaped (has a SHALL), no Assumptions row has an empty default or rationale, and requirement IDs are well-formed. A non-zero exit means fix before confirming — the script checks structure; the judgment calls (is the interpretation right, is the outcome precise) stay yours. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
 
 Fix inline. This gate is bounded to THIS feature's stated dimensions and actual behavior — never to "anything imaginable." The Out of Scope table and anti-scope-creep rules remain the counterweights: the gate clarifies existing requirements, it never invents new ones.
 
@@ -286,13 +286,13 @@ How we know the feature is successful:
 - **Edge cases matter** — What breaks? What's empty? What's huge?
 - **Out of Scope prevents creep** — If it's not here, it doesn't get built
 - **Closure gate before confirm** — Three checks: unambiguity + precision, open-questions/assumptions closure, declined gray areas logged; scope-tiered; bounded to stated dimensions; never invents requirements
-- **Confirm after the gate passes** — Present the spec for user confirmation only after the closure gate passes (no unresolved-and-unmarked items remain) and `validate_spec.py` exits clean; user approves spec before moving to the discuss phase
+- **Confirm after the gate passes** — Present the spec for user confirmation only after the closure gate passes (no unresolved-and-unmarked items remain) and `validate_spec.ts` exits clean; user approves spec before moving to the discuss phase
 
 ---
 
 ## Done
 
-Specify is done when every requirement has an ID, acceptance criteria are testable EARS statements, edge cases are named, out-of-scope boundaries are explicit, implicit-requirement dimensions are resolved or marked `N/A because <reason>`, the Requirement Closure Gate is satisfied, and `validate_spec.py` exits clean (or the no-code-execution-tool fallback was applied).
+Specify is done when every requirement has an ID, acceptance criteria are testable EARS statements, edge cases are named, out-of-scope boundaries are explicit, implicit-requirement dimensions are resolved or marked `N/A because <reason>`, the Requirement Closure Gate is satisfied, and `validate_spec.ts` exits clean (or the no-code-execution-tool fallback was applied).
 
 ## Massa-ai Integration
 

package/skills/massa-ai/references/spec-driven/sub-agents.md

@@ -148,7 +148,7 @@ Delegated work returns through the compact summary contract above. Planning, tas
 
 ## Standalone Fallback
 
-When sub-agents are unavailable (a single agent executing the full feature), use the standalone fresh-eyes fallback: run `references/spec-driven/validate.md` as a standalone pass — clear implementation assumptions, re-read `spec.md` and the diff from scratch, apply evidence-or-zero, run the spec-anchored coverage check and discrimination sensor, and write `.specs/features/<slug>/validation.md`. **Deterministic backing (run it, do not eyeball it):** `python3 skills/massa-ai/scripts/validate_state.py <feature> [--root .]` confirms the report is a real PASS before the feature is marked done. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+When sub-agents are unavailable (a single agent executing the full feature), use the standalone fresh-eyes fallback: run `references/spec-driven/validate.md` as a standalone pass — clear implementation assumptions, re-read `spec.md` and the diff from scratch, apply evidence-or-zero, run the spec-anchored coverage check and discrimination sensor, and write `.specs/features/<slug>/validation.md`. **Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/validate_state.ts <feature> [--root .]` confirms the report is a real PASS before the feature is marked done. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
 
 ---
 

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

@@ -157,7 +157,7 @@ This keeps phase boundaries meaningful while letting the packing hit its target
 
 Before showing tasks to the user, run ALL three pre-approval checks. These are NOT optional — they are gates. If any check fails, restructure the tasks and re-run until all pass.
 
-**Deterministic backing (run it, do not eyeball it):** `python3 skills/massa-ai/scripts/validate_tasks.py <feature> [--root .]` enforces the structural half of these checks so they cannot drift: it flags a `Where` that names multiple files (granularity smell, Check 1), a diagram edge with no matching `Depends on` within a phase and vice-versa (Check 2), a task missing its `Tests` or `Gate` field, a `Tests: none` to confirm against the matrix (Check 3), and any dependency pointing to a later phase. A non-zero exit means restructure before presenting. The script checks structure; the two tables below (the layer-to-test co-location judgment) are still yours. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+**Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/validate_tasks.ts <feature> [--root .]` enforces the structural half of these checks so they cannot drift: it flags a `Where` that names multiple files (granularity smell, Check 1), a diagram edge with no matching `Depends on` within a phase and vice-versa (Check 2), a task missing its `Tests` or `Gate` field, a `Tests: none` to confirm against the matrix (Check 3), and any dependency pointing to a later phase. A non-zero exit means restructure before presenting. The script checks structure; the two tables below (the layer-to-test co-location judgment) are still yours. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
 
 **Check 1: Task Granularity** — verify each task is atomic (see Granularity Check section).
 
@@ -516,4 +516,4 @@ Before sampling tests manually, prefer massa-ai tooling to read the codebase:
 
 ## Done
 
-Tasks is done when every in-scope requirement maps to one or more executable tasks, dependencies are explicit, the Test Coverage Matrix and Gate Check Commands are present, project testing guideline scan and pre-approval checks are recorded, the three mandatory pre-approval tables (Granularity, Diagram-Definition Cross-Check, Test Co-location Validation) pass, `validate_tasks.py` exits clean (or the no-code-execution-tool fallback was applied), and each task has deterministic validation with artifact-store evidence recorded.
+Tasks is done when every in-scope requirement maps to one or more executable tasks, dependencies are explicit, the Test Coverage Matrix and Gate Check Commands are present, project testing guideline scan and pre-approval checks are recorded, the three mandatory pre-approval tables (Granularity, Diagram-Definition Cross-Check, Test Co-location Validation) pass, `validate_tasks.ts` exits clean (or the no-code-execution-tool fallback was applied), and each task has deterministic validation with artifact-store evidence recorded.

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

@@ -204,14 +204,14 @@ After all checks complete, the Verifier MUST:
 1. **Write the persisted report** to `.specs/features/<slug>/validation.md` (see template below). This file is the evidence artifact — it survives the session and can be referenced by CI, reviewers, or future agents. Record in `.specs/project/STATE.md` (Decisions) that validation evidence is available at that path.
 2. **Return a compact summary in chat** to the orchestrator (see Compact Chat Summary section below). The orchestrator surfaces it to the user and routes any ranked gaps to fix tasks.
 
-**Deterministic backing (run it, do not eyeball it):** after writing the report, run `python3 skills/massa-ai/scripts/validate_state.py <feature> [--root .]`. It confirms the report is real — present, verdict filled to PASS, and backed by at least one `file:line` evidence citation — so a missing, hollow, placeholder, or FAIL report cannot slip through as done. A non-zero exit means the feature is NOT done: repair the report or route the FAIL gaps to fix tasks, then re-run. This is the closing gate of Execute and runs automatically, the same way the lessons layer runs at distillation — never a manual step. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+**Deterministic backing (run it, do not eyeball it):** after writing the report, run `bun skills/massa-ai/scripts/validate_state.ts <feature> [--root .]`. It confirms the report is real — present, verdict filled to PASS, and backed by at least one `file:line` evidence citation — so a missing, hollow, placeholder, or FAIL report cannot slip through as done. A non-zero exit means the feature is NOT done: repair the report or route the FAIL gaps to fix tasks, then re-run. This is the closing gate of Execute and runs automatically, the same way the lessons layer runs at distillation — never a manual step. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
 
 ### 10. Distill Lessons (MANDATORY when validation.md has signal)
 
 This is the closing action of validation — not a separate phase. Immediately after the report is written, turn its grounded failures into reusable, project-local guidance by following [references/lessons.md](../lessons.md) and the stub at [references/spec-driven/lessons.md](lessons.md). In short: for each surviving mutant, spec-precision gap, failed/uncovered AC, or `// SPEC_DEVIATION`, record one terse general lesson via:
 
 ```bash
-python3 skills/massa-ai/scripts/lessons.py --root . add --feature <slug> --signal "<signal>" --source "<source>" --text "<lesson>" --scope "<scope>"
+bun skills/massa-ai/scripts/lessons.ts --root . add --feature <slug> --signal "<signal>" --source "<source>" --text "<lesson>" --scope "<scope>"
 ```
 
 The script enforces grounding (mandatory `--source`) and owns all bookkeeping. A clean PASS with no signal → record nothing. Run the self-check: if there was signal but no lesson was recorded, say so in chat. See [references/lessons.md](../lessons.md) for the exact commands, phrasing rules, scope discipline, and the no-script fallback.
@@ -398,5 +398,5 @@ Update `.specs/features/<slug>/spec.md` requirement statuses and reflect verifie
 - **Max 3 diagnostic iterations** — Prevents infinite investigation loops
 - **Update traceability** — Every verified requirement updates spec.md status and the FEATURES.json registry
 - **Always write the report file** — `.specs/features/<slug>/validation.md` is the persisted evidence artifact
-- **Distill after writing** — turn grounded failures into lessons via `python3 skills/massa-ai/scripts/lessons.py` ([references/lessons.md](../lessons.md)); clean PASS → no lesson
+- **Distill after writing** — turn grounded failures into lessons via `bun skills/massa-ai/scripts/lessons.ts` ([references/lessons.md](../lessons.md)); clean PASS → no lesson
 - **Independence first** — prefer a fresh read-only verifier; the author never verifies their own work when tooling allows

package/skills/massa-ai/scripts/check_commit.ts

@@ -0,0 +1,231 @@
+#!/usr/bin/env bun
+/**
+ * check_commit.ts - deterministic Conventional Commits validation.
+ *
+ * The per-task atomic-commit rule mandates Conventional Commits 1.0.0. This makes
+ * that rule checkable instead of trusting the model to remember the format. Bun
+ * builtins only, zero dependencies, agent-agnostic.
+ *
+ * It reads the message from (in priority order): a positional file path, --message,
+ * or stdin. The file-path form matches how git passes the message file to a
+ * `commit-msg` hook, so this doubles as an optional git-level guard WITHOUT
+ * coupling the skill to any AI agent:
+ *
+ *     ln -s skills/massa-ai/scripts/check_commit.ts .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
+ *
+ * What it checks:
+ *   ERROR  - header does not match  type(scope)!: description
+ *            (an optional leading `[KEY] ` Jira-style prefix is stripped first -
+ *            see massa-ai's `workflows/commit.md` §8, e.g. `[SA-142] feat(x): y`)
+ *   ERROR  - type is not one of the allowed Conventional Commits types
+ *   ERROR  - description is empty, starts uppercase, or ends with a period
+ *   ERROR  - `!` breaking marker present but no `BREAKING CHANGE:` footer
+ *   WARN   - header longer than 72 characters
+ *
+ * Usage:
+ *   bun skills/massa-ai/scripts/check_commit.ts [msgfile]
+ *   bun skills/massa-ai/scripts/check_commit.ts --message "feat(auth): add email validation"
+ *   bun skills/massa-ai/scripts/check_commit.ts --message "[SA-142] feat(auth): reject expired tokens"
+ *   echo "fix(cart): prevent negative quantity" | bun skills/massa-ai/scripts/check_commit.ts
+ *
+ * Exit codes: 0 pass, 1 violation, 2 usage error.
+ */
+
+import { readFileSync } from "node:fs";
+
+const TYPES = ["feat", "fix", "refactor", "docs", "test", "style", "perf", "build", "ci", "chore"];
+
+// massa-ai patch (D1c): an optional leading Jira-style key prefix, e.g.
+// "[SA-142] feat(auth): reject expired tokens" (workflows/commit.md §8). The
+// key shape mirrors the branch-key regex there: [A-Z][A-Z0-9]{1,9}-\d+.
+const PREFIX_RE = /^\[(?<key>[A-Z][A-Z0-9]{1,9}-\d+)\]\s+(?<rest>.+)$/;
+const HEADER_RE = /^(?<type>\w+)(?:\((?<scope>[^)]+)\))?(?<bang>!)?: (?<desc>.+)$/;
+
+const USAGE = "usage: check_commit.ts [-h] [--message MESSAGE] [msgfile]";
+const HELP = `${USAGE}
+
+Validate a Conventional Commits message.
+
+positional arguments:
+  msgfile               path to a commit message file (as git passes to commit-msg)
+
+options:
+  -h, --help            show this help message and exit
+  --message MESSAGE     the commit message as a string`;
+
+interface Args {
+  msgfile: string | null;
+  message: string | null;
+}
+
+/** Mirrors Python's str.splitlines(): universal newline split, no trailing empty element. */
+function splitLines(text: string): string[] {
+  if (text === "") return [];
+  const result: string[] = [];
+  const lineBreakRe = /\r\n|\r|\n/g;
+  let start = 0;
+  let match: RegExpExecArray | null;
+  while ((match = lineBreakRe.exec(text)) !== null) {
+    result.push(text.slice(start, match.index));
+    start = match.index + match[0].length;
+  }
+  if (start < text.length) {
+    result.push(text.slice(start));
+  }
+  return result;
+}
+
+/** Mirrors Python's repr() for plain-text strings (single-quoted, backslash/quote/control escapes). */
+function pyRepr(s: string): string {
+  const hasSingle = s.includes("'");
+  const hasDouble = s.includes('"');
+  const quote = hasSingle && !hasDouble ? '"' : "'";
+  let out = quote;
+  for (const ch of s) {
+    if (ch === "\\") out += "\\\\";
+    else if (ch === quote) out += "\\" + quote;
+    else if (ch === "\n") out += "\\n";
+    else if (ch === "\r") out += "\\r";
+    else if (ch === "\t") out += "\\t";
+    else {
+      const code = ch.codePointAt(0)!;
+      if (code < 0x20 || code === 0x7f) {
+        out += "\\x" + code.toString(16).padStart(2, "0");
+      } else {
+        out += ch;
+      }
+    }
+  }
+  out += quote;
+  return out;
+}
+
+function printUsageError(msg: string): void {
+  process.stderr.write(`${USAGE}\ncheck_commit.ts: error: ${msg}\n`);
+}
+
+function parseArgs(argv: string[]): Args | null {
+  let message: string | null = null;
+  const positionals: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--message") {
+      if (i + 1 >= argv.length) {
+        printUsageError("argument --message: expected one argument");
+        return null;
+      }
+      message = argv[++i];
+    } else if (a.startsWith("--message=")) {
+      message = a.slice("--message=".length);
+    } else if (a === "-h" || a === "--help") {
+      console.log(HELP);
+      process.exit(0);
+    } else if (a.startsWith("-") && a !== "-") {
+      printUsageError(`unrecognized arguments: ${a}`);
+      return null;
+    } else {
+      positionals.push(a);
+    }
+  }
+  if (positionals.length > 1) {
+    printUsageError(`unrecognized arguments: ${positionals.slice(1).join(" ")}`);
+    return null;
+  }
+  return { msgfile: positionals[0] ?? null, message };
+}
+
+function readMessage(args: Args): string {
+  if (args.message !== null) return args.message;
+  if (args.msgfile) {
+    return readFileSync(args.msgfile, "utf-8");
+  }
+  if (!process.stdin.isTTY) {
+    try {
+      return readFileSync(0, "utf-8");
+    } catch {
+      return "";
+    }
+  }
+  return "";
+}
+
+function check(message: string): { errors: string[]; warnings: string[] } {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  // Ignore comment lines (git puts '#' comments in the message file).
+  let lines = splitLines(message).filter((ln) => !ln.trimStart().startsWith("#"));
+  // Trim leading blank lines.
+  while (lines.length && !lines[0]!.trim()) {
+    lines.shift();
+  }
+  if (!lines.length) {
+    return { errors: ["empty commit message"], warnings };
+  }
+
+  const header = lines[0]!.replace(/\s+$/, "");
+  if (header.length > 72) {
+    warnings.push(`header is ${header.length} chars (>72): ${header.slice(0, 60)}...`);
+  }
+
+  // Strip an optional massa-ai Jira-style `[KEY] ` prefix before matching the
+  // Conventional Commits header shape.
+  const prefixed = PREFIX_RE.exec(header);
+  const headerBody = prefixed?.groups?.rest ?? header;
+
+  const m = HEADER_RE.exec(headerBody);
+  if (!m || !m.groups) {
+    errors.push(`header does not match 'type(scope): description': ${pyRepr(header)}`);
+    return { errors, warnings };
+  }
+
+  const ctype = m.groups.type!;
+  const desc = m.groups.desc!;
+  const bang = m.groups.bang;
+
+  if (!TYPES.includes(ctype)) {
+    errors.push(`type '${ctype}' is not one of: ${TYPES.join(", ")}`);
+  }
+  if (!desc.trim()) {
+    errors.push("description is empty");
+  } else {
+    if (/\p{Lu}/u.test(desc[0]!)) {
+      errors.push(`description should start lowercase: '${desc.slice(0, 30)}'`);
+    }
+    if (desc.replace(/\s+$/, "").endsWith(".")) {
+      errors.push("description should not end with a period");
+    }
+  }
+
+  const body = lines.slice(1).join("\n");
+  const breakingFooter = /^BREAKING CHANGE:/m.test(body);
+  if (bang && !breakingFooter) {
+    errors.push("'!' breaking marker present but no 'BREAKING CHANGE:' footer");
+  }
+
+  return { errors, warnings };
+}
+
+function main(argv: string[]): number {
+  const args = parseArgs(argv);
+  if (args === null) return 2;
+
+  const message = readMessage(args);
+  if (!message.trim()) {
+    console.error("check_commit: no message provided (pass a file, --message, or pipe via stdin).");
+    return 2;
+  }
+
+  const { errors, warnings } = check(message);
+  for (const w of warnings) console.log(`  WARN  ${w}`);
+  for (const e of errors) console.log(`  ERROR ${e}`);
+  if (errors.length) {
+    console.log("\ncheck_commit: FAIL - see https://www.conventionalcommits.org/en/v1.0.0/");
+    return 1;
+  }
+  console.log("check_commit: OK");
+  return 0;
+}
+
+if (import.meta.main) {
+  process.exit(main(process.argv.slice(2)));
+}