@massa-ai/cursor-plugin 1.20.0 → 1.21.0

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

@@ -58,7 +58,7 @@ This step ALWAYS runs — there is no precondition. Decide which of two paths to
 
 Before sampling tests or inferring anything, scan the project for documented quality and testing standards. Stack-agnostic sources to check (illustrative, not exhaustive):
 
-- Agent/AI instructions: `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/**`, `.github/copilot-instructions.md`
+- Agent/AI convention files, if the repo has any: `AGENTS.md` (the vendor-neutral standard) and any tool-specific rules file or rules directory the project happens to use
 - Contributor guides: `CONTRIBUTING.md`, `docs/` (testing, quality, or standards subdocs), README testing section
 - Tool configuration: coverage thresholds in the test runner config (e.g., `jest.config.*`, `vitest.config.*`, `pytest.ini`, `.nycrc`, `Makefile` coverage targets, CI coverage gates)
 
@@ -74,7 +74,7 @@ Before sampling tests or inferring anything, scan the project for documented qua
 **How to infer (path 1 — existing tests):**
 
 1. **Sample test files.** Locate 5–10 existing test files. Map each file's location relative to its source file to identify which code layers are exercised and at what level (unit, integration, e2e). Use these samples for style, location patterns, framework, and test type — and as a **floor** (never produce tests less thorough than existing ones for the same layer). Existing tests are NOT a ceiling on thoroughness; the thoroughness target comes from the spec ACs, listed edge cases, and guidelines (or strong default). The Coverage Expectation column captures the target per layer.
-2. **Discover commands from the repo.** Do NOT invent commands and do NOT assume an ecosystem. Read the project's own build/task manifests, test config, and CI workflows to extract the actual commands — for example: `package.json` / `project.json` (JS/TS), `Makefile`, `pyproject.toml` / `tox.ini` / `pytest` (Python), `Cargo.toml` (Rust), `go test` invocations (Go), `pom.xml` / `build.gradle` (Java/Kotlin), `Gemfile` / `Rakefile` (Ruby), `composer.json` (PHP), `.github/workflows` / `.gitlab-ci.yml`. The list is illustrative; detect what this repo actually uses.
+2. **Discover commands from the repo.** Do NOT invent commands and do NOT assume an ecosystem. Read the project's own build/task manifests, test config, and CI workflows to extract the actual commands — for example: `package.json` / `project.json` (JS/TS), `Makefile`, `pyproject.toml` / `tox.ini` / `pytest` (Python), `Cargo.toml` (Rust), `go test` invocations (Go), `pom.xml` / `build.gradle` (Java/Kotlin), `Gemfile` / `Rakefile` (Ruby), `composer.json` (PHP), `.github/workflows` / `.gitlab-ci.yml`. The list is illustrative; detect what this repo actually uses. Capture the **linter/formatter** command too (e.g. the configured `lint`/`format`/`typecheck` script, or a `.pre-commit-config`, `.golangci.yml`, `ruff`/`eslint`/`biome` config) — the Build gate runs it alongside the tests.
 
 **Output contract — render these two sections verbatim into `tasks.md`** (the exact headings downstream phases reference):
 
@@ -157,6 +157,8 @@ 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).
+
 **Check 1: Task Granularity** — verify each task is atomic (see Granularity Check section).
 
 **Check 2: Diagram-Definition Cross-Check** — verify the execution diagram matches every task's `Depends on` field (see Diagram-Definition Cross-Check section). Build the cross-check table and include it in the output.
@@ -350,12 +352,12 @@ Execution is strictly sequential — there is no intra-phase parallelism. A sing
 
 **How phase-based execution works:**
 
-At Execute, the agent counts total tasks and packs phases into **task-budgeted batches** (~7 tasks per worker, whole phases — the benchmarked sweet spot is ~20 tasks → ~3 workers). A **phase** is the semantic/dependency unit; a **batch** is one or more *consecutive whole phases* assigned to one worker. The cut only ever lands on a phase boundary — a phase is never split across workers. When packing yields more than one batch (> ~8 tasks), the agent offers to dispatch batch sub-agents. Batches run sequentially: each worker executes ALL its tasks in order, then reports a compact summary before the next batch starts. This right-sizes the worker count by workload instead of by phase count (one-per-phase is too fragmented; expensive and slow). See `references/spec-driven/sub-agents.md` for the full model — packing algorithm, offer-then-confirm, worker payload, compact summary contract, failure handling, and context sizing guidance.
+At Execute, the agent counts total tasks and packs phases into **task-budgeted batches** (~7 tasks per worker, whole phases — the benchmarked sweet spot is ~20 tasks → ~3 workers). A **phase** is the semantic/dependency unit; a **batch** is one or more *consecutive whole phases* assigned to one worker. The cut only ever lands on a phase boundary — a phase is never split across workers. **The sub-agent offer fires whenever the feature has more than 3 tasks** — a 4–8-task feature still packs into a single batch and is offered as one batch worker; only a feature with 3 or fewer tasks executes inline with no offer. Batches run sequentially: each worker executes ALL its tasks in order, then reports a compact summary before the next batch starts. This right-sizes the worker count by workload instead of by phase count (one-per-phase is too fragmented; expensive and slow). See `references/spec-driven/sub-agents.md` for the full model — packing algorithm, offer-then-confirm, worker payload, compact summary contract, failure handling, and context sizing guidance.
 
