@massa-ai/claude-plugin 1.63.1 → 1.64.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "massa-ai",
-  "version": "1.63.1",
+  "version": "1.64.0",
   "description": "massa-ai — semantic code search, durable memory, symbol graph, and context compression",
   "author": {
     "name": "Luiz Massa",

package/agent-profiles/balanced/code-explorer.md

@@ -72,7 +72,7 @@ Output:
 - The work is tightly coupled without a clear owner.
 
 ## massa-ai Integration
-- Retrieval order: `list_projects` freshness -> `project_map` -> `search(summary)` -> `search(enriched)` -> symbol tools -> `read_file` -> focused shell fallback.
+- Retrieval order: index-first. This charter inherits no other context, so read `references/codebase-investigation.md` §Source Order in full rather than assume the sequence.
 - Freshness gating: `project_map`, `get_architecture`, `trace_path`, and `impact_analysis` count as evidence only when the index is fresh for the current path and commit/worktree state; otherwise fall back to `search`/`get_references` and record reduced retrieval confidence.
 - 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, logs, and source reads; return only `path:line` pointers and findings.

package/agent-profiles/cheap/code-explorer.md

@@ -72,7 +72,7 @@ Output:
 - The work is tightly coupled without a clear owner.
 
 ## massa-ai Integration
-- Retrieval order: `list_projects` freshness -> `project_map` -> `search(summary)` -> `search(enriched)` -> symbol tools -> `read_file` -> focused shell fallback.
+- Retrieval order: index-first. This charter inherits no other context, so read `references/codebase-investigation.md` §Source Order in full rather than assume the sequence.
 - Freshness gating: `project_map`, `get_architecture`, `trace_path`, and `impact_analysis` count as evidence only when the index is fresh for the current path and commit/worktree state; otherwise fall back to `search`/`get_references` and record reduced retrieval confidence.
 - 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, logs, and source reads; return only `path:line` pointers and findings.

package/agent-profiles/heavy/code-explorer.md

@@ -72,7 +72,7 @@ Output:
 - The work is tightly coupled without a clear owner.
 
 ## massa-ai Integration
-- Retrieval order: `list_projects` freshness -> `project_map` -> `search(summary)` -> `search(enriched)` -> symbol tools -> `read_file` -> focused shell fallback.
+- Retrieval order: index-first. This charter inherits no other context, so read `references/codebase-investigation.md` §Source Order in full rather than assume the sequence.
 - Freshness gating: `project_map`, `get_architecture`, `trace_path`, and `impact_analysis` count as evidence only when the index is fresh for the current path and commit/worktree state; otherwise fall back to `search`/`get_references` and record reduced retrieval confidence.
 - 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, logs, and source reads; return only `path:line` pointers and findings.

package/agent-profiles/home/code-explorer.md

@@ -72,7 +72,7 @@ Output:
 - The work is tightly coupled without a clear owner.
 
 ## massa-ai Integration
-- Retrieval order: `list_projects` freshness -> `project_map` -> `search(summary)` -> `search(enriched)` -> symbol tools -> `read_file` -> focused shell fallback.
+- Retrieval order: index-first. This charter inherits no other context, so read `references/codebase-investigation.md` §Source Order in full rather than assume the sequence.
 - Freshness gating: `project_map`, `get_architecture`, `trace_path`, and `impact_analysis` count as evidence only when the index is fresh for the current path and commit/worktree state; otherwise fall back to `search`/`get_references` and record reduced retrieval confidence.
 - 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, logs, and source reads; return only `path:line` pointers and findings.

package/agent-profiles/work/code-explorer.md

@@ -72,7 +72,7 @@ Output:
 - The work is tightly coupled without a clear owner.
 
 ## massa-ai Integration
-- Retrieval order: `list_projects` freshness -> `project_map` -> `search(summary)` -> `search(enriched)` -> symbol tools -> `read_file` -> focused shell fallback.
+- Retrieval order: index-first. This charter inherits no other context, so read `references/codebase-investigation.md` §Source Order in full rather than assume the sequence.
 - Freshness gating: `project_map`, `get_architecture`, `trace_path`, and `impact_analysis` count as evidence only when the index is fresh for the current path and commit/worktree state; otherwise fall back to `search`/`get_references` and record reduced retrieval confidence.
 - 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, logs, and source reads; return only `path:line` pointers and findings.

package/agents/code-explorer.md

@@ -72,7 +72,7 @@ Output:
 - The work is tightly coupled without a clear owner.
 
 ## massa-ai Integration
-- Retrieval order: `list_projects` freshness -> `project_map` -> `search(summary)` -> `search(enriched)` -> symbol tools -> `read_file` -> focused shell fallback.
+- Retrieval order: index-first. This charter inherits no other context, so read `references/codebase-investigation.md` §Source Order in full rather than assume the sequence.
 - Freshness gating: `project_map`, `get_architecture`, `trace_path`, and `impact_analysis` count as evidence only when the index is fresh for the current path and commit/worktree state; otherwise fall back to `search`/`get_references` and record reduced retrieval confidence.
 - 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, logs, and source reads; return only `path:line` pointers and findings.

package/commands/the-fool.md

@@ -1,5 +1,5 @@
 ---
-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. — explicit massa-ai 'the-fool' workflow"
+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. — explicit massa-ai 'the-fool' workflow"
 argument-hint: "[task description]"
 ---
 <!-- massa-ai:generated workflow-command -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/claude-plugin",
-  "version": "1.63.1",
+  "version": "1.64.0",
   "description": "massa-ai plugin for Claude Code — semantic code search, durable memory, symbol graph, and context compression",
   "files": [
     "agents",

package/skills/agents/code-explorer/SKILL.md

@@ -74,7 +74,7 @@ Output:
 - The work is tightly coupled without a clear owner.
 
 ## massa-ai Integration
-- Retrieval order: `list_projects` freshness -> `project_map` -> `search(summary)` -> `search(enriched)` -> symbol tools -> `read_file` -> focused shell fallback.
+- Retrieval order: index-first. This charter inherits no other context, so read `references/codebase-investigation.md` §Source Order in full rather than assume the sequence.
 - Freshness gating: `project_map`, `get_architecture`, `trace_path`, and `impact_analysis` count as evidence only when the index is fresh for the current path and commit/worktree state; otherwise fall back to `search`/`get_references` and record reduced retrieval confidence.
 - 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, logs, and source reads; return only `path:line` pointers and findings.

package/skills/bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bootstrap
-description: Inspect or toggle the massa-ai startup-contract rules (caveman, massa-ai-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.
+description: Inspect or toggle the massa-ai startup-contract rules (massa-ai-router, dedupe-guardrails, 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
@@ -33,18 +33,18 @@ Run `bootstrap list` before any toggle, so the reported change is against a stat
 `--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 eight 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`.
+Exactly six 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.
 - `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 eight — relay that list rather than guessing what the user meant.
+`caveman` and `plan-challenge` were retired: the CLI refuses them as retired, and a persisted entry for one is skipped silently. The Plan Challenge gate itself still runs — it is fixed workflow behavior in the massa-ai router, no longer a toggle.
+
+Never invent an id. An unrecognised id is refused before anything is read or written, and the error names the id and lists all six — 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.
 
@@ -66,7 +66,7 @@ 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 eight ids above, exactly as the engine lists them.
+- Never invent, abbreviate, or pluralise a rule id; use only the six 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.

package/skills/massa-ai/SKILL.md

@@ -146,18 +146,19 @@ selected workflow asks for it.
 
 ## Plan Challenge Gate
 
-Apply the installed Plan Challenge Policy from `skills/AGENTS.md` (canonical
-source); prompt-level instructions override it for the current turn.
+A prompt-level instruction (skip, a mode, append without revising) overrides
+this for the current turn only.
 
-- **Lite** (default, low-risk `feature`/`refactor`): dispatch `judge` in `plan-critique` mode
-  (`references/agent-modes/judge/plan-critique-lite.md`) with a bounded checklist packet (failing
+- **Lite** (default: `feature`, `refactor`): dispatch `judge` in `plan-critique` mode
+  (`references/agent-modes/judge/plan-critique-lite.md`) with a bounded packet (failing
   assumption, falsifying check, risk/size check, `escalate_to_full:
   true|false` + reason); skip The Fool references unless it escalates.
-- **Full** (`spec-driven`, `design`, `create-adr`/`rfc`/`tdd`, explicit
-  challenge, high-risk domain, >5 files/modules, or lite escalation): load
-  `workflows/the-fool.md`, select the mode, dispatch `judge` in `plan-critique`
+- **Full** (`spec-driven`, `design`, `create-adr`, `create-rfc`, `create-tdd`, explicit
+  challenge, a rule-5 risk domain, security, data loss, >5 files/modules, or lite escalation): load
+  `workflows/the-fool.md`, auto-select the mode, dispatch `judge` in `plan-critique`
   mode (`references/agent-modes/judge/plan-critique-full.md`) with `fool_mode` in the packet.
-- If `judge` is unavailable, run a local fresh-eyes critique and report the
+- Revise the plan for each valid critical/high finding.
+- If `judge` is unavailable, critique locally and report the
   skipped reason; never retry under a different agent name.
 
 ## Retrieval And Synapse

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

@@ -164,14 +164,12 @@ resolves to a current agent.
 | `coupling-auditor` | `code-reviewer` | folded in; `mode: audit`, `lens: architecture`, `sub-mode: coupling` |
 | `deepening-architect` | `code-reviewer` | folded in; `mode: audit`, `lens: architecture`, `sub-mode: deepening` |
 
-The charter names retired by the roster consolidation map to current agents in the
-single old→new table of `skills/AGENTS.md`; this file does not repeat it. Workflows
-dispatch the current `<role>` name through a named dispatch block — the legacy column
-is traceability only, never a dispatch target.
+Workflows dispatch the current `<role>` name through a named dispatch block — the
+legacy column is traceability only, never a dispatch target.
 
 ## Capability Packet
 
-**This section is the sole canonical Capability Packet definition.** `references/subagent-design.md` mirrors this list and the root `skills/AGENTS.md` registry points here without restating it. Bespoke packets (judge panel, `product-manager` FURPS dispatch, phase-batch worker) are declared specializations that map onto these fields in their own workflow files.
+**This section is the sole canonical Capability Packet definition.** `references/subagent-design.md` and the root `skills/AGENTS.md` registry point here without restating it. Bespoke packets (judge panel, `product-manager` FURPS dispatch, phase-batch worker) are declared specializations that map onto these fields in their own workflow files.
 
 **A subagent inherits nothing from the parent session** — no skills, no loaded references, no conversation history. Everything the subagent needs is named explicitly in the packet, including the exact reference file paths it must read itself.
 
@@ -282,8 +280,8 @@ Do not expose raw subagent prompts, raw logs, private reasoning, or full output
 Example:
 
 ```md
-🤖 [Agent Started] Verifier is checking the docs-only change set. Scope: massa-ai references and README.
-🤖 [Agent Done] Verifier found no stale references. Skipped checks: none.
+🤖 [Agent Started] Code Reviewer (verify mode), model `<model>`, effort `<effort>`. Scope: massa-ai references and README.
+🤖 [Agent Done] Code Reviewer found no stale references. Skipped checks: none.
 ```
 
 ### Model/Effort Announcement
@@ -354,9 +352,8 @@ For `depth: full`, or after lite escalation, the main agent selects the The Fool
 - confidence impact
 - exact next step
 
-The main agent owns final synthesis and applies the canonical Plan Challenge
-Policy: the `<!-- massa-ai:bootstrap -->` block installed as `<host>/AGENTS.md`,
-whose single source is `skills/AGENTS.md` in the product repo.
+The main agent owns final synthesis and applies the fixed Plan Challenge Gate
+in `SKILL.md` §Plan Challenge Gate.
 
 ## Memory Rules
 

package/skills/massa-ai/references/architecture-lenses.md

@@ -47,27 +47,7 @@ Do not flag strong local coupling as bad when the modules change together and lo
 
 ## Deepening Lens
 
-Use these terms exactly:
-
-- Module: anything with an interface and implementation.
-- Interface: everything a caller must know, including invariants, ordering, errors, config, and performance.
-- Seam: where an interface lives.
-- Adapter: concrete thing satisfying an interface at a seam.
-- Depth: leverage at the interface.
-- Leverage: capability callers get per unit of interface learned.
-- Locality: change, bugs, and verification concentrated in one place.
-
-Load `references/architecture-deepening-lens.md` when the audit target includes shallow modules, pass-through abstractions, seams, adapters, tests that reach past interfaces, or AI-navigability concerns.
-
-Check:
-
-- shallow modules whose interface is nearly as complex as implementation
-- pass-through wrappers
-- seams with only one adapter and no actual variation
-- test-only extraction that loses locality
-- concepts split across many files without leverage
-
-Deletion test: full detail in `references/architecture-deepening-lens.md`.
+Load `references/architecture-deepening-lens.md` when the audit target includes shallow modules, pass-through abstractions, seams, adapters, tests that reach past interfaces, or AI-navigability concerns. That reference owns the vocabulary (Module, Interface, Seam, Adapter, Depth, Leverage, Locality), the Deepening Signals checklist, and the Deletion Test.
 
 Only recommend a new seam when variation, dependency direction, external I/O, or test substitution is real.
 

package/skills/massa-ai/references/artifact-persistence.md

@@ -13,6 +13,8 @@ Use before any workflow reads or writes durable `.specs/` artifacts. This file o
 
 Artifact reads resolve conflicts in this strict order (first match wins): fresh user instruction > approved `.specs/` artifact > STATE/HANDOFF > massa-ai memory. massa-ai memory and external summaries are discovery, not authority. In a repository with no `.specs/project/STATE.md`/`.specs/HANDOFF.md`, the chain simply has fewer links — the ordering is unchanged.
 
+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.
+
 ## Quick Artifact Templates
 
 Quick-sized tasks persist under `.specs/quick/NNN-slug/` — `NNN` zero-padded and sequential per project, `slug` the short kebab-case intent. Exactly two files:

package/skills/massa-ai/references/codebase-investigation.md

@@ -27,25 +27,45 @@ For exploration-only work, Recon and Debrief are the main deliverables.
 
 ## Source Order
 
+This is the single ordered retrieval list for massa-ai workflows and agents.
+Every other reference (`mcp-tools.md`, `spec-driven/code-analysis.md`,
+`synapse-policy.md`, workflow files, agent charters) points here instead of
+restating it; where a file adds tool-specific parameters, budgets, or a
+tier not listed below, it says so as an explicit delta on top of this order.
+
 Prefer sources in this order:
 
 1. `recall` for prior decisions, patterns, failed attempts, and handoffs.
 2. `list_projects` or equivalent index metadata to verify project ID,
-   path, status, and freshness.
-3. `project_map` for indexed-project architecture orientation when the
+   path, status, and freshness (`lastIndexedAt`).
+3. `project_map` for indexed-project general architecture orientation when the
    index is fresh for the current repository path and worktree state.
-4. Summary search, then targeted enriched search.
-5. Symbol tools and `read_file` for exact definitions, usages, and ranges.
-6. `optimized_context` when synthesized compact context is available and more useful
-   than exact source.
-7. Local `.notebook/INDEX.md` only if the project already uses `.notebook/`.
-8. Focused shell search/read fallback when massa-ai is unavailable, stale, incomplete, or unindexed.
-9. External sources only when current external library/API behavior matters — and then strictly through the ordered chain in `references/knowledge-verification-chain.md` (project docs → Context7 MCP → web search → flag-as-uncertain, unavailable steps recorded as skipped sensors).
+4. `get_architecture` for architecture-specific deep maps (packages, routes,
+   hotspots, communities, cycles) when the index is fresh.
+5. Summary search, then targeted enriched search. Parameters and default
+   budgets for these two modes are a schema delta owned by `mcp-tools.md`
+   §Retrieval Order.
+6. Symbol tools (`search_definitions`, `get_references`, `go_to_definition`)
+   and `read_file` for exact definitions, usages, and ranges.
+7. `symbol_snippet` for raw code snippets by exact file + line range.
+8. `trace_path` for typed-edge call/data-flow path tracing (fresh index only).
+9. `impact_analysis` for git-diff centrality-ranked impact (fresh index only).
+10. `optimized_context` when synthesized compact context is available and more useful
+    than exact source.
+11. Local `.notebook/INDEX.md` only if the project already uses `.notebook/`.
+12. Focused shell search/read fallback (`rg`, `grep`) when massa-ai is
+    unavailable, stale, incomplete, unindexed, or misses obvious local truth. Spec-driven code analysis
+    adds one tier here — `sg`/ast-grep for structural pattern search when
+    installed, tried before `rg`/`grep`; see
+    `references/spec-driven/code-analysis.md` §Tool Priority.
+13. External sources only when current external library/API behavior matters — and then strictly through the ordered chain in `references/knowledge-verification-chain.md` (project docs → Context7 MCP → web search → flag-as-uncertain, unavailable steps recorded as skipped sensors).
 
 Project maps, search results, and optimized context are leads until confirmed
 against source files read in the current session or returned with current
 freshness evidence. Current repository source and approved `.specs/` artifacts
 override indexed context, memories, external summaries, and old handoff notes.
+This is the canonical statement of that rule; other references point here
+instead of restating it.
 
 For multi-search investigations, load `references/synapse-policy.md`. Keep the
 durable `workflowSessionId` separate from the ephemeral Synapse session.

package/skills/massa-ai/references/conversation-feedback.md

@@ -8,25 +8,18 @@ Conversation feedback is a user-facing progress layer, not a log system. Keep ea
 
 ## Policy Source
 
-Read the canonical Conversation Feedback 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, emit concise transition updates automatically, keep each
-update to 1-2 lines, and suppress chain-of-thought, raw logs, secrets, and
-repeated micro-events.
+The canonical Conversation Feedback Policy — settings, supported label names,
+line shape, worked example, and base rules — is the installed `AGENTS.md` bootstrap
+block (`<!-- massa-ai:bootstrap -->`), whose single source is `skills/AGENTS.md`
+in the product repo. It is always in context, so this file does not repeat it.
+If that block is unavailable, emit concise transition updates automatically,
+keep each update to 1-2 lines, and suppress chain-of-thought, raw logs,
+secrets, and repeated micro-events.
 
-## Line Shape
+## Label Meanings
 
-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.
-
-When relevant, compactly surface phase, loaded context, context pressure,
-checks, risk, handoff state, queue/delegation state, sync outcome, memory
-outcome, skipped checks, and residual risk. Omit fields that do not affect the
-next user decision.
-
-## Supported Labels
+The policy lists the label names; this is when each non-agent label applies. The four
+`Agent *` labels are defined in `references/agent-orchestration.md`.
 
 | Label | Use When |
 |---|---|
@@ -35,16 +28,19 @@ next user decision.
 | `Loading` | Reading a rule, skill, workflow, reference, document, NotebookLM source, or other context source. |
 | `Context` | Reporting memory, search, NotebookLM, source, or repo context that was found or unavailable. |
 | `Decision` | A meaningful tradeoff, scope decision, workflow choice, or default has been chosen. |
-| `Agent Started` | A subagent or delegated role is launched. |
-| `Agent Running` | A subagent is active, waiting, or doing a bounded task. |
-| `Agent Done` | A subagent returns usable evidence, findings, implementation, or verification. |
-| `Agent Blocked` | A subagent cannot complete its assigned scope or needs main-thread/user action. |
 | `Divergence` | Expected context, paths, plan details, user claims, or repo reality disagree. |
 | `Warning` | Work can continue, but confidence or verification is limited. |
 | `Error` | A command, tool, workflow, or required check failed and needs recovery. |
 | `Verified` | Deterministic checks, source inspection, or artifact validation produced evidence. |
 | `Finished` | The workflow closes with changed artifacts, memory outcome, and residual risk. |
 
+## What To Surface
+
+When relevant, compactly surface phase, loaded context, context pressure,
+checks, risk, handoff state, queue/delegation state, sync outcome, memory
+outcome, skipped checks, and residual risk. Omit fields that do not affect the
+next user decision.
+
 ## When To Emit
 
 Emit status updates at lifecycle boundaries and during any work phase lasting >30 seconds:
@@ -71,24 +67,8 @@ Use `references/context-firewall.md` when raw output is verbose. Feedback should
 
 ## Subagent Feedback
 
-When a subagent is used, the main agent reports only the role, scope, permission mode, current task, and status. Do not expose raw subagent prompts or internal deliberation.
-
-The `Agent Started` line's model/effort component has one canonical definition — `references/agent-orchestration.md`'s Model/Effort Announcement — not restated here.
-
-Examples:
-
-```md
-🤖 [Agent Started] Verifier is checking the docs-only change set. Scope: massa-ai references and README.
-🤖 [Agent Done] Verifier found no stale references. Skipped checks: none.
-```
+When a subagent is used, the main agent reports only the role, scope, permission mode, current task, and status. Do not expose raw subagent prompts or internal deliberation. The delegated-work labels and the `Agent Started` model/effort component are defined once in `references/agent-orchestration.md` (its delegated-work label list and Model/Effort Announcement), not restated here.
 
 ## Completion Feedback
 
 Use `Verified` after checks pass or when the strongest available evidence is inspected. Use `Finished` only after the Evidence Gate summary is ready.
-
-Example:
-
-```md
-✅ [Verified] Skill validation and stale-reference scans passed.
-🏁 [Finished] Updated conversation feedback docs. Memory outcome: durable decision stored. Remaining risk: none found.
-```

package/skills/massa-ai/references/create-rfc/quality-and-lifecycle.md

@@ -46,7 +46,7 @@ Keep focus on whether and which direction should be selected. Route detailed imp
 
 ## Plan Challenge Gate
 
-Run the full configured Plan Challenge Gate after the draft exists. Challenge at least:
+Run the full Plan Challenge Gate after the draft exists. Challenge at least:
 
 - strongest counterargument to the recommendation
 - evidence quality and interested-party or vendor bias

package/skills/massa-ai/references/create-tdd/quality-and-lifecycle.md

@@ -31,7 +31,7 @@ If a blocking item fails, revise the draft or ask the user. Non-blocking gaps re
 
 ## Challenge Gate
 
-Run the configured Plan Challenge Gate after the draft exists. For the default full TDD gate, prefer pre-mortem mode unless security/adversarial risk calls for red-team or source claims call for evidence audit.
+Run the Plan Challenge Gate after the draft exists. For the full TDD gate, prefer pre-mortem mode unless security/adversarial risk calls for red-team or source claims call for evidence audit.
 
 Challenge at least:
 

package/skills/massa-ai/references/decision-engine.md

@@ -61,13 +61,9 @@ Before a non-trivial change, ask:
 Most bugs come from state inconsistency, async/race issues, wrong data-shape
 assumptions, or environment differences.
 
-Debug loop:
-
-1. Recall prior attempts and known patterns.
-2. Define expected vs actual behavior.
-3. Trace input -> transformation -> output.
-4. Check recent changes first.
-5. Test one falsifiable hypothesis at a time.
-6. Persist durable lessons only after scoring.
+For the full diagnosis loop (intake, feedback-loop gate, hypothesis board,
+instrumentation, fix and prevention), see `references/debug-diagnosis-loop.md`.
+
+Persist durable lessons only after scoring.
 
 Avoid blind whole-repo scans when a targeted recall/search path exists.

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

@@ -1,26 +1,23 @@
 # Design-To-Code Implementation Direction
 
-The single normative copy of the mobile UI implementation direction set:
-Target Surface Packet, Figma Evidence / Screenshot Context Packet, the
-Design-To-Code Mapping Matrix, coherent-slice implementation rules, and
-per-slice verification/completion criteria.
+The single normative copy of the design-route direction set on top of the
+mobile-figma-matcher packets: coherent-slice implementation rules and
+per-slice verification/completion criteria. Target Surface Packet
+construction is owned by `references/mobile-figma-matcher/repository-detection.md`;
+the Figma Evidence Packet and the Design-To-Code Mapping Matrix are owned by
+`references/mobile-figma-matcher/core.md`.
 
 Loaded by `workflows/design.md` for its direct route (behavior unchanged),
 and by `spec-driven`/`feature` when Figma ingestion is enabled, so those
 workflows absorb this direction set by reference instead of restating it.
+Load `references/mobile-figma-matcher/repository-detection.md` and
+`references/mobile-figma-matcher/core.md` alongside this file.
 
 ## Target Surface Packet
 
-Build the immutable Target Surface Packet before loading stack guidance.
-Classify each selected surface and load only its contracts:
-
-- 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.
+Load `references/mobile-figma-matcher/repository-detection.md` and build its
+immutable Target Surface Packet before loading stack guidance; that
+reference also owns the platform -> matcher-contract file map.
 
 Non-mobile targets under Figma ingestion do not have a matcher contract to
 classify against; proceed with the wiring recorded in `references/figma-wiring.md`
@@ -28,22 +25,26 @@ and a best-effort implementation contract, and record that class explicitly.
 
 ## Figma Evidence / Screenshot Context Packet
 
-Build the Figma Evidence Packet with metadata when needed, design context,
-screenshot, variables, current Code Connect mappings, variants/states,
-annotations, and asset inventory. For screenshot-only sources, build a
-Screenshot Context Packet with provenance, target state, visible constraints,
-uncertainty, and `Design Evidence Class: screenshot-context-only`; do not
-infer exact Figma tokens, dimensions, variables, variants, or parity from
-screenshots alone. Stop if neither structured Figma evidence nor supplied
-screenshot context is available.
+Load `references/mobile-figma-matcher/core.md` and build its Figma Evidence
+Packet: metadata when needed, design context, screenshot, variables, current
+Code Connect mappings, variants/states, annotations, and asset inventory.
+
+Unlike the audit/fix route (`core.md` Boundaries: "A screenshot or pasted
+description alone is not a design contract"), the design route additionally
+accepts screenshot-only sources: build a Screenshot Context Packet with
+provenance, target state, visible constraints, uncertainty, and `Design
+Evidence Class: screenshot-context-only`; do not infer exact Figma tokens,
+dimensions, variables, variants, or parity from screenshots alone. Stop if
+neither structured Figma evidence nor supplied screenshot context is
+available.
 
 ## Design-To-Code Mapping Matrix
 
 Resolve current components, tokens, resources, assets, source-set ownership,
-platform adapters, requirements, and existing validation sensors. Create the
-Design-To-Code Mapping Matrix and one comparison configuration per selected
-runtime surface; screenshot-only rows use inferred visual intent, not
-`Figma Value`.
+platform adapters, requirements, and existing validation sensors, then build
+`references/mobile-figma-matcher/core.md`'s Design-To-Code Mapping Matrix and
+one comparison configuration per selected runtime surface; screenshot-only
+rows use inferred visual intent, not `Figma Value`.
 
 ## Sizing And Verification Recipe
 

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

@@ -34,8 +34,8 @@ bun skills/massa-ai/scripts/lessons.ts --root . add \
 
 `--project`/`--session`/`--workflow`/`--entity` carry the active massa-ai
 context onto the lesson so the file store and massa-ai memory stay in the same
-recall namespace. They are optional for manual runs but supplied by the
-continuous-learning hook loop.
+recall namespace. They are optional for manual runs; pass them whenever the
+active context is known.
 
 Do not record one-off tool failures, transient environment issues, methodology opinions, or chat summaries as lessons.
 
@@ -122,20 +122,12 @@ oldest-first followed by `trend: improving|stable|degrading`, or
 
 If `lessons.ts` is unavailable or cannot run, record `Lessons: skipped - script unavailable` in the validation report or evidence gate, keep the raw signal in the report, and do not hand-edit `lessons.json`. A future run with the script can import the validated signal.
 
-## Continuous-Learning Loop (hook-fed)
+## Observation Buffer
 
-The lessons layer is a closed loop, not manual-only. Two runtime hooks
-(`apps/claude-plugin/hooks/`, installed for Claude Code by the plugin installer) feed it:
-
-1. **observe** — `observe_runner.py` (PostToolUse) captures raw tool-use
-   observations into the gitignored `.specs/observations.json` buffer. Grounding
-   is NOT assigned here.
-2. **evaluate** — `continuous_learning_evaluate.py` (Stop) reads the active
-   massa-ai context from `.specs/project/STATE.md` and the observations
-   buffer. For each observation that already carries grounded fields
-   (`signal`, `text`, `source`, `feature`), it calls `lessons.ts add` with the
-   `--project`/`--session`/`--workflow`/`--entity` context. Ungrounded
-   observations are left in the buffer for agent input and logged as skipped.
+`lessons.ts observe` appends one raw JSON observation to the gitignored
+`.specs/observations.json` buffer. No host hook feeds or drains it today: the
+former hook-fed observe/evaluate loop was removed, so a lesson exists only once
+the agent records it with `lessons.ts add` from a grounded verification signal.
 
 ### massa-ai Dual-Write
 
@@ -149,9 +141,10 @@ and durable memory stay consistent:
   `memory:procedural`. This puts lessons in the same recall namespace as
   massa-ai decisions/patterns, so future `recall` surfaces them at
   Specify/Design.
-- massa-ai MCP is agent-side only; the hook/CLI subprocess writes via REST
-  (`MASSA_AI_API_URL`). When REST is unavailable, the lesson still lands in
-  `lessons.json` and the skipped memory write is logged (graceful degradation).
+- massa-ai MCP is agent-side only; the CLI subprocess writes via REST
+  (`MASSA_AI_API_URL`, 1.5 s timeout). When REST is unset or unavailable, the
+  lesson still lands in `lessons.json` and the memory write is dropped silently —
+  nothing is logged and the exit code is unchanged (graceful degradation).
 
 ### Round-Trip
 
@@ -166,5 +159,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. Nothing else records it — the hook loop keeps no skip
-log on disk, so your stated reason is the only record.
+state the skipped reason. Nothing else records it — no skip log exists on disk,
+so your stated reason is the only record.