@massa-ai/claude-plugin 1.63.1 → 1.64.0

package/skills/massa-ai/references/mcp-tools.md

@@ -148,32 +148,19 @@ depends on exact content.
 
 ## Retrieval Order
 
-1. `list_projects` or equivalent index metadata to verify project ID,
-   path, status, and `lastIndexedAt` before treating indexed context as current.
-2. `project_map` for general architecture orientation when the index is fresh for the current repository path and worktree state.
-3. `get_architecture` for architecture-specific deep maps (packages, routes, hotspots, communities, cycles) when the index is fresh.
-4. `search(responseMode="summary", maxResults=10)` for broad discovery.
-5. `search(responseMode="enriched", maxResults=3)` for targeted deep reads with `fileImports`, `parentSymbol`, and chunk navigation metadata; raise to `maxResults=5` only when 4-5 exact files, symbols, or report finding IDs are already named.
-6. Symbol tools (`search_definitions`, `get_references`, `go_to_definition`) and `read_file` for exact source evidence.
-7. `symbol_snippet` for raw code snippets by file + line range.
-8. `trace_path` for typed-edge BFS call/data-flow path tracing (fresh index only).
-9. `impact_analysis` for git-diff centrality-ranked impact (fresh index only).
-10. `optimized_context` for compact synthesized context when available.
-11. Focused `rg`/file reads when massa-ai is unavailable, stale, incomplete, or misses obvious local truth.
-
-Do not use `full` or `enriched` for broad whole-project sweeps. Attempt REST fallback exactly once after a documented MCP schema, adapter, or missing-operation failure; if REST also fails, continue with MCP/local fallback and record the skipped reason.
-
-Graph tools (`trace_path`, `impact_analysis`, `get_architecture`) only count as
-evidence when the index is fresh for the current repository path and
-commit/worktree state. When the index is stale, incomplete, missing the target
-path, or older than relevant local changes, fall back to `search`/`get_references`
-and record the reduced retrieval confidence.
+The ordered retrieval list is owned by `references/codebase-investigation.md`
+§Source Order — follow it end to end; it is not restated here. This section
+is the MCP parameter/budget schema delta for tools in that order:
+
+- `list_projects`: verify project ID, path, status, and `lastIndexedAt` before treating indexed context as current.
+- `search(responseMode="summary", maxResults=10)` for broad discovery; `search(responseMode="enriched", maxResults=3)` for targeted deep reads with `fileImports`, `parentSymbol`, and chunk navigation metadata; raise to `maxResults=5` only when 4-5 exact files, symbols, or report finding IDs are already named. Do not use `full` or `enriched` for broad whole-project sweeps.
+- `symbol_snippet`: raw code snippets by exact file + line range (see the Capability Matrix above for required fields).
+- Graph tools (`trace_path`, `impact_analysis`, `get_architecture`) only count as evidence when the index is fresh for the current repository path and commit/worktree state; when stale, incomplete, missing the target path, or older than relevant local changes, fall back to `search`/`get_references` and record the reduced retrieval confidence.
+- Attempt REST fallback exactly once after a documented MCP schema, adapter, or missing-operation failure; if REST also fails, continue with MCP/local fallback and record the skipped reason.
 
 Project maps, search hits, and optimized context are discovery leads until
-confirmed against source files read in the current session or returned with
-freshness evidence for the current worktree. When index status is stale,
-incomplete, missing the target path, or older than relevant local changes, use
-focused source reads as proof and record the reduced retrieval confidence.
+confirmed against source — see `references/codebase-investigation.md`
+§Source Order for the canonical statement of that rule.
 
 ## Common MCP Calls
 

package/skills/massa-ai/references/mobile-figma-matcher/repository-detection.md

@@ -25,7 +25,19 @@ Excluded Surfaces: <found but out of scope, with reason>
 2. Locate candidate modules using build configuration, manifests/projects, source sets, and ownership boundaries.
 3. Classify each target surface using at least one build/configuration signal and one source/resource signal when available.
 4. Map each selected surface to its Figma node. A single node may map to several surfaces; separate platform frames require explicit mappings.
-5. Load only the references required by selected surface IDs.
+5. Load only the Matcher Contracts references required by selected surface IDs.
+
+## Matcher Contracts
+
+Load only the contract file for each classified surface:
+
+- Android Views XML -> `references/mobile-figma-matcher/android-views.md`.
+- Android Jetpack Compose -> `references/mobile-figma-matcher/android-compose.md`.
+- iOS UIKit -> `references/mobile-figma-matcher/ios-uikit.md`.
+- iOS SwiftUI -> `references/mobile-figma-matcher/ios-swiftui.md`.
+- Shared KMP Compose Multiplatform -> `references/mobile-figma-matcher/kmp-compose-multiplatform.md`
+  plus native contracts only for selected native source sets, hosts,
+  wrappers, or runtime targets.
 
 ## Stack Signals
 

package/skills/massa-ai/references/pr-task-fix.md