-When the whole feature fits a single batch (≤ ~8 tasks), execution happens inline in the main window with no sub-agents spawned.
+When the whole feature has 3 or fewer tasks, execution happens inline in the main window with no sub-agents spawned and no offer made.
 
 **The orchestrating agent's role during Execute:**
-1. Count total tasks and pack phases into ~7-task batches — offer batch sub-agents if that yields more than one batch and the user accepts
+1. Count total tasks — if more than 3, pack phases into ~7-task batches and offer batch sub-agents (even a single resulting batch is offered); wait for the user's choice
 2. Dispatch the next batch (to a worker, or execute inline)
 3. Receive the compact batch summary
 4. Update tasks.md with results
@@ -514,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, 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.py` 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

@@ -27,7 +27,7 @@ Use this reference for the mandatory final Execute validation gate. This is not
 
 Prefer a fresh read-only verifier agent or tool. The author must not verify their own work when independent verification tooling is available. When subagents are unavailable, run the standalone fresh-eyes fallback: re-read `spec.md`, changed files, tests, and diff from scratch before making a verdict.
 
-The verifier is read-only against the real worktree. Discrimination sensor mutations run only in scratch state such as a temporary worktree, stash-protected copy, or temp file copy, and must be reverted or discarded before verdict.
+The verifier is read-only against the real worktree. Discrimination sensor mutations run only in an isolated scratch state — a temporary git worktree (preferred) or temp file copies (fallback), never `git stash` — and must be reverted or discarded before verdict.
 
 ## Inputs
 
@@ -100,18 +100,20 @@ The sensor provides the empirical guarantee that the tests can actually detect r
 
 **How it works:**
 
-1. **Prepare a scratch state.** Use one of (choose the safest available for the environment):
-   - `git stash` the current state, apply a mutation, run tests, then `git stash pop`; OR
-   - A temporary worktree (`git worktree add`); OR
-   - A temp copy of the affected file(s).
-2. **Inject a behavior-level fault** into the new code introduced by this feature. Choose a mutation proportional to the code's risk:
+1. **Prepare an isolated scratch.** Never mutate the real worktree. Choose one:
+   - Preferred: a temporary git worktree (`git worktree add <scratch-path> HEAD`), mutate and run tests there, then `git worktree remove --force <scratch-path>`.
+   - Fallback (no git / worktree unavailable): copy only the affected file(s) to a temp directory, mutate the copies, point the test runner at those copies (or restore originals from the copies' backups), then delete the temp directory.
+   - **Forbidden:** `git stash` / `git stash pop`. A stash records state *before* the mutation; popping it does not reverse a mutation applied afterward, and on a clean tree `git stash` creates no entry at all — so the fault is left in the real worktree.
+2. **Capture a baseline.** Record `git status --porcelain` (or equivalent) of the real worktree *before* any sensor work. It must be unchanged after cleanup.
+3. **Inject a behavior-level fault** into the scratch copy of the new code introduced by this feature. Choose a mutation proportional to the code's risk:
    - Flip a boolean condition (`if (x)` → `if (!x)`, `>` → `>=`)
    - Change a return value (return a wrong status code, wrong field, zero instead of a computed value)
    - Off-by-one (shift a loop bound, change a slice index)
    - Remove a required side effect (delete a method call that the spec requires)
-3. **Run the tests** that cover the mutated code. Use the Quick or Full gate command from tasks.md.
-4. **Confirm the mutant is killed** (tests FAIL). Then discard the mutation (restore the scratch state).
-5. **If a mutant survives** (tests still pass after the fault), the tests are not discriminating for that behavior — add a fix task to strengthen the assertion.
+4. **Run the tests** that cover the mutated code (against the scratch). Use the Quick or Full gate command from tasks.md.
+5. **Confirm the mutant is killed** (tests FAIL). Discard the scratch (remove worktree or delete temp copies).
+6. **Verify isolation.** Re-run `git status --porcelain` on the real worktree and confirm it matches the baseline from step 2. If it differs, STOP — restore the real tree before continuing, and treat the sensor run as invalid.
+7. **If a mutant survives** (tests still pass after the fault), the tests are not discriminating for that behavior — add a fix task to strengthen the assertion.
 
 **Tiering (proportional, not optional):**
 
@@ -202,6 +204,8 @@ 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).
+
 ### 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:
@@ -364,6 +368,7 @@ Update `.specs/features/<slug>/spec.md` requirement statuses and reflect verifie
 ## Summary
 
 **Overall**: ✅ Ready | ⚠️ Issues | ❌ Not Ready
+**Result**: PASS | FAIL
 
 **Spec-anchored check**: [N/N ACs matched spec outcome | M spec-precision gaps]
 **Sensor**: [N/N mutations killed]
@@ -382,7 +387,7 @@ Update `.specs/features/<slug>/spec.md` requirement statuses and reflect verifie
 
 - **Validation is never prompted** — it always runs after the last task; do not ask the user whether to run it
 - **Spec-anchored, not just covered** — "there is an assertion" is not enough; the assertion must target the spec-defined outcome
-- **Sensor in scratch only** — never mutate the real tree; stash/worktree/temp copy, run, discard
+- **Sensor in scratch only** — never mutate the real tree; use a temp worktree or file copies (never `git stash`), run, discard, then confirm porcelain matches the pre-sensor baseline
 - **Surviving mutants are fix tasks** — do not mark the feature done if the sensor found weak tests
 - **P1 first** — MVP must work before P2/P3
 - **WHEN/THEN = Test** — Each criterion is a test case

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

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""
+check_commit.py - 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. Pure
+standard library, 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.py .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:
+  python3 skills/massa-ai/scripts/check_commit.py [msgfile]
+  python3 skills/massa-ai/scripts/check_commit.py --message "feat(auth): add email validation"
+  python3 skills/massa-ai/scripts/check_commit.py --message "[SA-142] feat(auth): reject expired tokens"
+  echo "fix(cart): prevent negative quantity" | python3 skills/massa-ai/scripts/check_commit.py
+
+Exit codes: 0 pass, 1 violation, 2 usage error.
+"""
+
+import argparse
+import re
+import sys
+
+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+.
+PREFIX_RE = re.compile(r"^\[(?P<key>[A-Z][A-Z0-9]{1,9}-\d+)\]\s+(?P<rest>.+)$")
+HEADER_RE = re.compile(r"^(?P<type>\w+)(?:\((?P<scope>[^)]+)\))?(?P<bang>!)?: (?P<desc>.+)$")
+
+
+def read_message(args):
+    if args.message is not None:
+        return args.message
+    if args.msgfile:
+        with open(args.msgfile, "r", encoding="utf-8") as f:
+            return f.read()
+    if not sys.stdin.isatty():
+        return sys.stdin.read()
+    return ""
+
+
+def check(message):
+    errors, warnings = [], []
+    # Ignore comment lines (git puts '#' comments in the message file).
+    lines = [ln for ln in message.splitlines() if not ln.lstrip().startswith("#")]
+    # Trim leading blank lines.
+    while lines and not lines[0].strip():
+        lines.pop(0)
+    if not lines:
+        return (["empty commit message"], warnings)
+
+    header = lines[0].rstrip()
+    if len(header) > 72:
+        warnings.append(f"header is {len(header)} chars (>72): {header[:60]}...")
+
+    # Strip an optional massa-ai Jira-style `[KEY] ` prefix before matching the
+    # Conventional Commits header shape.
+    prefixed = PREFIX_RE.match(header)
+    header_body = prefixed.group("rest") if prefixed else header
+
+    m = HEADER_RE.match(header_body)
+    if not m:
+        errors.append(f"header does not match 'type(scope): description': {header!r}")
+        return (errors, warnings)
+
+    ctype = m.group("type")
+    desc = m.group("desc")
+    bang = m.group("bang")
+
+    if ctype not in TYPES:
+        errors.append(f"type '{ctype}' is not one of: {', '.join(TYPES)}")
+    if not desc.strip():
+        errors.append("description is empty")
+    else:
+        if desc[:1].isupper():
+            errors.append(f"description should start lowercase: '{desc[:30]}'")
+        if desc.rstrip().endswith("."):
+            errors.append("description should not end with a period")
+
+    body = "\n".join(lines[1:])
+    breaking_footer = bool(re.search(r"^BREAKING CHANGE:", body, re.MULTILINE))
+    if bang and not breaking_footer:
+        errors.append("'!' breaking marker present but no 'BREAKING CHANGE:' footer")
+
+    return (errors, warnings)
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="check_commit.py", description="Validate a Conventional Commits message.")
+    p.add_argument("msgfile", nargs="?", default=None, help="path to a commit message file (as git passes to commit-msg)")
+    p.add_argument("--message", default=None, help="the commit message as a string")
+    args = p.parse_args(argv)
+
+    message = read_message(args)
+    if not message.strip():
+        print("check_commit: no message provided (pass a file, --message, or pipe via stdin).", file=sys.stderr)
+        return 2
+
+    errors, warnings = check(message)
+    for w in warnings:
+        print(f"  WARN  {w}")
+    for e in errors:
+        print(f"  ERROR {e}")
+    if errors:
+        print("\ncheck_commit: FAIL - see https://www.conventionalcommits.org/en/v1.0.0/")
+        return 1
+    print("check_commit: OK")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+check_specs_delivered.py - deterministic gate: .specs/ artifacts are
+committed on the branch before a PR is opened (GATE-02).
+
+New script, not a TLC port - massa-ai's `implementation-delivery.md` chain has
+no gate requiring `.specs/` (spec/context/design/tasks/validation, project
+state, handoff, features registry) to be committed before `gh pr create`. This
+turns that gap into two conjunctive, deterministic checks:
+
+  1. `git status --porcelain -- .specs/` is empty - nothing under .specs/ is
+     modified-but-uncommitted or untracked.
+  2. The feature's `spec.md` (always required) plus any of
+     `{context,design,tasks,validation}.md` that exist on disk, plus
+     `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and
+     `.specs/project/FEATURES.json`, are tracked on HEAD
+     (`git ls-tree -r --name-only HEAD`).
+
+Check 2 exists because check 1 alone is not sufficient: a feature whose
+`.specs/` artifacts were simply never written is porcelain-clean (nothing to
+be dirty about) while still failing the actual requirement. Absence must fail,
+not pass.
+
+Pure `git` + standard library. No dependencies. Run from the project root (the
+dir that contains .specs/), or pass --root.
+
+Usage:
+  python3 skills/massa-ai/scripts/check_specs_delivered.py <feature> [--root DIR]
+
+Exit codes: 0 all required paths clean + tracked, 1 a required path is dirty,
+            untracked, or not tracked on HEAD (paths named), 2 usage/git error.
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+
+# Always required for the named feature.
+FEATURE_REQUIRED = ["spec.md"]
+# Required only when present on disk (not every feature reaches every phase).
+FEATURE_OPTIONAL = ["context.md", "design.md", "tasks.md", "validation.md"]
+
+STATE_FILES = [
+    os.path.join(".specs", "project", "STATE.md"),
+    os.path.join(".specs", "HANDOFF.md"),
+    os.path.join(".specs", "project", "FEATURES.json"),
+]
+
+
+def _run_git(args, root):
+    try:
+        proc = subprocess.run(
+            ["git"] + args, cwd=root, capture_output=True, text=True, check=False
+        )
+    except FileNotFoundError:
+        print("check_specs_delivered: git not found on PATH", file=sys.stderr)
+        raise SystemExit(2)
+    if proc.returncode != 0:
+        print(
+            f"check_specs_delivered: git {' '.join(args)} failed: {proc.stderr.strip()}",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+    return proc.stdout
+
+
+def _porcelain_dirty_paths(root):
+    """Lines from `git status --porcelain -- .specs/` (empty = clean)."""
+    out = _run_git(["status", "--porcelain", "--", ".specs/"], root)
+    return [ln for ln in out.splitlines() if ln.strip()]
+
+
+def _tracked_on_head(root):
+    """Set of every path tracked on HEAD, repo-root-relative, '/'-separated."""
+    out = _run_git(["ls-tree", "-r", "--name-only", "HEAD"], root)
+    return set(out.splitlines())
+
+
+def _resolve_feature_dir(root, feature):
+    if os.path.isabs(feature) or os.sep in feature:
+        return os.path.normpath(feature)
+    return os.path.join(root, ".specs", "features", feature)
+
+
+def required_paths(root, feature):
+    """Repo-root-relative, '/'-separated paths this feature must have tracked."""
+    fdir = _resolve_feature_dir(root, feature)
+    fdir_rel = os.path.relpath(fdir, root)
+    paths = [os.path.join(fdir_rel, name) for name in FEATURE_REQUIRED]
+    if os.path.isdir(fdir):
+        for name in FEATURE_OPTIONAL:
+            if os.path.isfile(os.path.join(fdir, name)):
+                paths.append(os.path.join(fdir_rel, name))
+    paths.extend(STATE_FILES)
+    return [p.replace(os.sep, "/") for p in paths]
+
+
+def check(root, feature):
+    """Return (errors, checked_paths). errors empty = pass."""
+    errors = []
+
+    for ln in _porcelain_dirty_paths(root):
+        errors.append(f"uncommitted/untracked under .specs/: {ln.strip()}")
+
+    paths = required_paths(root, feature)
+    tracked = _tracked_on_head(root)
+    for p in paths:
+        if p not in tracked:
+            errors.append(f"not tracked on HEAD: {p}")
+
+    return errors, paths
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(
+        prog="check_specs_delivered.py",
+        description="Gate: .specs/ artifacts committed on the branch before PR (GATE-02).",
+    )
+    p.add_argument("feature", help="Feature slug under <root>/.specs/features/, or a direct path")
+    p.add_argument("--root", default=".", help="Project root containing .specs/ (default: current dir)")
+    args = p.parse_args(argv)
+    root = os.path.abspath(args.root)
+
+    errors, checked = check(root, args.feature)
+
+    for e in errors:
+        print(f"  ERROR {e}")
+    print(f"\ncheck_specs_delivered: checked {len(checked)} path(s):")
+    for c in checked:
+        print(f"  - {c}")
+    print(f"check_specs_delivered: {len(errors)} error(s)")
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -24,6 +24,7 @@ Commands:
   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).
