@massa-ai/cursor-plugin 1.55.0 → 1.57.0

package/.cursor-plugin/plugin.json

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

package/install.sh

@@ -397,7 +397,7 @@ install_bundled_skills() {
   # authoritative constant (D6/IPT-05) — not derived by scanning the bundle's
   # skills/ directory, which would install 49 on cursor (every workflow skill
   # ships as its own directory here).
-  for name in massa-ai persona-router profile; do
+  for name in massa-ai persona-router profile bootstrap; do
     src="$SCRIPT_DIR/skills/$name"
     [[ -d "$src" ]] || continue
     dest="$HARNESS_SKILLS_DIR/$name"
@@ -426,7 +426,7 @@ if (typeof data.platforms !== "object" || data.platforms === null || Array.isArr
 }
 data.version = 2;
 const prev = data.platforms[host];
-data.platforms[host] = { root, skillsOwner: "plugin", skills: ["massa-ai", "persona-router", "profile"] };
+data.platforms[host] = { root, skillsOwner: "plugin", skills: ["massa-ai", "persona-router", "profile", "bootstrap"] };
 // The whole-record replace must not drop fields a previous successful install
 // wrote (R2) — re-attach them. installRoute (T9) is installer-owned but
 // written by a LATER step of this same install (record_plugin_version), so it
@@ -472,7 +472,7 @@ NODE
   )"
   [[ "$raw_owner" == "plugin" ]] && {
     local name
-    for name in massa-ai persona-router profile; do
+    for name in massa-ai persona-router profile bootstrap; do
       rm -rf "$HARNESS_SKILLS_DIR/$name"
     done
     rmdir "$HARNESS_SKILLS_DIR" 2>/dev/null || true
@@ -680,15 +680,17 @@ vecho "  + .cursor-plugin/plugin.json"
 
 # Copy the host-command skills (each in a subdirectory: skills/<name>/SKILL.md),
 # quick + generated workflow commands alike. massa-ai/, persona-router/,
-# agents/, and profile/ are the PDO-06 harness bundle, not a Cursor command
-# skill — they are installed separately, into the shared harness skills
+# agents/, profile/ and bootstrap/ are the PDO-06 harness bundle, not a Cursor
+# command skill — they are installed separately, into the shared harness skills
 # directory (see "Skills bundling" below), not into this plugin-cache
 # skills/ tree. `profile` was missing from this exclusion pre-fix, which
-# leaked it into the command-skill cache mislabeled as `/profile`.
+# leaked it into the command-skill cache mislabeled as `/profile`; `bootstrap`
+# (T21) is the same class, and is excluded here in the same commit that
+# teaches the generator to emit it, so it never has a release where it leaks.
 for src in "$SCRIPT_DIR/skills/"*/SKILL.md; do
   name="$(basename "$(dirname "$src")")"
   case "$name" in
-    massa-ai|persona-router|agents|profile) continue ;;
+    massa-ai|persona-router|agents|profile|bootstrap) continue ;;
   esac
   mkdir -p "$PLUGIN_DIR/skills/$name"
   cp "$src" "$PLUGIN_DIR/skills/$name/SKILL.md"

package/package.json

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

package/skills/agents/architecture-specialist/SKILL.md

@@ -3,7 +3,7 @@ name: architecture-specialist
 description: Read-only architecture guidance agent. Evaluate architecture, suggest boundaries, recommend abstractions, evaluate trade-offs, and suggest modularization. Folds the existing domain-mapper, coupling-auditor, and deepening-architect roles into one specialist. Triggers when a workflow needs architectural guidance before or during design. Never implements or rewrites code.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: deep
   permission: read-only

package/skills/agents/audit-specialist/SKILL.md

@@ -3,7 +3,7 @@ name: audit-specialist
 description: Configurable read-only audit agent. Execute specialized audits through six lenses — bugs, architecture, security, requirements, code-quality, performance — selected via the lens field in the capability packet. Triggers when a workflow needs a findings-only audit. Never modifies implementation.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: deep
   permission: read-only

package/skills/agents/builder/SKILL.md