@@ -12,24 +12,16 @@ Use ADR/TDD input as implementation context, not as permission to bypass the act
 
 ## PR Task Grouping
 
-Decompose work into reviewable PR groups before editing. Reuse the TDD task-planning contract:
-
-- Prefer Small PRs: `1-200 LOC / 1-3 files`, with a practical sweet spot under `50-100 LOC`.
-- Use Medium PRs: `201-500 LOC / 3-10 files` only when splitting further would break buildability, testability, UI coherence, or implementation dependency order.
-- Treat Large PRs: `500+ LOC / 10+ files` as exceptions requiring a split, stacked PR, feature-flag, or containment rationale before execution.
+Decompose work into reviewable PR groups before editing. Reuse the TDD
+task-planning contract in `references/create-tdd/document-contract.md`
+§Implementation Task Table for the PR-size bands (Small/Medium/Large) and the
+layer order (Data, then Domain, then Presentation/Navigation, mapped to
+repository terms when boundaries differ).
 
 Every PR group must be independently buildable and testable. It must not leave an intermediate state that breaks tests, UI, migrations, public contracts, required runtime behavior, or the active workflow's verification recipe.
 
 If a group is too large, split it into two or more groups. If tasks are too small, merge related small work only when the merged group remains independent, reviewable, buildable, and testable.
 
-Order non-breaking groups by layer when applicable:
-
-1. `Data`: DTOs, DAOs, data sources, repositories, analytics, persistence, and data-layer interfaces.
-2. `Domain`: use cases, models, mappers, configs, exceptions, monitoring, and business rules.
-3. `Presentation/Navigation`: screens, views, view models, actions, states, routes, and navigation.
-
-When the target project uses different boundaries, map these labels to the closest repository terms and state the mapping before execution.
-
 ## Commit Per Group
 
 For each PR group:

package/skills/massa-ai/references/spec-driven/code-analysis.md

@@ -6,13 +6,16 @@ Use when Specify, Design, Tasks, Execute, or Validate needs source inspection or
 
 ## Tool Priority
 
-Use graceful degradation, starting from massa-ai indexed tooling and falling back to structural, then text, search:
-
-1. `list_projects` (or equivalent index metadata) before indexed reads, to verify project ID, path, status, and freshness.
-2. `search` (or indexed symbol reads) when available and fresh for the current repository path and worktree state. Prefer `search_definitions`, `get_references`, or `optimized_context` for symbol- and reference-shaped queries.
-3. `sg` / ast-grep for structural pattern-based search when installed.
-4. `rg` (ripgrep) for fast context-aware text and file search.
-5. `grep` or direct file reads as the final, always-available fallback.
+Use graceful degradation: base retrieval sequence is
+`references/codebase-investigation.md` §Source Order — that file owns the
+ordered list; do not restate it here. Prefer `search_definitions`,
+`get_references`, or `optimized_context` for symbol- and reference-shaped
+queries within that sequence.
+
+Spec-driven code analysis adds one tier between semantic/symbol search and
+the shell fallback: try `sg` / ast-grep for structural pattern-based search
+when installed, then fall back to `rg` (ripgrep), then `grep` or direct file
+reads as the final, always-available fallback.
 
 ## Freshness And Source Precedence
 

package/skills/massa-ai/references/spec-driven/coding-principles.md

@@ -4,6 +4,11 @@ Use before writing or changing implementation, tests, fixtures, validation asset
 
 Behavioral bias, not checklist. Read before every implementation.
 
+General coding behavior — thinking before coding, simplicity, surgical
+changes, and goal-driven execution — is owned by `references/coding-guidelines.md`
+§1-4; read it before every implementation. This file keeps only what is
+unique to spec-driven Execute.
+
 ---
 
 ## Pre-Implementation Statement
@@ -18,34 +23,16 @@ Artifact-store evidence: active artifact key, version, and checksum after write
 
 ---
 
-## Before Coding
-
-- State assumptions explicitly. If uncertain, ask.
-- Multiple interpretations exist? Present all—don't pick silently.
-- Simpler approach exists? Say so. Push back when warranted.
-- Something unclear? Stop. Name what's confusing. Ask.
-- User's approach seems wrong? Disagree honestly. Don't be sycophantic.
-
----
-
-## During Implementation
-
-### Simplicity
-
-- No features beyond what was asked
-- No abstractions for single-use code
-- No "flexibility" or "configurability" not requested
-- No error handling for impossible scenarios
-- 200 lines that could be 50? Rewrite it.
+## Spec-Driven Rules
 
-### Surgical Changes
+Content here has no equivalent in `references/coding-guidelines.md` — general
+before-coding, simplicity, surgical-changes, and goal-driven guidance lives
+there instead.
 
