@massa-ai/cursor-plugin 1.54.1 → 1.56.0

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.54.1",
+  "version": "1.56.0",
   "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
   "files": [
     "agents",

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

@@ -56,7 +56,7 @@ Provide architectural guidance by evaluating structure, suggesting boundaries, a
 - Verification Ladder: static (coupling, depth, boundary) checks; no behavioral changes.
 - Massa-ai Memory: suggest durable architecture-decision memories only when a boundary or abstraction is recommended; main agent persists.
 - Synapse: own ephemeral session when evaluation spans multiple modules with repeated searches.
-- References: `references/architecture-lenses.md`, `references/architecture-domain-lens.md`, `references/architecture-coupling-lens.md`, `references/architecture-deepening-lens.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/architecture-lenses.md`, `references/architecture-domain-lens.md`, `references/architecture-coupling-lens.md`, `references/architecture-deepening-lens.md`.
 
 ## Validation Sensors
 - Every finding has a `path:line` or metric pointer.

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

@@ -72,7 +72,7 @@ All lenses share `references/audit-scope.md` (scope rules) and `references/audit
 - Verification Ladder: static checks per lens; no behavioral changes (findings-only).
 - Massa-ai Memory: suggest durable audit-pattern memories only when a lens reveals a recurring issue class; main agent persists.
 - Synapse: own ephemeral session when the audit spans multiple modules with repeated searches.
-- References: `references/audit-scope.md`, `references/audit-report-io.md`, plus the per-lens references above.
+- References (paths relative to the `massa-ai` skill directory): `references/audit-scope.md`, `references/audit-report-io.md`, plus the per-lens references above.
 
 ## Validation Sensors
 - Every finding has a `path:line` pointer.

package/skills/agents/builder/SKILL.md

@@ -58,7 +58,7 @@ Implement an approved plan or task by modifying source code with a disjoint writ
 - Verification Ladder: run the task's sensors (static + behavioral) before claiming Complete.
 - Massa-ai Memory: suggest durable code-pattern memories only when the implementation establishes a reusable convention; main agent persists.
 - Synapse: none (implementation is not a repeated-search task).
-- References: `references/agent-orchestration.md`, `references/naming-standards.md`, `references/code-annotation.md`, `references/root-cause-scripts.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`, `references/naming-standards.md`, `references/code-annotation.md`, `references/root-cause-scripts.md`.
 
 ## Validation Sensors
 - Verification commands from the plan pass (tests, build, typecheck, lint).

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

@@ -58,7 +58,7 @@ Prepare the minimum high-quality Context Packet required for another agent to do
 - Verification Ladder: static checks only (file existence, reference existence).
 - Massa-ai Memory: retrieve via `recall`; do not persist unless the main agent assigns it.
 - Synapse: own ephemeral session per `references/synapse-policy.md`; pass `synapseSessionId` on every `search`.
-- References: `references/context-firewall.md`, `references/synapse-policy.md`, `references/mcp-tools.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/context-firewall.md`, `references/synapse-policy.md`, `references/mcp-tools.md`.
 
 ## Validation Sensors
 - Every file in the Context Packet exists (`test -f`).

package/skills/agents/designer/SKILL.md

@@ -59,7 +59,7 @@ Own the screen: verify an existing user-facing screen against its design source,
 - Verification Ladder: behavioral (the UI module builds and its tests pass) and file-integrity (no validation asset weakened).
 - Massa-ai Memory: suggest durable memories only when a reusable screen or design-token convention is established; the main agent persists.
 - Synapse: none by default; request an ephemeral session only when the scope needs two or more related searches across the UI layer.
-- References: `references/figma-pre-analysis.md`, `references/figma-wiring.md`, `references/design-implementation.md`, `references/naming-standards.md`, `references/verification-ladder.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/figma-pre-analysis.md`, `references/figma-wiring.md`, `references/design-implementation.md`, `references/naming-standards.md`, `references/verification-ladder.md`.
 
 ## Validation Sensors
 - Every design element in scope appears in the conformance table with a verdict, or the table states why the design source did not cover it.

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

@@ -56,7 +56,7 @@ Generate engineering documentation artifacts (README, ADR, RFC, changelog, KDoc,
 - Verification Ladder: static (doc-lint, stale-reference, link check); no behavioral sensors.
 - Massa-ai Memory: suggest durable doc-format memories only when a documentation convention is established; main agent persists.
 - Synapse: none (documentation is not a repeated-search task).
-- References: `references/adr-authoring.md`, `references/rfc/`.
+- References (paths relative to the `massa-ai` skill directory): `references/adr-authoring.md`, `references/rfc/`.
 
 ## Validation Sensors
 - Stale-reference scan passes (no dead links to removed files).

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

@@ -60,7 +60,7 @@ Analyze exactly one FURPS+ dimension of a PRD or ADR against its checklist secti
 - Verification Ladder: static evidence checks only — source-location proof per claim, absent-claim detection per `missing`.
 - Massa-ai Memory: suggest durable memories only when a reusable refinement pattern is discovered; the main agent persists.
 - Synapse: own ephemeral session when >= 2 searches are expected, per `references/synapse-policy.md`.
-- References: `references/furps/checklist.md`, `references/furps/report-contract.md`, `references/furps/intake.md`, `references/agent-orchestration.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/furps/checklist.md`, `references/furps/report-contract.md`, `references/furps/intake.md`, `references/agent-orchestration.md`.
 
 ## Validation Sensors
 - Source-location proof (quote plus section) for every `covered`/`partial` claim.

package/skills/agents/investigator/SKILL.md

@@ -59,7 +59,7 @@ Read and understand the codebase to answer engineering questions without modifyi
 - Verification Ladder: static checks (grep, search) and file-integrity; no behavioral changes.
 - Massa-ai Memory: suggest durable architecture/dependency memories only when useful; main agent persists.
 - Synapse: own ephemeral session per `references/synapse-policy.md`; pass `synapseSessionId` on every `search`.
-- References: `references/codebase-investigation.md`, `references/agent-orchestration.md`, `references/synapse-policy.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/codebase-investigation.md`, `references/agent-orchestration.md`, `references/synapse-policy.md`.
 
 ## Validation Sensors
 - Source-backed evidence for every claim (`path:line`).

package/skills/agents/judge/SKILL.md

@@ -80,7 +80,7 @@ next_step: <string>
 - Verification Ladder: every score cites a quotation; a score without a quote is a sensor failure.
 - Massa-ai Memory: suggest durable memories only for reusable evaluation failure patterns; the main agent persists.
 - Policy: the orchestrator owns dispatch, consensus arithmetic, and the final verdict; this agent owns its scores and its file only.
-- References: `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
 
 ## Model Hint
 See `references/agent-orchestration.md` (Model Diversity Fallback): `metadata.model_tier`

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

@@ -71,7 +71,7 @@ overall: weighted-mean
 - Verification Ladder: every criterion must be checkable by quoting the artifact — a criterion that cannot be evidenced is not a criterion.
 - Massa-ai Memory: suggest durable memories only for reusable rubric patterns; the main agent persists.
 - Policy: the main agent (judge-with-debate orchestrator) owns dispatch, YAML validation, retry, and consensus; this agent owns the specification only.
-- References: `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
 
 ## Model Hint
 See `references/agent-orchestration.md` (Model Diversity Fallback): `metadata.model_tier`

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

@@ -73,7 +73,7 @@ If none are present, refuse with: `Non-mobile target. Refusing mobile-specialist
 - Verification Ladder: platform-specific static checks when available; no behavioral changes.
 - Massa-ai Memory: suggest durable mobile-decision memories only when a platform constraint or lifecycle pattern is established; main agent persists.
 - Synapse: own ephemeral session when guidance spans multiple mobile modules with repeated searches.
-- References: `references/mobile-context.md`, `references/mobile-diagnosis.md`, `references/maestro.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/mobile-context.md`, `references/mobile-diagnosis.md`, `references/maestro.md`.
 
 ## Validation Sensors
 - At least one detection signal is confirmed present before guidance is given.

package/skills/agents/navigator/SKILL.md

@@ -66,7 +66,7 @@ The user's codebase is **already indexed** by massa-ai. The first move on any qu
 - Orphaned-dims recovery: if a vector `search` returns 0 results while other dim tables hold chunks for the project, report to the parent agent that `index` with `forceReindex=true` is required. Do not run it.
 - Context Firewall: summarize search output; return only `path:line` pointers and findings.
 - Massa-ai Memory: suggest durable navigation facts (entry points, ownership boundaries) only when reusable; the main agent persists.
-- References: `references/mcp-tools.md`, `references/codebase-investigation.md`, `references/synapse-policy.md`, `references/context-firewall.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/mcp-tools.md`, `references/codebase-investigation.md`, `references/synapse-policy.md`, `references/context-firewall.md`.
 
 ## Validation Sensors
 - Every claim carries a `path:line` or symbol pointer.

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

@@ -79,7 +79,7 @@ Never receives full conversation context.
 - Verification Ladder: every challenge names the concrete sensor that would settle it.
 - Massa-ai Memory: suggest durable memories only for reusable failure modes or rejected approaches; the main agent persists.
 - Policy: the main agent owns mode selection, synthesis, plan revision, and the Evidence Gate; this agent owns the critique only.
-- References: `references/agent-orchestration.md`, `references/the-fool/`, `references/verification-ladder.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`, `references/the-fool/`, `references/verification-ladder.md`.
 
 ## Validation Sensors
 - Every challenge ties to a plan section plus a concrete evidence gap or falsifiable check.

package/skills/agents/planner/SKILL.md

@@ -56,7 +56,7 @@ Transform an engineering request into a structured implementation plan.
 - Verification Ladder: plan references expected sensors; does not run them.
 - Massa-ai Memory: suggest durable decision memories only when the plan locks a strategy; main agent persists.
 - Synapse: none (planning is not a repeated-search task).
-- References: `references/agent-orchestration.md`, `references/subagent-design.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`, `references/subagent-design.md`.
 
 ## Validation Sensors
 - Every step in the plan references a concrete file, module, or task.

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

@@ -55,7 +55,7 @@ Analyze requirements before implementation to surface ambiguity, gaps, contradic
 - Verification Ladder: static (spec citation) only; no behavioral sensors.
 - Massa-ai Memory: suggest durable requirement-decision memories only when an implicit requirement is accepted as an assumption; main agent persists.
 - Synapse: none (analysis is not a repeated-search task).
-- References: `references/spec-driven/specify.md`, `references/furps/`.
+- References (paths relative to the `massa-ai` skill directory): `references/spec-driven/specify.md`, `references/furps/`.
 
 ## Validation Sensors
 - Every finding cites a requirement ID or spec section.

package/skills/agents/reviewer/SKILL.md

@@ -57,7 +57,7 @@ Review implementation quality by analyzing the diff and flagging bugs, regressio
 - Verification Ladder: static checks (lint, typecheck) as supporting evidence; behavioral checks belong to verification-agent.
 - Massa-ai Memory: suggest durable code-quality memories only when a review reveals a reusable pattern; main agent persists.
 - Synapse: none (review is not a repeated-search task).
-- References: `references/agent-orchestration.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`.
 
 ## Validation Sensors
 - Every finding has a `path:line` pointer.

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

@@ -58,7 +58,7 @@ Generate a testing strategy that covers unit, integration, edge cases, negative
 - Verification Ladder: behavioral (tests) and file-integrity (no validation assets weakened).
 - Massa-ai Memory: suggest durable test-pattern memories only when a testing convention is established; main agent persists.
 - Synapse: none (test planning is not a repeated-search task).
-- References: `references/verification-ladder.md`, `references/code-annotation.md`, `references/root-cause-scripts.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/verification-ladder.md`, `references/code-annotation.md`, `references/root-cause-scripts.md`.
 
 ## Validation Sensors
 - Every acceptance criterion maps to at least one test case.

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

@@ -55,7 +55,7 @@ Centralize Verification Ladder logic and validate that a task's output meets its
 - Verification Ladder: this agent IS the ladder; choose the cheapest sufficient evidence first.
 - Massa-ai Memory: suggest durable verification-recipe memories only when a sensor pattern is reusable; main agent persists.
 - Synapse: none (verification is not a repeated-search task).
-- References: `references/verification-ladder.md`, `references/evidence-gate.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/verification-ladder.md`, `references/evidence-gate.md`.
 
 ## Validation Sensors
 - Every acceptance criterion has a PASS/FAIL verdict with evidence.

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/references/architecture-lenses.md

@@ -39,28 +39,7 @@ Analyze dependency cost with strength, distance, and volatility.
 
 Load `references/architecture-coupling-lens.md` when the audit target includes dependencies, imports, service calls, shared schemas/models, direct persistence access, co-change, or contract leakage.
 
-Strength levels:
-
-- Intrusive: downstream depends on internals not designed for integration.
-- Functional: sequential, transactional, or duplicated symmetric business rules.
-- Model: upstream exposes internal domain model to downstream.
-- Contract: integration-specific DTO/protocol hides internals.
-
-Distance levels:
-
-- same function or class
-- same package
-- same module/library
-- different service
-- external system or team
-
-Volatility signals:
-
-- core business logic
-- frequent git changes or co-change
-- TODO/FIXME clusters
-- evolving API versions
-- fragile tests or recurring regressions
+Strength, distance, and volatility level definitions: full detail in `references/architecture-coupling-lens.md`.
 
 Flag highest risk when high strength, high distance, and high volatility combine.
 
@@ -88,10 +67,7 @@ Check:
 - test-only extraction that loses locality
 - concepts split across many files without leverage
 
-Use the deletion test:
-
-- If deleting a module removes complexity, it was probably shallow.
-- If deleting it spreads complexity across callers, it was probably earning its keep.
+Deletion test: full detail in `references/architecture-deepening-lens.md`.
 
 Only recommend a new seam when variation, dependency direction, external I/O, or test substitution is real.
 

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/conversation-feedback.md

@@ -17,19 +17,7 @@ repeated micro-events.
 
 ## Line Shape
 
-Each status update must be 1-2 lines. Use an emoji, a capitalized label in square brackets, and one or two plain sentences.
-
-Do:
-
-```md
-🔵 [Start] Planning visual feedback for massa-ai. Workflow: Spec Driven. Session: Visual Feedback.
-🔄 [Loading] Reading AGENTS.md and massa-ai router guidance before planning.
-🧠 [Context] Found 8 relevant massa-ai memories and queried the requested NotebookLM source.
-🤖 [Agent Running] Plan Critic is checking failure modes for the proposed design.
-⚠️ [Divergence] Expected the legacy router path, but this checkout uses skills/massa-ai/SKILL.md.
-✅ [Verified] Stale-reference checks and skill validation passed.
-🏁 [Finished] Plan complete. Changed files: none. Remaining risk: none found.
-```
+Each status update must be 1-2 lines. Use an emoji, a capitalized label in square brackets, and one or two plain sentences. The worked example is not repeated here — it lives in the canonical policy block named under Policy Source above, which is always in context.
 
 Avoid terse machine-shaped status lines, lowercase labels, equals-sign syntax, and tiny abbreviations.
 

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

@@ -131,7 +131,7 @@ recall stays owned by the router.
 
 | Failure | Behavior |
 |---|---|
-| massa-ai REST unavailable | lesson still lands in `lessons.json`; skipped memory write logged to `scripts/hooks-state/skip.log` |
-| `.specs/STATE.md` absent / workflow unset | stop gate falls back to flat matrix |
+| massa-ai REST unavailable | lesson still lands in `lessons.json`; the memory write is fire-and-forget and is dropped silently (a timeout emits a `deadline-on-fire` JSON breadcrumb on **stderr**, nothing is written to disk) |
+| `.specs/project/STATE.md` absent / workflow unset | stop gate falls back to flat matrix |
 | bad / malformed stdin | hook exits 0, never blocks |
-| hook non-critical error | exit 0, approve, log skip |
+| hook non-critical error | exit 0, approve, degrade silently — there is no skip log file |

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

@@ -166,5 +166,5 @@ best-effort. An ungrounded lesson is refused by both `add` and the massa-ai writ
 ### Self-Check
 
 After verification: if a reusable signal was found but no lesson was recorded,
-state the skipped reason. The hook loop logs every skip to
-`scripts/hooks-state/skip.log`.
+state the skipped reason. Nothing else records it — the hook loop keeps no skip
+log on disk, so your stated reason is the only record.

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

@@ -19,22 +19,6 @@ Official source anchors:
 - Cloud limits: https://docs.maestro.dev/maestro-cloud/limits.md
 - Maestro MCP: https://docs.maestro.dev/get-started/maestro-mcp.md
 
-## Load Map
-
-| Need | Load |
-|---|---|
-| Source authority, Q&A checklist handling, unsupported facts, transcript requirements | `references/maestro/fact-ledger.md` |
-| CLI preflight, device/platform readiness, local command flags, sharding, live help capture | `references/maestro/cli-device.md` |
-| YAML commands, flow headers, AI commands, examples | `references/maestro/yaml-commands.md` |
-| Core, relational, trait, state, dimension, platform, regex, and web-only selector behavior | `references/maestro/selectors.md` |
-| Flow discovery, config.yaml discovery patterns, tags, execution order, suite isolation | `references/maestro/workspace-execution.md` |
-| Flow header/config/env/report-output boundaries | `references/maestro/config-env-output.md` |
-| `evalScript`, `runScript`, `output`, `faker`, logging, `maestro.log` | `references/maestro/js-scripting.md` |
-| JUnit/HTML reports, artifact directories, debug output, screenshots, videos, AI reports, recording | `references/maestro/artifacts-reports.md` |
-| Cloud binary eligibility, auth/plan needs, app-binary reuse, Cloud device flags, Cloud limits | `references/maestro/cloud.md` |
-| Maestro MCP install/use, tool metadata, Viewer, Cloud-auth tools | `references/maestro/mcp.md` |
-| Stable suite design, setup/teardown, selectors, fixtures, output contracts, skipped checks | `references/maestro/patterns.md` |
-
 ## Minimum Step Selection
 
 - Flow implementation: load `fact-ledger.md`, `cli-device.md`, then only the focused files for the flow surface being edited: commonly `yaml-commands.md`, `selectors.md`, `workspace-execution.md`, `config-env-output.md`, `js-scripting.md`, and `patterns.md`.

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
 

package/skills/massa-ai/workflows/discovery.md

@@ -89,39 +89,6 @@ effects ("if we do X, what does that enable or foreclose?"); bring in
 competitive response; think in timeframes (3 months vs 12 months vs 3
 years).
 
-## Frameworks As Tools
-
-Pull a framework in when it moves the conversation forward — never dump
-frameworks or force the conversation through them as a checklist.
-
-- **How Might We (HMW)**: "How might we [outcome] for [user] without
-  [constraint]?" Aim between too broad ("improve onboarding") and too narrow
-  (a disguised solution); generate 5–10 reframings — each opens a different
-  solution space.
-- **Jobs-to-be-Done (JTBD)**: "When [situation], I want to [motivation] so I
-  can [outcome]." The job is stable while solutions change; emotional and
-  social jobs often outweigh functional ones. Ask "what did they fire to
-  hire this?" — it reveals the real competitive set.
-- **Opportunity Solution Tree**: outcome → opportunities (evidence-backed
-  user needs) → multiple solutions per opportunity → cheapest experiment per
-  solution. One solution per opportunity means exploration stopped too
-  early; the tree is a living artifact.
-- **First Principles Decomposition**: state the assumption, break it into
-  fundamental components, ask of each "law of physics or convention?", then
-  rebuild from only the fundamentals. Use when the team is stuck in
-  incremental thinking.
-- **SCAMPER**: seven lenses on an existing product — Substitute, Combine,
-  Adapt, Modify (10x bigger/smaller/faster), Put to other use, Eliminate
-  ("would anyone notice?"), Reverse (flip the sequence or the default).
-- **OODA Loop** (Observe–Orient–Decide–Act): a decision-tempo framework —
-  gather raw signals wide, make sense of them while challenging your own
-  orientation, choose a proportional reversible bet, act, and cycle. Use
-  when the conversation over-deliberates or keeps circling: orient with what
-  exists, decide, and let the next observation correct course.
-- **Reverse Brainstorming**: invert the problem ("how could we make this
-  worse?"), generate freely — people find flaws more easily than fixes —
-  then reverse each worsening idea into the seed of a solution.
-
 ## Session Rhythm
 
 A good session opens up before it narrows down. Move through five stages;
@@ -134,8 +101,9 @@ name the stage transition when it helps the user follow.
    to nothing.
 2. **Diverge** — Generate many ideas without judgment; build on ideas rather
    than shooting them down; follow tangents; push past the first 3–5 obvious
-   ideas; use the frameworks above to open new angles. Do not evaluate
-   feasibility here — that kills divergent thinking.
+   ideas; pull in whatever brainstorming frameworks fit the conversation to
+   open new angles. Do not evaluate feasibility here — that kills divergent
+   thinking.
 3. **Provoke** — The sparring-partner stage: "What is the strongest argument
    against this?", "Who would hate this and why?", "What are we not
    seeing?", "What if the opposite were true?", "What is the 10x more

package/skills/massa-ai/workflows/skill-architect.md

@@ -47,32 +47,15 @@ what "success" looks like.
 
 ### 1.1 — Understand the Problem
 
-Start by asking about the OUTCOME, not the implementation. Key questions
-(ask conversationally, not as a checklist dump):
-
-- **What workflow do you want to make consistent?** Get a concrete example
-  of what they do today, step by step.
-- **What goes wrong without the skill?** Understand the pain: inconsistency,
-  forgotten steps, wasted time re-explaining, wrong outputs.
-- **Who will use this skill?** Just them? Their team? Public distribution?
-  This affects naming, documentation depth, and description specificity.
-- **What tools are involved?** Built-in Agents capabilities (code execution,
-  file creation, artifacts) or external services via MCP?
+Determine: the workflow to make consistent, what goes wrong without the
+skill, who will use it (affects naming, documentation depth, and description
+specificity), and what tools are involved (built-in Agents capabilities or
+external services via MCP).
 
 ### 1.2 — Define Use Cases
 
-Nail down 2-3 concrete use cases. For each, capture:
-
-```
-Use Case: [Name]
-Trigger: What the user would say or do
-Steps: The sequence of actions
-Tools: Built-in or MCP tools needed
-Result: What success looks like (specific output)
-```
-
-If the user is vague, give them examples to react to. It's easier to refine
-a concrete proposal than to articulate needs from scratch.
+Nail down 2-3 concrete use cases, each capturing name, trigger, steps, tools
+needed, and expected result.
 
 ### 1.3 — Identify the Category
 
@@ -87,11 +70,8 @@ detailed pattern guidance):
 
 ### 1.4 — Establish Success Criteria
 
-Before moving on, agree on how they'll know the skill works:
-
-- **Trigger accuracy:** What should trigger it? What should NOT?
-- **Output quality:** What does a good result look like concretely?
-- **Efficiency:** How many interactions should it take?
+Before moving on, agree on trigger accuracy, output quality, and efficiency
+expectations — how they'll know the skill works.
 
 **Exit criteria for Discovery:**