@@ -3,7 +3,7 @@ name: builder
 description: Write-permitted implementation agent. Implement approved plans by modifying source code, creating files, and updating existing code while following project conventions. Triggers when a workflow has an approved plan or task with a disjoint write set. Never redesigns architecture, performs reviews, or generates implementation plans.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: standard
   permission: write

package/skills/agents/context-curator/SKILL.md

@@ -3,7 +3,7 @@ name: context-curator
 description: Read-only context preparation agent. Decide which files to open, retrieve memories, use Synapse when appropriate, apply Context Firewall rules, and produce a concise Context Packet consumed by other agents. Triggers when a workflow needs the minimum high-quality context before dispatching a planner, builder, or reviewer. Never implements, reviews, or plans.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: deep
   permission: read-only

package/skills/agents/designer/SKILL.md

@@ -3,7 +3,7 @@ name: designer
 description: Screen implementation and design-conformance agent. Verify and implement user-facing screens against their design source, reading Figma through MCP when a link or node id is supplied. Default read-only; writes only UI-layer files when explicitly scoped with a disjoint write set. Triggers whenever a task creates or modifies a screen. Owns screen-vs-design conformance only; no production logic outside the UI layer.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: standard
   permission: write

package/skills/agents/documentation-agent/SKILL.md

@@ -3,7 +3,7 @@ name: documentation-agent
 description: Engineering documentation agent. Generate README, ADR, RFC, changelog, KDoc, and architecture documentation. Default read-only; writes only doc files when explicitly scoped with a disjoint write set. Triggers when a workflow needs documentation artifacts. Never modifies implementation.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: light
   permission: write

package/skills/agents/furps-analyst/SKILL.md

@@ -3,7 +3,7 @@ name: furps-analyst
 description: Read-only FURPS+ dimension analyst. Analyze exactly one FURPS+ dimension (F, U, R, P, S, or X) of a PRD or ADR against its checklist section and return structured refinement findings. Triggers when the furps-refinement workflow fans out per-dimension analysis. Never analyzes other dimensions, never writes files, never mutates Atlassian issues.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: deep
   permission: read-only

package/skills/agents/investigator/SKILL.md

@@ -3,7 +3,7 @@ name: investigator
 description: Read-only codebase investigation agent. Locate implementations, trace execution flow, identify dependencies, estimate change impact, and answer engineering questions. Triggers when a workflow needs to understand existing code before planning or implementing. Never modifies code, never generates implementation, never performs reviews.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: deep
   permission: read-only

package/skills/agents/judge/SKILL.md

@@ -3,7 +3,7 @@ name: judge
 description: Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.2.0"
   model_tier: deep
   permission: write

package/skills/agents/meta-judge/SKILL.md

@@ -3,7 +3,7 @@ name: meta-judge
 description: Read-only evaluation-specification author for judge-with-debate. Generate the tailored rubric, criteria, weights, and checklists that a panel of judge agents uses to evaluate an artifact through independent analysis and multi-round debate. Runs exactly once per evaluation. Never scores the artifact, never edits the specification after emission.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.1.0"
   model_tier: deep
   permission: read-only

package/skills/agents/mobile-specialist/SKILL.md

@@ -3,7 +3,7 @@ name: mobile-specialist
 description: Conditional mobile expertise agent. Provide Android, Kotlin, Compose, KMP, Swift, iOS, Gradle, CocoaPods, performance, lifecycle, and offline-sync guidance. Invoked only when the workflow detects a mobile-related project. Read-only. Triggers on mobile detection signals; refuses non-mobile targets.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: deep
   permission: read-only

package/skills/agents/navigator/SKILL.md

@@ -3,7 +3,7 @@ name: navigator
 description: Code exploration specialist that leverages the massa-ai semantic index instead of brute-force file reads. Use when the user asks "where is X?", "how does Y work?", "who calls Z?", or for any question about an indexed codebase. Starts every investigation by consulting the massa-ai index (project map, definitions, references) before falling back to Read/Grep.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.1.0"
   model_tier: deep
   permission: read-only

package/skills/agents/plan-critic/SKILL.md

