@massa-ai/cursor-plugin 1.20.0 → 1.22.0

package/skills/massa-ai/workflows/spec-driven.md

@@ -27,6 +27,7 @@ Holds for every task, even if reference files are not opened:
 2. The gate must pass (tests pass) before a task is done — the test runner decides, not self-assessment.
 3. One atomic commit per task. Never batch tasks; never weaken, skip, or delete tests to make them pass.
 4. After the last task, a fresh verification-agent always runs automatically (author ≠ verifier) — spec-anchored outcome check plus discrimination sensor. Never optional, never prompted.
+5. **Blast radius (approval ≠ remote authority):** Approving Execute for this feature authorizes local implementation and local commits, and covers one delivery through PR creation — branch push and `gh pr create` — under one explicit go-ahead given at Execute start. Force-push, deploy, production database changes, merges, and any other remote/externally-visible/destructive operation always require a separate explicit go-ahead, even after that authorization.
 
 ## Auto-Sizing
 
@@ -39,7 +40,7 @@ Complexity determines depth, not a fixed pipeline. Assess scope first, apply onl
 | Large | >10 tasks OR multi-component feature | Full spec + requirement IDs | Architecture + components | Full breakdown + deps | Implement + verify per task |
 | Complex | Ambiguity or new domain (unfamiliar vocabulary, no prior pattern) | Full spec + discuss gray areas | Research + architecture | Breakdown + phase plan | Implement + interactive UAT |
 
-A "phase" is a group of tasks sharing a dependency boundary or a checkpoint commit — it is distinct from a single task or atomic step. The sub-agent offer fires when a formal `tasks.md` packs into more than one task-budgeted batch (> ~8 tasks).
+A "phase" is a group of tasks sharing a dependency boundary or a checkpoint commit — it is distinct from a single task or atomic step. The sub-agent offer fires when a formal `tasks.md` has more than 3 tasks — packing itself still uses ~7-task batches; a 4–8-task feature is offered as a single batch worker.
 
 - Specify and Execute are always required.
 - Design is skipped when straightforward (no architectural decisions, no new patterns).
@@ -80,7 +81,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
    - Load current canonical artifacts from `.specs/` files: `.specs/project/FEATURES.json`, `.specs/project/STATE.md`, `.specs/HANDOFF.md`, existing `.specs/features/<slug>/` phase artifacts, lessons, and project source. Current repository source and approved `.specs/` artifacts override stale memory, old handoff notes, external summaries, debug exports, or unapproved generated plans.
    - `search` only counts as codebase evidence when it is fresh for the current repository path and commit/worktree state, or when the result is confirmed against source files read in this session.
    - Load confirmed project lessons through `references/lessons.md` when `.specs/lessons.json` exists:
-     `python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed`
+     `bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed`
 3. Run `Specify` with `references/spec-driven/specify.md`.
    - Capture stable requirement IDs, testable acceptance criteria, edge cases, and explicit out-of-scope items.
    - Run `references/spec-driven/discuss.md` inside Specify when gray areas, implicit requirements, persistence/state, external calls, auth, payments, concurrency, or state transitions affect behavior.
@@ -93,7 +94,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
    - Run repo-rules discovery from `references/repo-rules-discovery.md` before the first repository mutation: record the harness sources loaded (or `repo-rules: none present`), and implement so every new or changed file conforms to the target repo's module layout, unit-test location, and testing-area conventions. A repo rule wins over a skill default for placement and gate commands; record any deviation with an explicit reason. Never fabricate rules or create `.claude/`/`.cursor/` directories the repo lacks.
    - Use the Test Coverage Matrix and Gate Check Commands from `tasks.md`, or state their inline equivalents when Tasks was skipped.
    - Ask the MCP and skill question in Tasks or inline Execute when tool choice can change correctness or verification.
