@massa-ai/cursor-plugin 1.21.0 → 1.23.0

package/.cursor-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "massa-ai",
-  "version": "1.21.0",
+  "version": "1.23.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.23.0",
   "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
   "files": [
     "agents",

package/skills/massa-ai/SKILL.md

@@ -60,6 +60,14 @@ Before reading any massa-ai file:
 - Persist only durable, useful knowledge. Do not fabricate memories to satisfy
   process. Use `memory_update` to correct stale memories and `memory_delete`
   to remove obsolete ones.
+- Expand every word abbreviation on first use in user-facing output — e.g.
+  "PR (Pull Request)", "AC (Acceptance Criteria)", "KMP (Kotlin Multiplatform)"
+  — including workflow-specific shorthands and finding-ID families.
+- Use one uniform vocabulary for separating batches of work in every workflow:
+  a **Task** is the atomic unit; a **Phase** is an ordered group of Tasks.
+  Report a phase's size as `1 Phase = X Tasks` and a plan's total as
+  `Y Phases = Z Tasks`. Do not substitute synonyms such as batch, wave, stage,
+  or chunk for these units in agent prose.
 - Emit concise user-facing status updates at meaningful workflow boundaries
   when the Conversation Feedback Policy is active.
 - Verify, don't assume: every factual claim that drives a decision is
@@ -275,6 +283,7 @@ Load only when a selected workflow asks for them:
 - `references/debug-diagnosis-loop.md`
 - `references/mobile-context.md`
 - `references/mobile-diagnosis.md`
+- `references/figma-pre-analysis.md`
 - `references/mobile-figma-matcher/`
 - `references/lessons.md`
 - `references/naming-standards.md`

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/figma-pre-analysis.md

@@ -0,0 +1,69 @@
+# Figma Pre-Analysis And Sequential Retrieval
+
+Load this reference whenever a workflow receives one or more Figma links, node
+IDs, or a readable desktop selection as a design source — the Figma audit/fix
+family (`mobile-figma-audit`, `mobile-figma-fix`), `design`, and the
+design-source gates of implementation workflows (`feature`, `spec-driven`).
+This reference owns the orchestration protocol only; Figma Evidence Packet
+field contracts stay in `references/mobile-figma-matcher/core.md`.
+
+The protocol is the single normative copy. Workflows point here; they do not
+restate it.
+
+## Why Two Stages
+
+Full Figma extraction on unscoped links overloads one context with mixed
+screens, buries feature boundaries, and makes evidence non-attributable. A
+cheap pre-analysis pass first maps what the links contain, so each retrieval
+pass reads one coherent slice.
+
+## Stage 1 — Pre-Analysis (always first, exactly one subagent)
+
+Dispatch one read-only subagent (investigator-class; Figma MCP — Model Context
+Protocol — access, no repository mutation) over the user-provided Figma links.
+Its job is understanding, **not** extraction:
+
+- Summarize composition: pages, screens, frames, component sets, shared tokens.
+- Summarize product context: what the screens are for, the features they serve,
+  and the user flows connecting them.
+- It does not build Figma Evidence Packet fields, does not resolve variables or
+  exact geometry, and does not compare against source code.
+
+Its output is a compact packet:
+
+1. **Context summary** — screens/features/flows in prose, sized for the main
+   agent's context budget.
+2. **Partition proposal** — how many retrieval subagents should read which
+   links/nodes/screen groups, partitioned by:
+   - **Size:** each slice must fit one subagent's context comfortably.
+   - **Coupling:** screens sharing tokens, components, or a design system
+     section stay in one slice.
+   - **Feature flow:** one user flow per slice when possible, so evidence
+     stays attributable to a feature.
+   A single small screen legitimately yields a one-slice proposal.
+
+The main agent reviews the proposal, adjusts slice boundaries if project
+knowledge contradicts them, and records the final partition before Stage 2.
+
+## Stage 2 — Sequential Retrieval (N subagents, one at a time)
+
+The main agent orchestrates the retrieval subagents **strictly sequentially —
+never in parallel**. For each slice, in the recorded order:
+
+1. Dispatch one read-only retrieval subagent scoped to that slice's
+   links/nodes, carrying the Stage 1 context summary and the slice's purpose.
+2. Wait for completion; fold its output into the workflow's Figma Evidence
+   Packet (or Screenshot Context Packet rows) before dispatching the next.
+3. Let each completed slice inform the next dispatch prompt — resolved shared
+   tokens, discovered variants, and naming conventions carry forward.
+
+Sequential dispatch is a hard rule, not a tuning choice: it respects Figma MCP
+session/rate limits, and it is what lets slice N+1 reuse what slice N learned.
+Retrieval subagents never spawn further subagents.
+
+## Fallback
+
+If subagent spawning is unavailable (forbidden, plugin missing, unknown agent
+type), run both stages inline in the main agent in the same order — pre-analysis
+summary first, then per-slice retrieval — and record the skipped delegation
+with its reason. Do not skip Stage 1 because delegation is unavailable.

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.
 
@@ -90,6 +90,18 @@ title: `[SA-100] Phase 1: search facade split`. The per-task commit prefixes on
 the branch are owned by `workflows/commit.md`; this stage owns only the PR-level
 phase prefix. Non-phased work keeps the existing PR title behavior unchanged.
 
+### Stages 3–7 — the PR description stays current
+
+The PR description is a living artifact, not a creation-time snapshot. After
+**every push requested while the PR exists** — repair iterations, follow-up
+tasks, review-requested changes — update the PR description with
+`gh pr edit <number> --body <b>` so it reflects the branch's current commit
+set, scope, and evidence **before** returning to Watch. The description must be
+current before the merge decision is requested; a merge may never be proposed
+over a description that describes an older state of the branch. When generated
+or bundled files are regenerated alongside source edits, the description names
+that blast radius explicitly so reviewers do not undercount the diff.
+
 ### Stage 7 — merge is never automatic
 
 Do not run `gh pr merge` without explicit user approval given in the current
@@ -126,6 +138,8 @@ silently did not run is worse than one that loudly failed.
 - Merging because CI passed. CI passing is the precondition for asking, not the
   approval itself.
 - Reporting "done" while the branch is unpushed.
+- Proposing or performing a merge while the PR description still describes an
+  older commit set — update it after each requested push, before merging.
 
 ## Completion Evidence
 

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/mobile-context.md

@@ -76,6 +76,25 @@ For design, mobile Figma audit, or mobile Figma fix, load `references/mobile-fig
 
 Never rely on model self-evaluation. If device access, signing, credentials, provisioning, or hardware is unavailable, state the missing dependency and use the strongest available artifact or static proof.
 
+## Compose Screen Previews
+
+In every implementation workflow, when the target surface is Android Jetpack
+Compose or KMP (Kotlin Multiplatform) Compose Multiplatform, every created or
+updated screen-level composable ships with `@Preview` composables in the same
+change:
+
+- Cover the representative states the change touches (default content, loading,
+  error, and empty where they exist), using preview parameter providers when
+  the project already uses them.
+- Follow the project's existing preview conventions (naming, placement,
+  multipreview annotations, theme wrappers) rather than inventing new ones.
+- Previews are validation assets: never delete or weaken an existing preview to
+  make a change compile, and treat a screen edit that leaves its previews stale
+  as incomplete work.
+- On KMP, place previews in the source set where the project renders them
+  (commonMain multiplatform previews or per-platform preview hosts), matching
+  established project layout.
+
 ## Tests Lens
 
 When auditing or executing test work, check mobile-specific coverage for:

package/skills/massa-ai/references/mobile-diagnosis.md

@@ -4,7 +4,7 @@ Use this reference when `workflows/debug.md` handles broken behavior involving K
 
 This extends `references/debug-diagnosis-loop.md`. Do not use it instead of the general debug loop.
 
-For non-debug mobile feature, refactor, tests, or security work, keep the intent-specific workflow and load `references/mobile-context.md` instead. Use `references/mobile-context.md` from Debug only when shared mobile vocabulary or non-bug parity/security/test framing is needed.
+For non-debug mobile feature, refactor, tests, or security work, keep the intent-specific workflow and load `references/mobile-context.md` instead. Use `references/mobile-context.md` from Debug only when shared mobile vocabulary or non-bug parity/security/test framing is needed — and always when a fix creates or updates a Compose screen, because its Compose Screen Previews rule (`@Preview` coverage) applies to debug-path edits too.
 
 ## Mobile Intake
 

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