@@ -3,7 +3,7 @@ name: plan-critic
 description: Read-only plan-challenge agent. Stress-test a constructed plan, surface the assumption most likely to fail, name the deterministic check that would falsify success, and return a bounded critique for the lite or full Plan Challenge gate. Triggers after a concrete plan exists. Never edits the plan, never implements, never expands scope.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: deep
   permission: read-only

package/skills/agents/planner/SKILL.md

@@ -3,7 +3,7 @@ name: planner
 description: Read-only planning agent. Transform engineering requests into implementation plans by breaking work into steps, identifying dependencies and risks, suggesting execution order, and producing an implementation strategy. Triggers when a workflow needs a plan before implementation. Never implements or reviews code.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: deep
   permission: read-only

package/skills/agents/requirements-analyst/SKILL.md

@@ -3,7 +3,7 @@ name: requirements-analyst
 description: Read-only requirements analysis agent. Detect ambiguity, missing requirements, contradictions, implicit requirements, and uncovered scenarios before implementation. Triggers during the Specify phase when gray areas, persistence, external calls, auth, payments, concurrency, or state transitions affect behavior. Never implements.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: deep
   permission: read-only

package/skills/agents/reviewer/SKILL.md

@@ -3,7 +3,7 @@ name: reviewer
 description: Read-only diff review agent. Analyze diffs to detect bugs, regressions, code smells, missing edge cases, and suggest improvements. Triggers after a builder completes a task and before the verification gate. Never implements, rewrites files, or plans features.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: deep
   permission: read-only

package/skills/agents/test-engineer/SKILL.md

@@ -3,7 +3,7 @@ name: test-engineer
 description: Testing strategy agent. Generate unit, integration, edge-case, negative-scenario, and acceptance-coverage test plans. Default read-only; writes only test files when explicitly scoped with a disjoint write set. Triggers when a workflow needs a test strategy or test plan. Focuses only on testing; no production code changes outside test files.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: standard
   permission: write

package/skills/agents/verification-agent/SKILL.md

@@ -3,7 +3,7 @@ name: verification-agent
 description: Read-only verification agent. Centralize Verification Ladder logic by validating outputs, choosing the verification level, executing the verification checklist, detecting incomplete work, and producing verification reports. Triggers as the mandatory final gate before a task is claimed complete. Never modifies implementation.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
   model_tier: deep
   permission: read-only