-   - If a formal `tasks.md` packs into more than one task-budgeted batch (> ~8 tasks), present the sub-agent offer from `references/spec-driven/sub-agents.md` before starting Execute. Offer-then-confirm — never auto-spawn; the user must accept before any sub-agent is dispatched. One worker per batch (~7 tasks, whole phases): each batch worker executes all its tasks in order (implement → gate → atomic commit), then reports a compact summary (tasks done, commit hashes, test counts, deviations). Workers never spawn further sub-agents.
+   - If a formal `tasks.md` has more than 3 tasks, present the sub-agent offer from `references/spec-driven/sub-agents.md` before starting Execute — even when packing yields a single batch (a 4–8-task feature is offered as one batch worker). Offer-then-confirm — never auto-spawn; the user must accept before any sub-agent is dispatched. One worker per batch (~7 tasks, whole phases): each batch worker executes all its tasks in order (implement → gate → atomic commit), then reports a compact summary (tasks done, commit hashes, test counts, deviations). Workers never spawn further sub-agents.
    - Implement one atomic step or approved task at a time.
    - For long-running task sequences, create a checkpoint via `create_checkpoint` at task boundaries with `taskId`, `description`, `progressPercent`, `currentStep`, `nextAction`, `fileChanges`, and `checkpointType: "manual"` so progress is resumable after interruption.
    - If resuming after interruption, call `list_checkpoints` with the `taskId` and `restore_checkpoint` to recover task state before continuing. If `create_checkpoint` is unavailable (e.g. `task_checkpoints` table missing), continue with `.specs/` artifact state as the fallback.
@@ -116,7 +117,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
     - The verification-agent re-derives coverage independently using evidence-or-zero and does not inherit the author's mental model.
    - The fix → re-verify loop is capped at 3 iterations before escalating to `Blocked`.
    - Distill lesson signals through `references/lessons.md` when validation produces grounded reusable failures.
-7. Update `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `references/spec-driven/memory.md` records for decisions, blockers, handoff, and completion evidence.
+7. Before the delivery chain's Propose stage (PR creation), write and commit `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `.specs/project/FEATURES.json` on the branch — not merely "after meaningful progress" during Execute, but committed before `gh pr create`. **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 (see `references/implementation-delivery.md` stage 3.5 and GATE-02). If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved). Record `references/spec-driven/memory.md` decisions, blockers, handoff, and completion evidence per that reference's write triggers.
 8. When the user splits planning and implementation across clean chats, resume from the canonical `.specs/` artifacts — `.specs/project/STATE.md`, `.specs/project/FEATURES.json`, `.specs/HANDOFF.md`, and the feature's phase files. This workflow owns the spec phase contracts on both sides of the split; there is no separate save/load procedure.
 9. Complete the configured Plan Challenge Gate for non-trivial plans and complete `references/evidence-gate.md` before claiming completion.
 
@@ -127,7 +128,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
 - Feature registry is `.specs/project/FEATURES.json`.
 - Handoff is `.specs/HANDOFF.md`.
 - `.specs/` files are canonical and git-tracked; there is no secondary store.
-- `.specs/lessons.json` is the machine-owned canonical lessons state; `.specs/LESSONS.md` is its rendered view, regenerated by `scripts/lessons.py` on every write — do not hand-edit.
+- `.specs/lessons.json` is the machine-owned canonical lessons state, the single lessons store — do not hand-edit; `lessons list` is the on-demand view.
 - Optional `.specs-exports/` projections are untracked debug aids only.
 - `remember` remains canonical for durable cross-session decisions, rejected approaches, reusable patterns, and verification recipes.
 