+  selftest   Run stdlib regressions (normalization).
 
 Exit codes: 0 ok, 2 usage/validation error (e.g. missing grounding).
 """
@@ -34,6 +35,7 @@ import json
 import os
 import re
 import sys
+import unicodedata
 import urllib.request
 
 STORE_REL = os.path.join(".specs", "lessons.json")
@@ -178,15 +180,50 @@ def _lesson_tags(lesson):
 
 
 def _norm(text):
-    """Normalized dedup key: lowercase, strip punctuation, collapse whitespace.
+    """Normalized dedup key for lesson text.
+
+    - casefold + NFD, strip combining marks (so Portuguese diacritics match ASCII peers)
+    - keep characters where str.isalnum() is true (any script) and whitespace
+    - drop other 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)
+    Phrase lessons tersely and canonically so recurrences actually merge.
+    """
+    t = unicodedata.normalize("NFD", text.casefold())
+    t = "".join(c for c in t if unicodedata.category(c) != "Mn")
+    t = "".join(c if (c.isalnum() or c.isspace()) else " " for c in t)
     t = re.sub(r"\s+", " ", t).strip()
     return t
 
 
+def _selftest_norm():
+    """Regressions for #158: Portuguese diacritics + distinct non-Latin text."""
+    failures = []
+
+    def check(cond, msg):
+        if not cond:
+            failures.append(msg)
+
+    a = _norm("Não use datas locais")
+    b = _norm("Nao use datas locais")
+    check(a == b == "nao use datas locais", f"PT diacritics: {a!r} vs {b!r}")
+
+    jp1 = _norm("日本語の文です")
+    jp2 = _norm("別の日本語文")
+    check(jp1 != "", f"JP1 empty: {jp1!r}")
+    check(jp2 != "", f"JP2 empty: {jp2!r}")
+    check(jp1 != jp2, f"JP sentences collapsed: {jp1!r} == {jp2!r}")
+
+    check(_norm("café") == _norm("cafe") == "cafe", f"cafe: {_norm('café')!r}")
+
+    if failures:
+        for f in failures:
+            print(f"FAIL: {f}", file=sys.stderr)
+        return 1
+    print("selftest_norm: ok")
+    return 0
+
+
 def _key(signal, text):
     return signal + "::" + _norm(text)
 
@@ -581,6 +618,9 @@ def main(argv=None):
     sp = sub.add_parser("status", help="Print counts")
     sp.set_defaults(fn=cmd_status)
 
+    sp = sub.add_parser("selftest", help="Run stdlib regressions (normalization)")
+    sp.set_defaults(fn=lambda root, args: _selftest_norm())
+
     args = p.parse_args(argv)
     root = os.path.abspath(args.root)
     return args.fn(root, args)