package/skills/bootstrap/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: bootstrap
+description: Inspect or toggle the massa-ai startup-contract rules (caveman, massa-ai-router, persona-router, dedupe-guardrails, plan-challenge, conversation-feedback, indexing-hygiene, english-code, code-comments) that the installed MASSA-AI.md delivers to this host. Use when the user asks which startup rules are active, asks to turn one on or off, or asks why a rule is or is not being applied. Do NOT use for editing the rule text itself (that is a massa-ai repository change, not a runtime toggle) and do NOT claim a toggle is live before the user restarts the host session.
+license: MIT
+metadata:
+  author: Luiz Massa
+  version: 1.0.0
+---
+
+# Bootstrap Rule Toggle Skill
+
+## Mission
+Drive the one massa-ai bootstrap toggle engine through its CLI and relay the engine's own per-host report — never a second toggle path, never a hand-edited `MASSA-AI.md`.
+
+## When To Use
+- The user asks which startup-contract rules are active, or what a rule does.
+- The user asks to enable or disable one rule by id.
+- The user asks to preview a toggle without applying it.
+- The user asks why a rule appears not to be in force on this host.
+
+## How To Drive It
+`massa-ai-config` is the only front for this surface. There is no `bootstrap_*` MCP tool, deliberately: the toggle has to keep working when the massa-ai MCP server is unreachable, because that is exactly the state a user is in after disabling `massa-ai-router` — the rule that loads the router which would otherwise drive the toggle. Never reach for an MCP call here, and never fall back to editing a rendered file by hand.
+
+```
+massa-ai-config bootstrap list                  # every rule: id, current state, default, description
+massa-ai-config bootstrap show                  # same output as list
+massa-ai-config bootstrap enable <rule-id>  [--dry-run]
+massa-ai-config bootstrap disable <rule-id> [--dry-run]
+```
+
+Run `bootstrap list` before any toggle, so the reported change is against a state that was read, not assumed. Default to `--dry-run` first when the user has not explicitly asked to apply the change immediately: a dry run persists nothing at all — not the preference either — and only previews the per-host delivery plan.
+
+`--target <dir>` exists for scratch homes and requires `--yes`; it redirects only where the contract is *rendered*. The preference itself is always persisted to `~/.config/massa-ai/config.json`, so under a redirected target the CLI names both paths on stderr. Do not pass `--target` unless the user asked for a specific directory.
+
+## The Rule Ids
+Exactly nine ids exist, and only these are accepted. There is no protected subset — every one of them can be switched both ways, including `massa-ai-router`.
+
+- `caveman` — keep communication compressed while preserving technical accuracy. Default: enabled.
+- `massa-ai-router` — load the massa-ai skill as the workflow router before substantive work. Default: enabled.
+- `persona-router` — select one cataloged specialist persona after massa-ai context is available. Default: enabled.
+- `dedupe-guardrails` — reuse already-loaded massa-ai context instead of bulk-loading workflows or references. Default: enabled.
+- `plan-challenge` — run The Fool as a post-plan challenge gate per the configured policy. Default: enabled.
+- `conversation-feedback` — emit chat-visible status updates for massa-ai workflow progress. Default: enabled.
+- `indexing-hygiene` — ignore build output, dependency, and secret paths during indexing and context loading. Default: enabled.
+- `english-code` — write generated code, identifiers, comments, and commit-facing artifacts in English regardless of conversational language. Default: enabled.
+- `code-comments` — require API doc blocks and rationale comments on generated code. Default: **disabled**.
+
+Never invent an id. An unrecognised id is refused before anything is read or written, and the error names the id and lists all nine — relay that list rather than guessing what the user meant.
+
+Disabling `massa-ai-router` is allowed and is the user's call. Say plainly that it removes the router which reads the startup contract, and that the recovery is this same CLI (`massa-ai-config bootstrap enable massa-ai-router`), which is a binary and not a rule, so it stays reachable.
+
+## Relaying The Result
+Always relay the per-host outcome and the restart notice verbatim in substance, not just "done". The report prints one line per host, each carrying its own status literal:
+
+- `written` — the contract was written and this host loads it.
+- `written-not-wired` — the contract was written, but **nothing on this host loads it**. Never collapse this into `written` and never report it as success: the command exits non-zero on it. Relay the reason as the engine states it — which artifact is missing, in which file — together with its remedy, `scripts/install-skills.sh --apply`, and say the toggle will not take effect on that host until the wiring is added.
+- `skipped` — a byte-identical re-apply whose wiring is already present. Relay its reason; a bare "skipped" does not distinguish "already up to date" from any other no-op.
+- `failed` — relay the reason that host failed for.
+
+Three further lines carry meaning and must not be dropped:
+
+- **No host installed.** When no host is recorded, the report says so and the command exits 0. That is "nothing to do", not "nothing happened" — say which it is.
+- **Ignored persisted state.** A persisted entry that is not a known rule id with a boolean value is reported once and is never fatal. Relay the names.
+- **Restart.** When at least one host was written in a non-dry-run pass, the report states that a host session restart is required. Say so explicitly, and never claim a toggle is already in force before that restart — hosts load the startup contract at session start; there is no live in-session reload.
+
+On a dry run, say so and that no files changed.
+
+## Restrictions
+- Never use an MCP tool for this surface; none exists. The CLI must keep working with the MCP server unreachable.
+- Never invent, abbreviate, or pluralise a rule id; use only the nine ids above, exactly as the engine lists them.
+- Never hand-edit a delivered `MASSA-AI.md`, a host's `AGENTS.md`, or `~/.config/massa-ai/config.json` to satisfy a toggle request — the engine owns those bytes, and a hand edit is overwritten by the next apply.
+- Never edit the rule text itself to satisfy a toggle request; that is a massa-ai repository change owned by a different workflow.
+- Never claim a toggle is live before the affected host's session restarts.
+- Never report a `written-not-wired` host as switched.

package/skills/massa-ai/SKILL.md