-- Don't "improve" adjacent code, comments, or formatting
-- Don't refactor things that aren't broken
-- Match existing style, even if you'd do differently
-- Unrelated dead code noticed? Mention it—don't delete it
-- Remove ONLY imports/variables/functions YOUR changes orphaned
-- Don't remove pre-existing dead code unless asked
+- Implement the simplest complete change that satisfies the approved requirement.
+- Touch only listed files unless a new requirement or design decision forces a return to Specify or Design.
+- Derive tests from acceptance criteria and spec-defined outcomes, not from current implementation.
+- Re-run the task gate after any code or validation-asset change.
 
 ### Test Integrity
 
@@ -53,32 +40,10 @@ Artifact-store evidence: active artifact key, version, and checksum after write
 - NEVER delete a test to reduce failure count
 - NEVER use the test framework's skip/disable/pending mechanism to bypass a failing test
 - NEVER modify a task's tests afterward to make the implementation pass
+- Do not weaken tests, specs, fixtures, snapshots, schemas, or checks to make work pass.
 - If a test is genuinely wrong, STOP and confirm with the user before changing it
 - Tests are the spec — implementation conforms to tests, not the other way around
 
-### Goal-Driven
-
-- Transform vague tasks into verifiable goals
-- Multi-step work? State brief plan with verify checkpoints
-- Every changed line must trace directly to user's request
-
-### Rules
-
-- Implement the simplest complete change that satisfies the approved requirement.
-- Touch only listed files unless a new requirement or design decision forces a return to Specify or Design.
-- Match existing style and local helpers.
-- Do not add speculative flexibility, broad refactors, or unrelated cleanup.
-- Do not weaken tests, specs, fixtures, snapshots, schemas, or checks to make work pass.
-- Derive tests from acceptance criteria and spec-defined outcomes, not from current implementation.
-- Re-run the task gate after any code or validation-asset change.
-
----
-
-## After Each Change
-
-Ask: "Would senior engineer call this overcomplicated?"
-If yes → simplify before proceeding.
-
 ---
 
 ## Writing Voice (specs, ADRs, reports, commits, summaries)

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

@@ -2,24 +2,15 @@
 
 Use when recording decisions, progress, blockers, handoff, or completion evidence for a spec-driven feature.
 
-This memory layer is split across two artifacts with distinct lifecycles. Each has its own write triggers; writes are always section-scoped — never whole-file overwrites.
-
-- `.specs/project/STATE.md` owns project-level **Decisions** (append-only) plus current objective, progress, blockers, verification evidence, changed files, and exact next step.
-- `.specs/HANDOFF.md` owns the local **Handoff** snapshot (replace-on-pause).
-- `.specs/project/FEATURES.json` owns the feature registry: `active_feature`, status, dependencies, and completion evidence.
-- `.specs/features/<slug>/` owns approved feature artifacts.
-- Use `references/spec-driven/artifact-store.md` for artifact read/write operations.
+This memory layer is split across two artifacts with distinct lifecycles (see Artifact State below). Each has its own write triggers; writes are always section-scoped — never whole-file overwrites. Use `references/spec-driven/artifact-store.md` for artifact read/write operations.
 
 ## STATE Precedence Chain
 
-When sources conflict, resolve in this strict order — first match wins, lower sources never override higher:
-
-1. **Fresh user instruction** — the live user's explicit direction for the current decision.
-2. **Approved `.specs/` artifact** — the current `spec.md`/`design.md`/`tasks.md` approved for the active feature.
-3. **STATE / HANDOFF** — `.specs/project/STATE.md` and `.specs/HANDOFF.md` position and decision logs.
-4. **massa-ai memory** — durable cross-session recall; context until confirmed against current source.
-
-massa-ai memory and external summaries are discovery, not authority. If a higher source is silent, the next source decides; if a lower source contradicts a higher one, the higher source wins and the lower one is corrected. Record the resolution in STATE so the chain stays auditable. `references/spec-driven/artifact-store.md` mirrors this chain for artifact reads.
+Canonical chain, ordering, and silent/contradicting-source resolution rules:
+`references/artifact-persistence.md` STATE Precedence Chain. For spec-driven,
+the "approved `.specs/` artifact" link is the current `spec.md`/`design.md`/
+`tasks.md` approved for the active feature, and the "STATE/HANDOFF" link is
+`.specs/project/STATE.md` and `.specs/HANDOFF.md`.
 
 ---
 

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

@@ -503,7 +503,7 @@ When Tasks runs, always generate these sections before listing implementation ta
 
 Before sampling tests manually, prefer massa-ai tooling to read the codebase:
 
-1. **Code analysis priority.** Run `list_projects`, then `project_map` and `search` / `optimized_context` to discover test files, test config, and layer structure BEFORE falling back to `ast-grep` / `rg` / `grep`. If the index is stale or missing, current source always overrides the index or a stored memory; reindex only when freshness blocks the decision.
+1. **Code analysis priority.** Discover test files, test config, and layer structure through the massa-ai index first, in the order of `references/codebase-investigation.md` §Source Order (plus the `ast-grep` tier in `references/spec-driven/code-analysis.md` §Tool Priority), BEFORE falling back to `ast-grep` / `rg` / `grep`. If the index is stale or missing, current source always overrides the index or a stored memory; reindex only when freshness blocks the decision.
 2. **Durable memory.** Tag confirmed planning artifacts with `remember` using `project:<id>`, `session:<id>`, `workflow:spec-driven`, `entity:<slug>`, and `memory:working|episodic|semantic|procedural`.
 3. **Validation: evidence-or-zero.** Every coverage claim and gate command must be confirmed against current source. No evidence → no claim.
 

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