@@ -150,7 +151,7 @@ When researching, designing, or making any technical decision, follow this chain
 
 ```
 Step 1: Codebase → existing code, conventions, patterns already in use
-Step 2: Project docs → README, docs/, inline comments, .specs/project/STATE.md (Decisions)
+Step 2: Project docs (leads, not truth) → README, docs/, inline comments, .specs/project/STATE.md (Decisions) — verify against current source before relying
 Step 3: Context7 MCP → resolve library ID, then query for current API/patterns
 Step 4: Web search → official docs, reputable sources, community patterns
 Step 5: Flag as uncertain → "I'm not certain about X — here's my reasoning, but verify"

package/skills/massa-ai/workflows/tests/tests-fix.md

@@ -52,7 +52,7 @@ Do not use this workflow for findings-only test coverage, assertion quality, fix
 10. Use strict harness sensors:
    - Never rely on AI subjective evaluation.
    - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
-     `python3 skills/massa-ai/scripts/lessons.py --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
+     `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
    - Apply the Mandatory Verification Fix Gate from `references/verification-ladder.md`: run the report's Verification Suggestion or an equivalent deterministic command/artifact check for each selected finding or coherent group.
    - Run the actual focused test command first, then broader relevant suites when feasible, such as `rtk yarn test`, `rtk npm test`, `rtk pytest`, or `rtk cargo test`.
    - Continue only when the execution harness returns a clean exit code, or report the exact skipped-check reason.

package/skills/massa-ai/scripts/lessons.py

@@ -1,590 +0,0 @@
-#!/usr/bin/env python3
-"""
-Deterministic bookkeeping for the massa-ai spec-driven lessons layer.
-
-The LLM supplies judgment (which failure happened, how to phrase the lesson, what
-signal grounds it). This script owns everything mechanical: IDs, distinct-feature
-recurrence counting, candidate->confirmed promotion, pruning, demotion, and
-rendering the human/agent-readable playbook. Bookkeeping by hand is exactly what
-rots a lessons file, so it lives here, not in a prompt.
-
-Canonical state:  .specs/lessons.json   (machine-owned - do NOT hand-edit)
-Rendered view:    .specs/LESSONS.md      (regenerated on every write)
-
-Pure standard library. No dependencies. Pass --root with the target workspace
-root so the package-local script writes that workspace's .specs directory.
-
-Commands:
-  add        Record a grounded lesson from a verification signal.
-  list       Print lessons (default: confirmed) for loading at Specify/Design.
-  penalize   Mark a confirmed lesson as having failed when applied (-> quarantine).
-  prune      Drop stale uncorroborated candidates (also runs automatically on add/list).
-  status     Print counts (used by the self-check in validate.md).
-  init       Create empty store + rendered file.
-  observe    Ingest a JSON observation into the gitignored observations buffer.
-  export     Export the lessons store as JSON (round-trips with import).
-  import     Import lessons from JSON (merge by dedup key; best-effort massa-ai memory).
-
-Exit codes: 0 ok, 2 usage/validation error (e.g. missing grounding).
-"""
-
-import argparse
-import datetime as _dt
-import json
-import os
-import re
-import sys
-import urllib.request
-
-STORE_REL = os.path.join(".specs", "lessons.json")
-RENDER_REL = os.path.join(".specs", "LESSONS.md")
-OBS_REL = os.path.join(".specs", "observations.json")
-
-SIGNALS = {
-    "ac_gap": "Acceptance criterion not covered / failed",
-    "surviving_mutant": "Discrimination sensor mutant survived (weak test)",
-    "spec_precision_gap": "Spec did not define a precise outcome",
-    "spec_deviation": "Implementation diverged from spec/design (SPEC_DEVIATION)",
-    "gate_fail": "Build-level gate check failed",
-}
-
-DEFAULTS = {"promote_threshold": 2, "window_days": 45, "quarantine_threshold": 2}
-
-# massa-ai supported memory types (references/mcp-tools.md). `procedural` is a
-# TAG, never a type. Lessons are procedural knowledge -> type `pattern`.
-MASSA_AI_SUPPORTED_TYPES = ("critical", "conversation", "code", "decision", "pattern")
-MASSA_AI_LESSON_TYPE = "pattern"
-
-
-def _now():
-    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-def _parse_date(s):
-    try:
-        return _dt.datetime.strptime(s, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=_dt.timezone.utc)
-    except Exception:
-        return _dt.datetime.now(_dt.timezone.utc)
-
-
-def _store_path(root):
-    return os.path.join(root, STORE_REL)
-
-
-def _render_path(root):
-    return os.path.join(root, RENDER_REL)
-
-
-def _load(root):
-    path = _store_path(root)
-    if not os.path.exists(path):
-        return {
-            "schema": 1,
-            "promote_threshold": DEFAULTS["promote_threshold"],
-            "window_days": DEFAULTS["window_days"],
-            "quarantine_threshold": DEFAULTS["quarantine_threshold"],
-            "next_id": 1,
-            "lessons": [],
-        }
-    with open(path, "r", encoding="utf-8") as f:
-        data = json.load(f)
-    for k, v in DEFAULTS.items():
-        data.setdefault(k, v)
-    data.setdefault("schema", 1)
-    data.setdefault("next_id", 1)
-    data.setdefault("lessons", [])
-    return data
-
-
-def _save(root, data):
-    os.makedirs(os.path.join(root, ".specs"), exist_ok=True)
-    with open(_store_path(root), "w", encoding="utf-8") as f:
-        json.dump(data, f, indent=2, ensure_ascii=False)
-        f.write("\n")
-    _render(root, data)
-
-
-def _confidence(lesson, data):
-    """Deterministic 0-1 confidence from recurrence + signal + scope presence."""
-    rec_cap = min(lesson.get("recurrence", 1) / max(data["promote_threshold"], 1), 1.0)
-    sig_weight = 0.15
-    scope_weight = 0.10 if lesson.get("scope") else 0.0
-    return round(min(rec_cap * 0.75 + sig_weight + scope_weight, 1.0), 2)
-
-
-def _obs_path(root):
-    return os.path.join(root, OBS_REL)
-
-
-def _obs_load(root):
-    path = _obs_path(root)
-    if not os.path.exists(path):
-        return []
-    try:
-        with open(path, "r", encoding="utf-8") as f:
-            data = json.load(f)
-        return data if isinstance(data, list) else []
-    except (ValueError, OSError):
-        return []
-
-
-def _obs_append(root, item):
-    os.makedirs(os.path.join(root, ".specs"), exist_ok=True)
-    items = _obs_load(root)
-    items.append(item)
-    with open(_obs_path(root), "w", encoding="utf-8") as f:
-        json.dump(items, f, indent=2, ensure_ascii=False)
-        f.write("\n")
-
-
-def _remember_best_effort(root, content, tags, project_id="", session_id=""):
-    """Best-effort massa-ai memory write via REST (urllib, stdlib only).
-
-    massa-ai MCP is agent-side only; a CLI subprocess cannot call MCP. massa-ai exposes
-    REST at MASSA_AI_API_URL. Type is always `pattern` (lessons are procedural
-    knowledge); `procedural` is a tag, not a type. Returns True on success,
-    False (silent) when unavailable — the file store remains source of truth.
-    """
-    api_url = os.environ.get("MASSA_AI_API_URL")
-    if not api_url:
-        return False
-    path = os.environ.get("MASSA_AI_MEMORY_PATH", "/api/v1/memory")
-    url = api_url.rstrip("/") + path
-    body = json.dumps({
-        "content": content, "type": MASSA_AI_LESSON_TYPE, "importance": 0.6,
-        "projectId": project_id, "sessionId": session_id, "tags": list(tags),
-    }).encode("utf-8")
-    req = urllib.request.Request(url, data=body, method="POST",
-                                 headers={"Content-Type": "application/json"})
-    key = os.environ.get("MASSA_AI_API_KEY")
-    if key:
-        req.add_header("x-api-key", key)
-    try:
-        with urllib.request.urlopen(req, timeout=1.5) as resp:
-            return 200 <= resp.status < 300
-    except Exception:
-        return False
-
-
-def _lesson_tags(lesson):
-    """massa-ai persistence tag contract for a lesson's massa-ai memory."""
-    return [
-        "project:%s" % lesson.get("project", ""),
-        "session:%s" % lesson.get("session", ""),
-        "workflow:%s" % (lesson.get("workflow", "") or "unset"),
-        "entity:%s" % (lesson.get("entity", "") or "unset"),
-        "memory:procedural",
-    ]
-
-
-def _norm(text):
-    """Normalized dedup key: lowercase, strip punctuation, collapse whitespace.
-    Exact-after-normalization only - no semantic matching (stdlib-only limitation).
-    Phrase lessons tersely and canonically so recurrences actually merge."""
-    t = text.lower().strip()
-    t = re.sub(r"[^a-z0-9\s]", " ", t)
-    t = re.sub(r"\s+", " ", t).strip()
-    return t
-
-
-def _key(signal, text):
-    return signal + "::" + _norm(text)
-
-
-def _auto_prune(data):
-    """Drop candidates that never recurred within the window. Mutates data."""
-    threshold = data["promote_threshold"]
-    window = data["window_days"]
-    now = _dt.datetime.now(_dt.timezone.utc)
-    kept = []
-    dropped = []
-    for l in data["lessons"]:
-        if l["status"] == "candidate" and l["recurrence"] < threshold:
-            age_days = (now - _parse_date(l.get("last_seen", l.get("created", _now())))).days
-            if age_days > window:
-                dropped.append(l["id"])
-                continue
-        kept.append(l)
-    data["lessons"] = kept
-    return dropped
-
-
-def _find(data, signal, text):
-    k = _key(signal, text)
-    for l in data["lessons"]:
-        if l.get("key") == k:
-            return l
-    return None
-
-
-def _render(root, data):
-    lines = []
-    lines.append("# LESSONS - auto-maintained by skills/massa-ai/scripts/lessons.py")
-    lines.append("")
-    lines.append("> Machine-owned. Do NOT hand-edit. Changes are overwritten on the next `lessons.py` write.")
-    lines.append("> Canonical state lives in `.specs/lessons.json`. Edit lessons only via the script.")
-    lines.append(f"> promote_threshold={data['promote_threshold']} distinct features | window_days={data['window_days']} | quarantine_threshold={data['quarantine_threshold']}")
-    lines.append("")
-
-    by_status = {"confirmed": [], "candidate": [], "quarantined": []}
-    for l in data["lessons"]:
-        by_status.get(l["status"], by_status["candidate"]).append(l)
-
-    def block(title, items, note):
-        out = [f"## {title}", ""]
-        if note:
-            out.append(note)
-            out.append("")
-        if not items:
-            out.append("_none_")
-            out.append("")
-            return out
-        for l in sorted(items, key=lambda x: x["id"]):
-            scope = f" | scope: `{l['scope']}`" if l.get("scope") else ""
-            conf = l.get("confidence", _confidence(l, data))
-            out.append(f"### {l['id']} - {l['text']}")
-            out.append(
-                f"- signal: `{l['signal']}` | recurrence: {l['recurrence']} feature(s){scope} | harmful: {l.get('harmful', 0)} | confidence: {conf}"
-            )
-            feats = ", ".join(l.get("features", [])) or "-"
-            out.append(f"- features: {feats}")
-            ctx = []
-            for k in ("project", "session", "workflow", "entity"):
-                if l.get(k):
-                    ctx.append(f"{k}={l[k]}")
-            if ctx:
-                out.append(f"- context: {' '.join(ctx)}")
-            ev = l.get("evidence", [])
-            if ev:
-                out.append(f"- evidence: {ev[0]}" + (f" (+{len(ev) - 1} more)" if len(ev) > 1 else ""))
-            out.append(f"- last seen: {l.get('last_seen', '-')}")
-            out.append("")
-        return out
-
-    lines += block(
-        "Confirmed (load these at Specify/Design)",
-        by_status["confirmed"],
-        "Corroborated across multiple features. Safe to apply as guidance.",
-    )
-    lines += block(
-        "Candidates (under observation - do NOT load as guidance yet)",
-        by_status["candidate"],
-        "Seen once or not yet corroborated. Tracked, not trusted.",
-    )
-    lines += block(
-        "Quarantined (failed when applied - ignore)",
-        by_status["quarantined"],
-        "A confirmed lesson that recurred alongside failure. Kept for the maintainer to review.",
-    )
-
-    with open(_render_path(root), "w", encoding="utf-8") as f:
-        f.write("\n".join(lines).rstrip() + "\n")
-
-
-# ----------------------------- commands -----------------------------
-
-def cmd_init(root, args):
-    data = _load(root)
-    _save(root, data)
-    print(f"Initialized lessons store at {_store_path(root)} and {_render_path(root)}")
-    return 0
-
-
-def cmd_add(root, args):
-    signal = args.signal
-    source = (args.source or "").strip()
-    text = (args.text or "").strip()
-    feature = (args.feature or "").strip()
-
-    # Grounding is enforced here, deterministically - not left to the prompt.
-    if signal not in SIGNALS:
-        print(f"ERROR: --signal must be one of {sorted(SIGNALS)}", file=sys.stderr)
-        return 2
-    if not feature:
-        print("ERROR: --feature is required (the feature the signal came from).", file=sys.stderr)
-        return 2
-    if not source:
-        print("ERROR: --source is required (file:line / AC id / mutant id / SPEC_DEVIATION ref).", file=sys.stderr)
-        print("       A lesson with no grounding in validation.md is an opinion, not a lesson. Refused.", file=sys.stderr)
-        return 2
-    if len(text) < 12:
-        print("ERROR: --text too short. State the actionable lesson in one terse sentence.", file=sys.stderr)
-        return 2
-
-    data = _load(root)
-    _auto_prune(data)
-    existing = _find(data, signal, text)
-    now = _now()
-    project = (getattr(args, "project", "") or "").strip()
-    session = (getattr(args, "session", "") or "").strip()
-    workflow = (getattr(args, "workflow", "") or "").strip()
-    entity = (getattr(args, "entity", "") or "").strip()
-
-    def _ctx(lesson):
-        if project:
-            lesson["project"] = project
-        if session:
-            lesson["session"] = session
-        if workflow:
-            lesson["workflow"] = workflow
-        if entity:
-            lesson["entity"] = entity
-
-    if existing:
-        if feature not in existing["features"]:
-            existing["features"].append(feature)
-        existing["recurrence"] = len(existing["features"])
-        existing["last_seen"] = now
-        _ctx(existing)
-        existing["confidence"] = _confidence(existing, data)
-        ev = source if not args.scope else f"{source} ({args.scope})"
-        if ev not in existing["evidence"]:
-            existing["evidence"].append(ev)
-        promoted = False
-        if existing["status"] == "candidate" and existing["recurrence"] >= data["promote_threshold"]:
-            existing["status"] = "confirmed"
-            promoted = True
-        _save(root, data)
-        _remember_best_effort(root, "%s [%s] %s" % (existing["id"], signal, text),
-                                    _lesson_tags(existing), project, session)
-        msg = f"UPDATED {existing['id']} (recurrence={existing['recurrence']}, status={existing['status']}, confidence={existing['confidence']})"
-        if promoted:
-            msg += " - PROMOTED to confirmed"
-        print(msg)
-    else:
-        lid = f"L-{data['next_id']:03d}"
-        data["next_id"] += 1
-        lesson = {
-            "id": lid,
-            "key": _key(signal, text),
-            "text": text,
-            "signal": signal,
-            "scope": (args.scope or "").strip(),
-            "status": "candidate",
-            "features": [feature],
-            "recurrence": 1,
-            "harmful": 0,
-            "evidence": [source if not args.scope else f"{source} ({args.scope})"],
-            "created": now,
-            "last_seen": now,
-        }
-        _ctx(lesson)
-        lesson["confidence"] = _confidence(lesson, data)
-        data["lessons"].append(lesson)
-        _save(root, data)
-        _remember_best_effort(root, "%s [%s] %s" % (lid, signal, text),
-                                    _lesson_tags(lesson), project, session)
-        print(f"ADDED {lid} (status=candidate, recurrence=1, confidence={lesson['confidence']})")
-    return 0
-
-
-def cmd_penalize(root, args):
-    data = _load(root)
-    target = None
-    for l in data["lessons"]:
-        if l["id"].lower() == args.id.lower():
-            target = l
-            break
-    if not target:
-        print(f"ERROR: no lesson with id {args.id}", file=sys.stderr)
-        return 2
-    target["harmful"] = target.get("harmful", 0) + 1
-    target["last_seen"] = _now()
-    if target["harmful"] >= data["quarantine_threshold"]:
-        target["status"] = "quarantined"
-    _save(root, data)
-    print(f"PENALIZED {target['id']} (harmful={target['harmful']}, status={target['status']})")
-    return 0
-
-
-def cmd_list(root, args):
-    data = _load(root)
-    if _auto_prune(data):
-        _save(root, data)
-    want = args.status
-    q = (args.query or "").lower().strip()
-    scope = (args.scope or "").lower().strip()
-    project = (getattr(args, "project", "") or "").lower().strip()
-    rows = []
-    for l in data["lessons"]:
-        if want != "all" and l["status"] != want:
-            continue
-        if q and q not in l["text"].lower():
-            continue
-        if scope and scope not in (l.get("scope", "").lower()):
-            continue
-        if project and project not in (l.get("project", "").lower()):
-            continue
-        rows.append(l)
-    if not rows:
-        flt = " ".join(f for f in (q, scope, project) if f)
-        print(f"(no {want} lessons" + (f" matching '{flt}'" if flt else "") + ")")
-        return 0
-    for l in sorted(rows, key=lambda x: x["id"]):
-        sc = f" [scope:{l['scope']}]" if l.get("scope") else ""
-        conf = l.get("confidence", _confidence(l, data))
-        print(f"{l['id']} ({l['status']}, x{l['recurrence']}, conf={conf}){sc}: {l['text']}")
-    return 0
-
-
-def cmd_observe(root, args):
-    """Ingest a JSON observation into the gitignored observations buffer.
-
-    Grounding is NOT enforced here; it is enforced when `add` consumes the
-    buffer. Observation fields: signal, text, source, feature, scope, project,
-    session, workflow, entity.
-    """
-    raw = args.json if args.json else sys.stdin.read()
-    try:
-        item = json.loads(raw)
-    except (ValueError, TypeError) as exc:
-        print(f"ERROR: observation is not valid JSON: {exc}", file=sys.stderr)
-        return 2
-    if not isinstance(item, dict):
-        print("ERROR: observation must be a JSON object", file=sys.stderr)
-        return 2
-    item.setdefault("observed_at", _now())
-    _obs_append(root, item)
-    print(f"OBSERVED buffer=1 (total={len(_obs_load(root))})")
-    return 0
-
-
-def cmd_export(root, args):
-    """Export the lessons store as JSON (stdout or --out). Round-trips with import."""
-    data = _load(root)
-    text = json.dumps(data, indent=2, ensure_ascii=False) + "\n"
-    if args.out:
-        with open(args.out, "w", encoding="utf-8") as f:
-            f.write(text)
-        print(f"EXPORTED {len(data['lessons'])} lessons -> {args.out}")
-    else:
-        sys.stdout.write(text)
-    return 0
-
-
-def cmd_import(root, args):
-    """Import lessons from JSON (stdin or --in), merging by dedup key.
-
-    Re-emits massa-ai memory best-effort (type `pattern`, tag `memory:procedural`)
-    for each imported lesson so the file store and massa-ai memory stay consistent.
-    """
-    raw = sys.stdin.read() if args.in_ is None else open(args.in_, "r", encoding="utf-8").read()
-    try:
-        incoming = json.loads(raw)
-    except (ValueError, TypeError) as exc:
-        print(f"ERROR: import payload is not valid JSON: {exc}", file=sys.stderr)
-        return 2
-    if not isinstance(incoming, dict) or not isinstance(incoming.get("lessons"), list):
-        print("ERROR: import payload must be a lessons store object with `lessons`", file=sys.stderr)
-        return 2
-    data = _load(root)
-    _auto_prune(data)
-    now = _now()
-    added = merged = 0
-    for l in incoming["lessons"]:
-        key = l.get("key") or _key(l.get("signal", ""), l.get("text", ""))
-        existing = next((x for x in data["lessons"] if x.get("key") == key), None)
-        if existing:
-            for f in l.get("features", []):
-                if f not in existing["features"]:
-                    existing["features"].append(f)
-            existing["recurrence"] = len(existing["features"])
-            existing["last_seen"] = now
-            existing["confidence"] = _confidence(existing, data)
-            merged += 1
-        else:
-            lid = f"L-{data['next_id']:03d}"
-            data["next_id"] += 1
-            l.setdefault("id", lid)
-            l["id"] = lid
-            l["key"] = key
-            l.setdefault("status", "candidate")
-            l.setdefault("recurrence", len(l.get("features", [])) or 1)
-            l.setdefault("harmful", 0)
-            l.setdefault("created", now)
-            l["last_seen"] = now
-            l["confidence"] = _confidence(l, data)
-            data["lessons"].append(l)
-            added += 1
-        target = existing or l
-        _remember_best_effort(root, "%s [%s] %s" % (target.get("id"), target.get("signal", ""), target.get("text", "")),
-                                    _lesson_tags(target), target.get("project", ""), target.get("session", ""))
-    _save(root, data)
-    print(f"IMPORTED added={added} merged={merged} massa-ai=best-effort")
-    return 0
-
-
-def cmd_prune(root, args):
-    data = _load(root)
-    dropped = _auto_prune(data)
-    _save(root, data)
-    print(f"Pruned {len(dropped)} stale candidate(s): {', '.join(dropped) if dropped else '-'}")
-    return 0
-
-
-def cmd_status(root, args):
-    data = _load(root)
-    counts = {"confirmed": 0, "candidate": 0, "quarantined": 0}
-    for l in data["lessons"]:
-        counts[l["status"]] = counts.get(l["status"], 0) + 1
-    total = len(data["lessons"])
-    print(f"lessons: {total} total | confirmed={counts['confirmed']} candidate={counts['candidate']} quarantined={counts['quarantined']}")
-    return 0
-
-
-def main(argv=None):
-    p = argparse.ArgumentParser(prog="lessons.py", description="Deterministic lessons bookkeeping for massa-ai spec-driven.")
-    p.add_argument("--root", default=".", help="Project root containing .specs/ (default: current dir)")
-    sub = p.add_subparsers(dest="cmd", required=True)
-
-    sp = sub.add_parser("init", help="Create empty store + rendered file")
-    sp.set_defaults(fn=cmd_init)
-
-    sp = sub.add_parser("add", help="Record a grounded lesson")
-    sp.add_argument("--feature", required=True)
-    sp.add_argument("--signal", required=True, choices=sorted(SIGNALS))
-    sp.add_argument("--source", required=True, help="file:line / AC id / mutant id / SPEC_DEVIATION ref")
-    sp.add_argument("--text", required=True, help="One terse, actionable sentence")
-    sp.add_argument("--scope", default="", help="Optional: path/layer/tag for retrieval filtering")
-    sp.add_argument("--project", default="", help="massa-ai projectId context")
-    sp.add_argument("--session", default="", help="massa-ai workflowSessionId context")
-    sp.add_argument("--workflow", default="", help="active massa-ai workflow type")
-    sp.add_argument("--entity", default="", help="active massa-ai entity")
-    sp.set_defaults(fn=cmd_add)
-
-    sp = sub.add_parser("penalize", help="Mark a confirmed lesson as failed-when-applied")
-    sp.add_argument("--id", required=True)
-    sp.set_defaults(fn=cmd_penalize)
-
-    sp = sub.add_parser("list", help="Print lessons for loading")
-    sp.add_argument("--status", default="confirmed", choices=["confirmed", "candidate", "quarantined", "all"])
-    sp.add_argument("--query", default="", help="Substring filter on lesson text")
-    sp.add_argument("--scope", default="", help="Substring filter on scope")
-    sp.add_argument("--project", default="", help="Substring filter on project")
-    sp.set_defaults(fn=cmd_list)
-
-    sp = sub.add_parser("observe", help="Ingest a JSON observation into the buffer")
-    sp.add_argument("--json", default="", help="Observation JSON (else read stdin)")
-    sp.set_defaults(fn=cmd_observe)
-
-    sp = sub.add_parser("export", help="Export lessons store as JSON")
-    sp.add_argument("--out", default="", help="Write to file (else stdout)")
-    sp.set_defaults(fn=cmd_export)
-
-    sp = sub.add_parser("import", help="Import lessons from JSON (merge by dedup key)")
-    sp.add_argument("--in", dest="in_", default=None, help="Read from file (else stdin)")
-    sp.set_defaults(fn=cmd_import)
-
-    sp = sub.add_parser("prune", help="Drop stale uncorroborated candidates")
-    sp.set_defaults(fn=cmd_prune)
-
-    sp = sub.add_parser("status", help="Print counts")
-    sp.set_defaults(fn=cmd_status)
-
-    args = p.parse_args(argv)
-    root = os.path.abspath(args.root)
-    return args.fn(root, args)
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())