@@ -3,7 +3,7 @@ name: massa-ai
 description: Default memory-backed workflow router for every coding, planning-before-coding, debugging, code review, refactoring, or implementation conversation. Always load it once per new coding session, select specialized workflows first, and use the general fallback otherwise. Handles massa-ai recall/search, durable memory, context compaction, handoff, audits, specs, ADR/RFC/TDD, and evidence gates. Do NOT use for generic non-coding chat or bulk-loading every workflow/reference.
 license: MIT
 metadata:
-  author: S1LV4, luizgmassa
+  author: Luiz Massa
   version: "1.0.0"
 ---
 
@@ -297,6 +297,7 @@ Load only when a selected workflow asks for them:
 - `references/lessons.md`
 - `references/naming-standards.md`
 - `references/pr-task-fix.md`
+- `references/code-quality-lens.md`
 - `references/architecture-lenses.md`
 - `references/architecture-domain-lens.md`
 - `references/architecture-coupling-lens.md`

package/skills/massa-ai/references/agent-orchestration.md

@@ -137,8 +137,6 @@ dispatch.
 
 Before adding a new reusable role, load `references/subagent-design.md` and write a bounded role charter. For one-off tasks, use an existing role plus the prompt contract below instead of inventing a new role.
 
-## Roles
-
 **The roster lives in one place: the Agent Table of `skills/AGENTS.md`**, which names
 every shipped specialist with its purpose, trigger, permission, and charter path. Do not
 restate it here. A second roster in this file is what let `judge` and `meta-judge` go
@@ -181,11 +179,50 @@ When dispatching a subagent, send a compact capability packet rather than a loos
 - `output`: the exact output contract
 - `firewall`: raw logs, diffs, snapshots, reports, or research that must be summarized
 - `memory`: whether the subagent may suggest memories and who persists them
-- `persona`: optional. The cataloged persona id in effect for the parent conversation, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions. Pass the id alone, never the persona prompt.
+- `persona`: optional. The active route's cataloged persona id in effect for the parent conversation, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions. Pass the id alone, never the persona prompt. Omit the field when no persona is routed.
 - `next_use`: what the main agent will do with the result
 - `lens`: conditional — `audit-specialist` dispatches only. One of `bugs | architecture | security | requirements | code-quality | performance`.
 
-The named dispatch block that workflows embed (the quoted block whose header carries the prefixed agent name and role) is the block projection of this packet: `role` and `purpose` live in the block's header line, and `next_use` defaults to "the main agent synthesizes and continues the workflow" when absent. The remaining eight fields — `trigger, scope, permissions, inputs, sensors, output, firewall, memory` — appear as the block's body lines. The optional `persona` field appears there too.
+The named dispatch block that workflows embed (the quoted block whose header carries the prefixed agent name and role) is the block projection of this packet: `role` and `purpose` live in the block's header line, and `next_use` defaults to "the main agent synthesizes and continues the workflow" when absent. The remaining eight fields — `trigger, scope, permissions, inputs, sensors, output, firewall, memory` — appear as the block's body lines, except where Role Defaults below already fix a field's value.
+
+### Role Defaults
+
+A dispatch block carries only what varies. Every line below is that field's value
+for **every** dispatch of the named role, supplied by this file rather than
+restated per workflow. A block that restates one has forked the contract, which
+is the failure these defaults exist to make impossible — the same field said
+twice is the same field free to disagree.
+
+Reading a workflow's dispatch block therefore means reading this section beside
+it. That is the trade: the block stops being self-contained in exchange for
+having exactly one place a shared value can be wrong.
+
+**Every role, every dispatch**
+
+- `persona` — as defined in the Capability Packet list above. It is never written
+  in a dispatch block; it applies to all of them.
+
+**`massa-ai-reviewer`**
+
+- `fallback`: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+
+**`massa-ai-verification-agent`**
+
+- `permissions`: read-only
+
+**`massa-ai-designer`** — its dispatch is mandatory-on-condition, so its trigger is
+fixed here rather than per workflow; a block that reworded it would silently make
+the dispatch advisory in that one file.
+
+- `trigger`: the task creates or modifies a user-facing screen — mandatory once that condition holds, per the Screen Implementation Exception in `references/agent-orchestration.md`; it does not fire when no screen surface is touched
+- `sensors`: Figma MCP read when a design source exists; per-element expected-vs-actual comparison; the UI module's own build/lint; the states a design under-specifies — empty, loading, error, long text, small and large sizes
+- `inputs`: exact `projectId`, parent `workflowSessionId`, Figma links/node ids or screenshots when supplied, acceptance criteria, the repository's existing UI conventions and design tokens, recalled screen patterns
+- `firewall`: summarized design-source evidence and `path:line` pointers only, never raw Figma node dumps or full file bodies
+- `memory`: suggest-only; the main agent persists durable screen and design-token conventions
+
+A designer block therefore carries only `scope`, `permissions` and `output` — the
+three fields that genuinely differ between an audit that may not write and an
+implementation workflow that may.
 
 ## Prompt Contract
 