@@ -164,7 +164,7 @@ For mobile or UI features, follow the [references/mobile-context.md](../mobile-c
 
 For each issue found during UAT or from the Verifier:
 
-1. **Diagnose** — Analyze the codebase to find root cause. Prefer massa-ai code-analysis tools first (search, optimized_context) for symbol and dependency location; fall back to ast-grep/rg/grep when the index is stale or unavailable. Current source overrides stale index/memory.
+1. **Diagnose** — Analyze the codebase to find root cause, following `references/spec-driven/code-analysis.md` §Tool Priority for search order. Current source overrides stale index/memory.
 2. **Create fix task** — Write a task definition with:
    - What: The specific fix
    - Where: File paths
@@ -187,7 +187,7 @@ After all checks complete, the Verifier MUST:
 
 ### 10. Distill Lessons (MANDATORY when validation.md has signal)
 
-This is the closing action of validation — not a separate phase. Immediately after the report is written, turn its grounded failures into reusable, project-local guidance by following [references/lessons.md](../lessons.md) and the stub at [references/spec-driven/lessons.md](lessons.md). In short: for each surviving mutant, spec-precision gap, failed/uncovered AC, or `// SPEC_DEVIATION`, record one terse general lesson via:
+This is the closing action of validation — not a separate phase. Immediately after the report is written, turn its grounded failures into reusable, project-local guidance by following [references/lessons.md](../lessons.md). In short: for each surviving mutant, spec-precision gap, failed/uncovered AC, or `// SPEC_DEVIATION`, record one terse general lesson via:
 
 ```bash
 bun skills/massa-ai/scripts/lessons.ts --root . add --feature <slug> --signal "<signal>" --source "<source>" --text "<lesson>" --scope "<scope>"

package/skills/massa-ai/references/synapse-policy.md

@@ -23,11 +23,10 @@ resumed handoff reuses `workflowSessionId` and opens a fresh Synapse session.
 - Major focus shift: update task context through REST when available; otherwise
   create a fresh Synapse session and let the prior session expire.
 
-Default search budget inside a Synapse session:
+Default search budget inside a Synapse session follows
+`references/mcp-tools.md` §Retrieval Order; this file does not restate the
+numbers.
 
-- Summary discovery: `responseMode="summary"`, `maxResults=10`.
-- Targeted deep reads: `responseMode="enriched"`, `maxResults=3`.
-- Expanded deep reads: `maxResults=5` only when 4-5 exact files, symbols, or report finding IDs are already named.
 - Do not use Synapse for a single recall, project map, exact file read, or one symbol lookup.
 
 Server-side bounds that constrain the budget:

package/skills/massa-ai/workflows/create-adr.md

@@ -32,7 +32,7 @@ Load `references/project-context.md` (intake sweep) before the first substantive
    - If an RFC is needed but absent and the user does not know the missing context, assume the decision is not made and route to `workflows/create-rfc.md`.
    - Require a source-backed or user-confirmed title, date, status, context, decision, consequences, links, and supersession status before drafting.
 6. Draft the ADR using the project's template when available; otherwise use the format selected via `references/create-adr.md`'s fallback questions. Tie claims to source confidence: confirmed, user-provided, recalled, inferred, or unresolved.
-7. Run the configured Plan Challenge Gate before saving. ADR decisions require the full gate under the default policy (`create-adr` is named in the full-gate set of the canonical Plan Challenge Policy); revise valid critical or high findings before the record is written, especially a decision presented without its rejected alternatives, consequences stated only as benefits, an unstated assumption the decision depends on, and status quo or sunk-cost bias in the framing. A challenge that invalidates the decision means the decision is not final — route to `workflows/create-rfc.md` rather than recording it.
+7. Run the Plan Challenge Gate before saving. ADR decisions require the full gate (`create-adr` is in the full-gate set of `SKILL.md` §Plan Challenge Gate); revise valid critical or high findings before the record is written, especially a decision presented without its rejected alternatives, consequences stated only as benefits, an unstated assumption the decision depends on, and status quo or sunk-cost bias in the framing. A challenge that invalidates the decision means the decision is not final — route to `workflows/create-rfc.md` rather than recording it.
 8. Save the generated ADR using the selected output target:
    - Default: write to the project's standard ADR directory in Default mode. In Plan Mode, propose the path and content without writing.
    - Confluence: when requested and a parent page link is provided, write a child page through Atlassian MCP and report the resulting page link.

package/skills/massa-ai/workflows/create-rfc.md

@@ -34,7 +34,7 @@ Load `references/project-context.md` (intake sweep) before the first substantive
 6. Choose the artifact path from an explicit user path or established project convention. Otherwise default to `docs/rfc/<entity>.md`.
    - If the target exists, update it only when the user explicitly requested an update; otherwise ask before overwriting.
    - When file mutation is unavailable or the user requested plan-only output, present the complete draft and intended path without writing.
-7. Run the full configured Plan Challenge Gate. Preserve all required RFC fields while revising valid critical or high findings, especially one-sided options, unsupported claims, hidden assumptions, status quo bias, weak cost estimates, and criteria chosen to justify a predetermined conclusion.
+7. Run the full Plan Challenge Gate. Preserve all required RFC fields while revising valid critical or high findings, especially one-sided options, unsupported claims, hidden assumptions, status quo bias, weak cost estimates, and criteria chosen to justify a predetermined conclusion.
 8. Load `references/create-rfc/quality-and-lifecycle.md`, validate every required behavior, and resolve blocking gaps. Keep unresolved facts explicit instead of silently removing mandatory fields.
 9. Save the proposal with status `NOT STARTED` or `IN PROGRESS`. Set `COMPLETE` and fill the Outcome section only when an explicit human decision or authoritative project record is available.
 10. Persist proposal state after recall, deduplication, and scoring:

package/skills/massa-ai/workflows/create-tdd.md

@@ -48,7 +48,7 @@ Load `references/project-context.md` (intake sweep) before the first substantive
 6. Choose the artifact path from an explicit user path or an existing project convention. Otherwise default to `docs/design/<entity>.md`.
    - If the target exists, treat the request as an update only when the user explicitly requested one; otherwise ask before overwriting it.
    - When file mutation is unavailable or the user requested plan-only output, present the complete draft and intended path without writing.
-7. Run the configured Plan Challenge Gate. TDD plans require the full gate under the default policy; revise valid critical or high findings before finalization.
+7. Run the Plan Challenge Gate. TDD plans require the full gate; revise valid critical or high findings before finalization.
 8. Load `references/create-tdd/quality-and-lifecycle.md`, validate the document, and resolve blocking gaps. Keep non-blocking unknowns explicit with owners or decision points when known.
 9. If the implementation task table is stable and validated, discover whether Atlassian MCP has readable Jira project metadata and issue-creation capability.
    - If Atlassian MCP is unavailable or read-only, leave the table's `Jira Key` values as `Unavailable` and report that ticket creation was skipped.

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

@@ -24,7 +24,7 @@ Not for Flutter, React Native, web UI, generic Figma exploration, variable-only
 2. Load `references/mobile-figma-matcher/repository-detection.md`, `references/mobile-figma-matcher/core.md`, `references/mobile-context.md`, `references/codebase-investigation.md`, `references/verification-ladder.md`, and `references/naming-standards.md` (before introducing or renaming identifiers, screens, components, attributes, or implementation-facing names — English-conversion rule applies). When Figma links or node IDs are provided, load `references/figma-pre-analysis.md` and run its two-stage sequential retrieval protocol before building the Figma Evidence Packet. Load `references/context-firewall.md` before large design/runtime artifacts and `references/synapse-policy.md` when repeated massa-ai searches are expected.
 3. `recall` -> load current component conventions, design-system rules, approved platform/accessibility deviations, prior Figma mappings, asset pipelines, and reusable render recipes. Memory is context, not proof.
 4. Require a concrete feature/module target plus at least one design source: readable Figma node/selection or supplied screenshots. Resolve required visual and interactive states plus a requirements source for behavior not represented in the design source. Ask whenever target ownership, runtime platforms, platform-frame mappings, screenshot authority, or any other important decision remains ambiguous or in doubt after source inspection.
-5. Follow `references/design-implementation.md` for the Target Surface Packet, the Figma Evidence / Screenshot Context Packet, the Design-To-Code Mapping Matrix, sizing and the verification recipe, coherent-slice implementation rules, per-slice verification, completion criteria, and the completion report — the single normative copy of this direction set, shared with `spec-driven`/`feature` under Figma ingestion.
+5. Follow `references/design-implementation.md` for the Target Surface Packet, the Figma Evidence / Screenshot Context Packet, the Design-To-Code Mapping Matrix, sizing and the verification recipe, coherent-slice implementation rules, per-slice verification, completion criteria, and the completion report — the single normative copy of this direction set, shared with `spec-driven`/`feature` under Figma ingestion. Once the Design-To-Code Mapping Matrix exists and before the first edit or `designer` dispatch, run the full Plan Challenge Gate (`SKILL.md` §Plan Challenge Gate) on the slice plan.
 6. Persist only durable token/component mappings, approved deviations, source-set ownership rules, asset-pipeline rules, or reusable render recipes after Importance Calibration. Use `workflow:design` and required project/session/entity/memory tags.
 7. Complete `references/evidence-gate.md`. Model visual judgment alone cannot satisfy completion.
 

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

@@ -58,14 +58,12 @@ When researching or resolving any technical question during exploration, follow
 > - scope: the exploration target — symbols, files, routes, commands, docs, or runtime artifacts to inspect
 > - permissions: read-only
 > - inputs: objective, scope, explicit out-of-scope areas, constraints, recalled facts, and the closest entry point
-> - sensors: progressive disclosure (project map → summary search → enriched search → symbol/file tools → optimized context → focused shell); per-step `verify:` criterion
+> - sensors: retrieval order per `references/codebase-investigation.md` §Source Order; per-step `verify:` criterion
 > - output: entry points, core flow, dependencies, data ownership, relevant contracts, exact evidence pointers (path, symbol, line), confirmed facts vs inferences
 > - firewall: raw logs, snapshots, generated reports, and broad search output summarized, not returned raw
 > - memory: suggest-only; main agent persists durable discoveries
 
-    - Follow the shared retrieval order: project map, summary search, targeted
-      enriched search, symbol/file tools, optimized context, then focused shell
-      fallback.
+    - Follow the shared retrieval order in `references/codebase-investigation.md` §Source Order.
    - When external documentation, API references, or web content is needed to answer the question, call `fetch_and_index` with `url` (or `requests`[]) to fetch, convert HTML→markdown or extract JSON key-paths, and index the result into the searchable store so it can be retrieved later via `search`. SSRF-guarded, TTL-cached.
    - Follow imports, calls, ownership boundaries, and data paths from entry point outward.
    - For behavior questions, trace input -> transformation -> output.

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

@@ -87,7 +87,7 @@ Before the first repository mutation, load `references/implementation-delivery.m
 
 - The fix→re-verify cycle for a PR group is capped by the Bounded Fix→Re-verify Loop's 3-iteration limit in `references/verification-ladder.md` (cap reached → `Blocked`).
 
-13. Run the configured Plan Challenge Gate on the refactor plan before the first behavior-preserving edit. Low-risk refactor plans use the Plan Challenge lite gate first; full The Fool is reserved for explicit challenge, high-risk domains, plans touching more than 5 files/classes/modules, or lite escalation. Revise valid critical or high findings — for a refactor the assumption most worth challenging is that the existing tests actually pin the behavior being preserved.
+13. Run the Plan Challenge Gate on the refactor plan before the first behavior-preserving edit. Low-risk refactor plans use the Plan Challenge lite gate first; full The Fool is reserved for explicit challenge, high-risk domains, plans touching more than 5 files/classes/modules, or lite escalation. Revise valid critical or high findings — for a refactor the assumption most worth challenging is that the existing tests actually pin the behavior being preserved.
 14. Complete the Evidence Gate from `references/evidence-gate.md`
 
 ## Failure Handling

package/skills/massa-ai/workflows/refinement/furps-refinement.md

@@ -21,7 +21,7 @@ Findings-only: do not edit the PRD/ADR unless the user separately asks.
    - `references/furps/intake.md` before intake and sub-agent dispatch
    - `references/furps/checklist.md` for the per-dimension check items
    - `references/furps/report-contract.md` before writing the report
-   - `references/furps/analyst-role.md` and `skills/agents/product-manager/SKILL.md` before dispatching `product-manager` in `furps` mode
+   - `skills/agents/product-manager/SKILL.md` before dispatching `product-manager` in `furps` mode
    - `references/agent-orchestration.md` and `references/context-firewall.md` before dispatch
    - `references/audit-report-io.md` before writing the final report
    - `references/synapse-policy.md` when repeated massa-ai searches are expected

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

@@ -156,7 +156,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
    - Distill lesson signals through `references/lessons.md` when validation produces grounded reusable failures.
 7. Before the delivery chain's Propose stage (PR creation), write and commit `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `.specs/project/FEATURES.json` on the branch — not merely "after meaningful progress" during Execute, but committed before `gh pr create`. **Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/check_specs_delivered.ts <feature> [--root .]` — a non-zero exit blocks Propose (see `references/implementation-delivery.md` stage 3.5 and GATE-02). If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved). Record decisions, blockers, handoff, and completion evidence per `references/spec-driven/memory.md`'s write triggers.
 8. When the user splits planning and implementation across clean chats, resume from the canonical `.specs/` artifacts — `.specs/project/STATE.md`, `.specs/project/FEATURES.json`, `.specs/HANDOFF.md`, and the feature's phase files. This workflow owns the spec phase contracts on both sides of the split; there is no separate save/load procedure.
-9. Complete the configured Plan Challenge Gate for non-trivial plans and complete `references/evidence-gate.md` before claiming completion.
+9. Complete the Plan Challenge Gate for non-trivial plans and complete `references/evidence-gate.md` before claiming completion.
 
 ## Artifact Ownership
 
@@ -210,8 +210,8 @@ Memory:
 | Record decision, project-level decision | `references/spec-driven/memory.md` |
 | Pause work, end session, I need to stop | `references/spec-driven/memory.md` |
 | Resume work, continue, pick up where we left off | `references/spec-driven/memory.md` |
-| Load lessons, what have we learned, apply past lessons | `references/spec-driven/lessons.md` |
-| Record lesson, distill lessons (auto-runs after validation) | `references/spec-driven/lessons.md` |
+| Load lessons, what have we learned, apply past lessons | `references/lessons.md` |
+| Record lesson, distill lessons (auto-runs after validation) | `references/lessons.md` |
 
 ## Output Behavior
 

package/skills/massa-ai/workflows/the-fool.md

@@ -1,6 +1,6 @@
 ---
 name: the-fool
-description: "Use this workflow for direct requests to challenge ideas, plans, decisions, or evidence, and as the configured post-plan challenge gate after other workflows construct a plan."
+description: "Use this workflow for direct requests to challenge ideas, plans, decisions, or evidence, and as the post-plan challenge gate after other workflows construct a plan."
 license: MIT
 metadata:
   version: "1.1.0"
@@ -8,7 +8,7 @@ metadata:
 
 ### The Fool
 
-Use for direct requests to challenge ideas, plans, decisions, proposals, architectures, evidence, or assumptions. Also use as the configured post-plan challenge gate after other massa-ai workflows construct a plan.
+Use for direct requests to challenge ideas, plans, decisions, proposals, architectures, evidence, or assumptions. Also use as the post-plan challenge gate after other massa-ai workflows construct a plan.
 
 Load `references/project-context.md` (intake sweep) before the first substantive read.
 
@@ -16,12 +16,13 @@ Not to build the initial plan, make the decision, or execute implementation work
 
 ## Configuration
 
-Read the canonical **Plan Challenge Policy** from the installed `AGENTS.md`
-bootstrap block (`<!-- massa-ai:bootstrap -->`), whose single source is
-`skills/AGENTS.md` in the product repo. If that
-file is unavailable, use the deterministic runtime fallback: run the lite gate
-with `pre_mortem` mode (do not judgment-select the gate or mode), and revise
-the parent plan when critical or high findings are valid.
+The gate is fixed behavior, defined once in `SKILL.md` §Plan Challenge Gate
+(which workflows run lite or full, and what escalates). There is no policy file
+to read: the mode is always auto-selected, and valid `critical` or `high`
+findings always revise the parent plan. The gate runs where a workflow carries a
+Plan Challenge step — the workflows named in those Lite and Full bullets; the
+risk and size triggers escalate a plan inside them to full, and a direct
+challenge request runs it anywhere.
 
 User prompt overrides take precedence for the current turn only, such as "skip the Fool gate", "use red-team mode", or "append critique without revising the plan".
 
@@ -34,18 +35,17 @@ User prompt overrides take precedence for the current turn only, such as "skip t
 2. `recall` -> load prior decisions, rejected approaches, constraints, accepted risks, and relevant evidence for the target entity.
 3. Require a concrete proposed plan before critique. If there is no plan, return to the parent workflow and construct the plan first. After a concrete plan exists, always attempt a `judge` subagent in `plan-critique` mode (it writes nothing in that mode) when subagent tooling is available. If that agent is unavailable, follow the no-agent fallback in `references/agent-orchestration.md` (Name Resolution): run the critique locally against the same output contract and report the skipped delegation.
 4. Resolve gate depth:
-   - Post-plan lite gate: keep parent identifiers and dispatch a bounded lite checklist packet without loading The Fool mode references.
+   - Post-plan lite gate: keep parent identifiers and dispatch the bounded packet the Lite bullet of `SKILL.md` §Plan Challenge Gate defines, without loading The Fool mode references.
    - Post-plan full gate or direct challenge: continue to mode selection and full critique.
    - Direct challenge requests use `workflowSessionId=fool-[entity]`; post-plan gates keep the parent identifiers and send only a bounded packet.
 5. Lite `judge` `plan-critique` packet:
-   - Inputs: proposed plan, scope, constraints, parent workflow, compact recalled facts/evidence, known risks, verification recipe, context-firewall limits, and lite checklist.
+   - Inputs: proposed plan, scope, constraints, parent workflow, compact recalled facts/evidence, known risks, verification recipe, context-firewall limits, and that Lite bullet's checklist (failing assumption, falsifying check, risk/size check).
    - Output must include the strongest low-risk challenges plus `escalate_to_full: true|false` and reason.
-   - If `escalate_to_full: false`, synthesize the lite critique, revise or accept risk according to policy, and complete the gate without loading The Fool mode references.
+   - If `escalate_to_full: false`, synthesize the lite critique, revise the plan for each challenge judged valid or record the accepted risk, and complete the gate without loading The Fool mode references.
    - If `escalate_to_full: true`, the main agent selects full mode, loads the relevant references, and dispatches a full `judge` `plan-critique` pass.
 6. Select The Fool mode for full gates:
-   - `mode: auto`: read `references/the-fool/mode-selection-guide.md` and choose the best mode from plan content and domain.
-   - `mode: ask`: ask the user only when interactive input is available; otherwise fall back to `auto` and report the fallback.
-   - Concrete mode values map to The Fool references: `pre_mortem`, `red_team`, `evidence_audit`, `socratic`, or `dialectic`.
+   - Read `references/the-fool/mode-selection-guide.md` and choose the best mode from plan content and domain, unless the user named a mode for this turn.
+   - Mode values map to The Fool references: `pre_mortem`, `red_team`, `evidence_audit`, `socratic`, or `dialectic`.
    - Mode reference map:
      - `pre_mortem` -> `references/the-fool/pre-mortem-analysis.md`
      - `red_team` -> `references/the-fool/red-team-adversarial.md`
@@ -69,10 +69,7 @@ User prompt overrides take precedence for the current turn only, such as "skip t
    - required revision or accepted-risk framing
    - confidence impact
    - exact next step
-10. Synthesize using `references/decision-engine.md`:
-   - `serious_findings: revise_plan`: revise valid `critical` or `high` findings before presenting the final plan.
-   - `serious_findings: append_critique`: keep the plan and attach the critique for user decision.
-   - `serious_findings: warn_only`: mention serious risks briefly without restructuring the plan.
+10. Synthesize using `references/decision-engine.md`: revise valid `critical` or `high` findings before presenting the final plan. Only a user override for the current turn keeps the plan unchanged and attaches the critique for user decision instead.
 11. Persist only durable outcomes after recall and scoring:
    - accepted architecture constraints, rejected approaches, durable risk decisions, or reusable critique patterns
    - required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:the-fool` or parent workflow for post-plan gates, `entity:<entity>`, and one `memory:<tier>`
@@ -87,4 +84,4 @@ When used as a gate, the final user-facing plan should not expose raw subagent c
 Plan Challenge: ran The Fool in pre-mortem mode; revised verification and rollout risks before finalizing.
 ```
 
-If the gate is skipped, state why only when it affects confidence, user expectation, or configured behavior.
+If the gate is skipped, state why only when it affects confidence or user expectation.

package/skills/massa-ai/references/furps/analyst-role.md

@@ -1,49 +0,0 @@
-# Role: product-manager (`furps` mode)
-
-Reusable sub-agent role for `workflows/refinement/furps-refinement.md`. Charter follows `references/subagent-design.md`. Registered in `references/agent-orchestration.md`.
-
-Purpose: analyze exactly one FURPS+ dimension (F, U, R, P, S, or X) of a PRD/ADR against its checklist section, returning structured refinement findings.
-
-Trigger description:
-- Use when the `furps-refinement` workflow fans out per-dimension analysis and needs isolated context plus independent verification per dimension.
-- Do not use when the work is a one-off local check, needs full conversation history, requires writes, or overlaps another role (use `judge` in `plan-critique` mode for The Fool, `code-explorer`/`code-reviewer` for code claims).
-
-Permissions:
-- Default: read-only.
-- No write access. No Atlassian mutation. No memory writes — suggest only.
-
-Context inputs:
-- exact `projectId`
-- exact parent `workflowSessionId` and a child session tag; an ephemeral Synapse session only if the role performs >=2 `search` calls
-- workflow name (`furps-refinement`) and role name (`product-manager`, `mode: furps`)
-- assigned dimension letter and its `references/furps/checklist.md` section
-- bounded document packet (sections/summaries, DoR, recalled facts, Fool summary)
-- exclusions: other dimensions (flag, do not expand), sibling-workflow targets
-- allowed tools: read-only file, read-only MCP, `search`
-- context-firewall limits: summarize the document; return evidence/findings only
-
-Process:
-1. Confirm the assigned dimension and refusal conditions (do not analyze other dimensions; do not write files).
-2. For each check item in the dimension's section, locate evidence in the document (quote plus section) or confirm absence.
-3. Assign status: `covered` | `partial` | `missing` | `unclear`.
-4. Produce `FR-<letter>-<N>` findings for every `missing`/`unclear` item and for `partial` items when the gap is non-trivial.
-5. Tag each finding's contribution to Open Questions / Suggestions / Insights / Risks / DoR-gaps.
-6. Return compact findings — no raw document dumps.
-
-Output contract:
-- Status: Complete | Partial | Blocked
-- Scope checked: dimension plus check items evaluated
-- Evidence: quotes/section IDs per check item
-- Findings: `FR-<letter>-<N>` with severity, confidence, status, impact, simplest fix direction, verification suggestion
-- Contributions: open questions / suggestions / insights / risks / DoR-gaps
-- Risks and skipped checks
-- Exact next step
-
-Validation sensors:
-- source-location proof (quote plus section) for every `covered`/`partial` claim
-- absent-claim detection for every `missing` claim
-- no self-evaluation: every finding ties to a concrete check item and document evidence
-
-Memory boundary:
-- Suggest durable memories only when a reusable refinement pattern is discovered.
-- Do not persist broad project memory. The main agent persists after synthesis.