@massa-ai/cursor-plugin 1.56.0 → 1.57.0

package/.cursor-plugin/plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/cursor-plugin",
-  "version": "1.56.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/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-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/skill-architect/authoring-principles.md

@@ -0,0 +1,37 @@
+# Skill Authoring Principles
+
+Read once, before Phase 1 of `workflows/skill-architect.md`. This file carries
+the principles and the conversational manner; the workflow carries the five
+phases, their exit criteria, and the hard rules.
+
+## Core Philosophy
+
+1. **Understand before building.** Never generate a SKILL.md until you've completed Discovery and Architecture phases. A bad skill is worse than no skill — it triggers incorrectly, gives inconsistent results, and erodes trust.
+
+2. **Progressive disclosure is everything.** The three-level system (frontmatter → SKILL.md body → linked files) exists for a reason: token economy. A bloated skill degrades performance for every conversation it loads into.
+
+3. **Composability over completeness.** Skills coexist with other skills. Never assume yours is the only one loaded. Be a good neighbor.
+
+4. **Specificity beats verbosity.** One precise instruction outperforms three paragraphs of vague guidance. Code beats prose for deterministic checks.
+
+5. **Skills are for agents, not humans.** No README.md inside the skill folder. No onboarding documentation. Write for an LLM that needs clear, actionable instructions.
+
+## Phase Sequence
+
+```
+DISCOVERY → ARCHITECTURE → CRAFT → VALIDATE → DELIVER
+```
+
+Move through phases sequentially. Never skip Discovery. Each phase has
+explicit exit criteria before you advance.
+
+## Conversation Style
+
+- Ask questions one area at a time — don't dump all Discovery questions at once
+- Give concrete suggestions the user can react to ("Would something like X work?")
+- If the user provides a vague request, propose a specific interpretation and ask
+  if it matches their intent
+- If the conversation already contains a workflow (user says "turn this into a
+  skill"), extract what you can from history FIRST, then fill gaps with questions
+- Match the user's technical level — explain terms if they seem non-technical
+- Be direct about tradeoffs: if a design choice has a downside, say so

package/skills/massa-ai/references/verification-ladder.md

@@ -10,6 +10,8 @@ Classify implementation size before editing:
 - Standard: <=10 files or <=500 changed LOC within one ownership area, or shared behavior/public API/test impact that still has clear acceptance criteria and no unresolved architecture decision.
 - Spec-driven: >10 files, >500 changed LOC, multiple ownership areas, unclear acceptance criteria, new dependency, migration, irreversible operation, security/privacy/auth, public compatibility, cross-service contract, or any unresolved architecture/product decision.
 
+Get the file and LOC halves from `bun skills/massa-ai/scripts/size_change.ts` (`--staged` for the index, `--range <a>..<b>` for a range) rather than counting a diff by eye. It reports changed files, changed LOC (added + deleted), and the resulting **size floor**. The qualitative half of each bullet above — acceptance criteria, dependencies, migrations, irreversible operations, security/privacy/auth, public compatibility, cross-service contracts, unresolved decisions — is invisible to a diff, so the script's answer is a lower bound: raise it when any of those applies, never lower it.
+
 Quick tasks can proceed inside the active workflow. Standard tasks need an explicit verification recipe before edits. Spec-driven tasks should route to `workflows/spec-driven.md` or be split into atomic tasks.
 
 ## Shared Reference Trigger Table

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

@@ -33,7 +33,10 @@
 
 import { readFileSync } from "node:fs";
 
-const TYPES = ["feat", "fix", "refactor", "docs", "test", "style", "perf", "build", "ci", "chore"];
+// `revert` is in the list because `workflows/commit.md` §8 names it in the type
+// precedence order the workflow tells the agent to pick from. Without it the
+// script rejected a message the workflow had just instructed the agent to write.
+const TYPES = ["feat", "fix", "refactor", "docs", "test", "style", "perf", "build", "ci", "chore", "revert"];
 
 // 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