package/skills/massa-ai/references/audit-scope.md

@@ -4,7 +4,7 @@ Use from audit workflows, implementation audit, bug finder, mobile Figma, and ex
 
 ## Scope Packets
 
-Every audit scope must produce a compact scope packet before analysis:
+Every audit scope must produce a compact scope packet before analysis. Resolve the mechanical half of it with `bun skills/massa-ai/scripts/resolve_scope.ts --scope modified|range|branch|files|whole`, which emits scope type, target focus, resolution method, base, head, resolved files, applied exclusions, and a freshness timestamp as JSON. It resolves files, not judgment: the ask-when-vague rule below and the per-lens evidence selection stay with the agent, and the script refuses rather than inventing a base when none can be resolved.
 
 ```text
 Scope Type: <modified files | explicit files/globs | commit range | branch comparison | codebase area | symbol/class/function | feature/flow | PR diff>

package/skills/massa-ai/references/code-annotation.md

@@ -2,7 +2,9 @@
 
 Use in every implementation workflow, before writing or editing
 source. Defines the three things every created or updated unit of code owes
-the next reader: an API doc block, a rationale comment, and a test.
+the next reader: an API doc block, a rationale comment, and a test. The first
+two are gated by a bootstrap toggle; the test is not — read Toggle Scope below
+before applying any of them.
 
 ## Principle
 
@@ -12,6 +14,19 @@ what does it do, why does it exist in this shape, and how do I prove it still
 works. Doc blocks answer the first, rationale comments the second, tests the
 third. None substitutes for another.
 
+## Toggle Scope
+
+§1 (API Doc Block) and §2 (Rationale Comment) apply only while the
+`code-comments` bootstrap rule is enabled, and `code-comments` defaults to
+**off** — so on a fresh install neither section is in force, and generated code
+carries no API doc blocks and no rationale comments.
+
+§3 (Tests) sits outside that gate and applies unconditionally: no toggle state
+weakens, narrows, or removes the test-coverage requirement.
+
+Read the current state with `massa-ai-config bootstrap list`; the rendered
+`MASSA-AI.md` startup contract is what states it for the running session.
+
 ## 1. API Doc Block
 
 Every **created or updated** public class, method, exported function, and public

package/skills/massa-ai/references/code-quality-lens.md

@@ -0,0 +1,107 @@
+# Code Quality Lens
+
+Load from `workflows/code-quality/code-quality-audit.md` (detection) and
+`workflows/code-quality/code-quality-fix.md` (repair). Both workflows used to
+carry their own copy of these rules, in different words, which is how one copy
+drifts into saying something the other does not.
+
+This file owns the rules themselves. Each workflow owns only what is genuinely
+its own: the audit owns static leads, severity, and the report contract; the fix
+owns sizing, the refactoring map, and behavior preservation.
+
+## The Split Criterion
+
+One criterion governs every "should this be split out?" question in this lens,
+whether the answer becomes a finding or an edit:
+
+**Split only when the result yields an externally-findable named unit (locatable
+by search or grep from outside the file) or measurably reduces change risk;
+never split on size or "more than one thing" alone.**
+
+The negative half is the load-bearing half. "This function does more than one
+thing" and "this file is long" are observations, not defects: an extraction that
+produces a helper only its single caller can find has moved the code without
+making anything easier to locate, change, or delete. Splitting on an accurate
+description needing the word "and" is the specific rule this replaces, and it is
+not a rule here.
+
+Apply the same criterion, unchanged, when the question is inverted — whether to
+inline rather than split.
+
+## File Shape
+
+Flag multi-subject files (unrelated exported surfaces bundled together) and any
+file over ~600 lines, regardless of subject count — it crowds out working
+context for the rest of the task (see `references/coding-guidelines.md` "File
+shape for agent readers"). Do NOT flag a single-subject file for line count
+alone below that bound.
+
+## SOLID
+
+Non-test source only.
+
+| Principle | Flag when | Fix direction |
+|---|---|---|
+| Single Responsibility | a class or module bundles distinct concern groups — validation plus persistence, formatting plus dispatch — and separating them meets the Split Criterion above, never on concern-count or size alone | separate mixed responsibilities only when the split yields an externally-findable named unit (locatable by search or grep from outside the file) or reduces change risk |
+| Open/Closed | a caller-side switch or if/else chain on a type tag means adding a variant requires modifying existing files | replace with polymorphism or a data map only when new variants are real |
+| Liskov | a subtype throws where the base does not, ignores required methods, or narrows the base contract | preserve base contracts |
+| Interface Segregation | an interface forces implementors to define unused methods | narrow fat interfaces |
+| Dependency Inversion | a hardcoded `new ConcreteType()` sits inside a class body where abstraction or injection would be natural | inject dependencies when hardcoded concretes block testing or substitution |
+
+## Clean Code
+
+Test and non-test source.
+
+| Smell | Flag when | Fix direction |
+|---|---|---|
+| Magic values | a meaningful bare literal repeats — strings, timeouts, thresholds, event names | replace with named constants |
+| Function does more than one thing | the Split Criterion above is met | split functions only when the result yields an externally-findable named unit (locatable by search or grep from outside the file) or measurably reduces change risk — never split on size or "more than one thing" alone |
+| Unqualified generic names | a name carries no domain or role qualification | name domain concepts precisely using `references/naming-standards.md` |
+| What-comments | a comment restates the code | remove it; keep only why comments for constraints, workarounds, or non-obvious invariants |
+| Half-finished surfaces | an exported TODO, stub, placeholder return, or "implement later" path | finish or delete it |
+| Long parameter lists | more than 3-4 positional parameters | convert to an options object when it improves call-site clarity |
+
+## KISS, YAGNI, DRY
+
+**KISS.** Flag abstractions, layers, indirection, or control flow that raise
+cognitive load without clearly improving readability, correctness, or constraint
+handling. Call out premature generalization, deep call chains, excessive
+configuration, and clever patterns that obscure intent. Prefer straightforward,
+explicit code a new reader can follow end-to-end: inline trivial abstractions,
+collapse unnecessary layers, choose boring solutions unless complexity is
+justified (real variability, hard constraints, or measured bottlenecks). When
+weighing whether to split instead of inline, apply the Split Criterion above
+unchanged — the direction of the question does not change the criterion.
+
+**YAGNI.** Flag speculative features, extension points, and generic
+infrastructure with no concrete caller, requirement, or near-term use. Call out
+"just in case" hooks, over-parameterization, unused toggles, and frameworks
+introduced ahead of need. Prefer implementing only what current use cases
+demand, structured to evolve when real requirements appear. Defer generalization
+until duplication or constraints force it, and remove dead or unused paths
+aggressively.
+
+**DRY.** Flag duplicated logic, data transformations, or domain rules repeated
+without a strong reason (e.g., performance isolation or explicit decoupling).
+Highlight copy-paste patterns, parallel conditionals, and repeated constants
+that raise maintenance cost or inconsistency risk. Recommend consolidation into
+a single source of truth when it improves clarity and reduces bugs, but avoid
+over-abstraction that harms readability or adds indirection for trivial reuse.
+
+**AI-slop surfaces.** Generic abstractions with no domain vocabulary,
+fabricated-looking type names, unnecessary factories/builders, wrappers around
+one call, comments that narrate obvious code, and broad configurability not
+supported by current requirements. Remove them when current usage evidence does
+not justify them.
+
+## Standing Rules
+
+- Prefer delete, inline, or merge over a replacement abstraction whenever simpler
+  code preserves behavior.
+- Require usage evidence before calling a surface unnecessary. When the evidence
+  is incomplete, mark the item `suspect` rather than reporting it as a defect.
+- **Architecture boundary.** Do not report, recommend, or introduce ports,
+  adapters, bounded contexts, new service/module boundaries, or VSA-style folder
+  migration from this lens. Those need dependency-direction, strength, distance,
+  volatility, module-depth, or cross-domain ownership evidence this lens does not
+  gather — hand them to `workflows/architecture/architecture-audit.md`.

package/skills/massa-ai/references/code-reuse-scan.md

@@ -39,7 +39,6 @@ implementation code is planned or written:
 > - output: the reuse map (below), evidence-or-zero when nothing reusable is found
 > - firewall: summarized candidates and pointers only, never raw file dumps
 > - memory: suggest-only; main agent persists durable reuse findings
-> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
 
 Dispatch one subagent per coherent target area; dispatch more than one only
 when the areas are independent enough to scope separately.

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

@@ -18,8 +18,8 @@ human chose to merge it".
 
 | # | Stage | Command | On failure |
 | --- | --- | --- | --- |
-| 0 | Preflight | `git rev-parse --is-inside-work-tree`; `command -v gh`; `gh auth status` | Record which capabilities are absent and select the degraded path below |
-| 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 |
+| 0 | Preflight | `bun skills/massa-ai/scripts/ensure_worktree.ts` runs this: `git rev-parse --is-inside-work-tree`; `command -v gh`; `gh auth status` | Record which capabilities are absent and select the degraded path below |
+| 1 | Isolate | `bun skills/massa-ai/scripts/ensure_worktree.ts --branch <type>/<slug> [--base <base>] [--path <path>]`, which runs `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. The script applies both rules and prints the resulting path + branch |
 | 1.5 | Summarize | present the pre-implementation change summary (see Stage 1.5) | Summary skipped → stop and present it before the first mutation; a mutation made without it is a protocol violation to report, not to hide |
 | 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 |
@@ -45,7 +45,10 @@ The only two legal skip reasons:
 2. The user explicitly declined isolation for this task.
 
 Record the skip reason verbatim in the completion report. Any other reason is a
-protocol violation, not a shortcut.
+protocol violation, not a shortcut. `ensure_worktree.ts` emits exactly these two
+strings and no third: it detects reason 1 from the tree, and takes reason 2 only
+from an explicit `--skip-declined`, because a script cannot observe a user
+declining anything.
 
 **Record the isolation evidence immediately after creation:** the worktree path
 and branch name go into the session status the moment Stage 1 completes, and

package/skills/massa-ai/references/naming-standards.md

@@ -30,13 +30,18 @@ Code vocabulary is evidence, not truth. When business intent is inferred only fr
 
 ## Language
 
-All new or renamed identifiers, classes, methods, screens, components,
-attributes, and implementation-facing artifact names are written in English.
-Convert any non-English source term to English before implementing —
-Portuguese is the primary case, but the rule covers any non-English source
-language. Preserve existing public contracts, persisted fields, and external
-names unless compatibility handling is explicitly in scope, per the
-public-contract clause above.
+This section is normative for **identifier** naming only, per AD-019's
+one-normative-reference discipline. New or renamed identifiers, classes,
+methods, screens, components, attributes, and implementation-facing artifact
+names use English words. Convert any non-English source term to English before
+implementing — Portuguese is the primary case, but the rule covers any
+non-English source language. Preserve existing public contracts, persisted
+fields, and external names unless compatibility handling is explicitly in
+scope, per the public-contract clause above.
+
+Everything past an identifier is owned by the `english-code` bootstrap rule in
+the rendered `MASSA-AI.md` startup contract. Consult that rule there rather
+than this section; the wider contract is deliberately not restated here.
 
 ## Workflow Use