@massa-ai/cursor-plugin 1.6.0

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

@@ -0,0 +1,96 @@
+# Codebase Investigation
+
+Use this reference when understanding unfamiliar code before planning, fixing, reviewing, or refactoring.
+
+## Golden Rules
+
+1. **Never assume or invent.** Uncertainty beats fabrication.
+2. **Deserves-a-note.** Persist durable understanding, not trivia.
+3. **Pointers, not copies.** Reference source by `path`/symbol/line; do not duplicate bulk content.
+4. **Surgical precision.** Smallest sufficient read/change.
+5. **Verify against source.** Memories and indexed context are leads until confirmed.
+
+Write and search in the user's human language. Match the user's prompt language for prose; match the codebase for identifiers, paths, and commands.
+
+## Mission Cycle
+
+Follow this proportional cycle (BRIEFING → PLAN → EXECUTE → DEBRIEF):
+
+1. **Briefing:** define objective, success criteria, constraints, and current session.
+2. **Recon:** inspect only relevant code paths and prior memories.
+3. **Plan:** state steps with per-step `verify:` criteria (what confirms the step succeeded) before non-trivial reads or edits.
+4. **Execute:** make surgical changes only when the workflow allows mutation.
+5. **Verify:** use deterministic sensors or concrete artifact inspection.
+6. **Debrief:** persist only durable discoveries; record what was verified against source.
+
+For exploration-only work, Recon and Debrief are the main deliverables.
+
+## Source 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
+   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. Official docs or web search only when current external API behavior matters.
+
+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.
+
+For multi-search investigations, load `references/synapse-policy.md`. Keep the
+durable `workflowSessionId` separate from the ephemeral Synapse session.
+
+massa-ai remains canonical memory for massa-ai workflows. Do not introduce `.notebook/` as a default persistence layer.
+
+## Recon Rules
+
+- Start from the closest entry point to the question.
+- Trace input -> transformation -> output for behavior questions.
+- Prefer pointers over copied code in notes and reports.
+- Read signatures and high-value logic first; avoid whole-project sweeps.
+- Treat generated, dependency, build, log, cache, and secret paths as out of scope unless explicitly relevant.
+
+## Debrief Rules
+
+Persist only if rediscovery would cost future effort:
+
+- project convention or repeated pattern
+- architectural constraint or accepted exception
+- fragile flow, gotcha, or verified root cause
+- rejected approach that future agents might reintroduce
+- verification recipe worth reusing
+
+**Note-worthiness trigger:** when understanding touches 3+ files or a non-trivial flow, persist a note to the massa-ai memory layer. Below that threshold, decide per-finding.
+
+Three-way note decision:
+
+- **create** — new durable finding worth its own note
+- **update** — existing non-stale note for the same entity
+- **skip** — trivial, one-off, or already captured
+
+Skip memory for trivial observations, one-off findings, and facts already captured in current non-stale memories.
+
+## Investigation Output
+
+Use this compact shape:
+
+```md
+Objective: ...
+Scope checked: ...
+Entry points: ...
+Flow: input -> transformation -> output
+Key evidence: `path` / symbol / command
+Open questions: ...
+Next step: ...
+Memory: write / skip, with reason
+```

package/skills/massa-ai/references/context-firewall.md

@@ -0,0 +1,62 @@
+# Context Firewall
+
+Use this reference before loading raw artifacts >200 lines, >20 KB, >50 search hits, generated reports, logs, screenshots, browser snapshots, CSVs, external research, or any source batch likely to exceed the next decision's needs.
+
+## Principle
+
+Keep verbose data outside the main reasoning window. Bring back only the facts needed for the next decision.
+
+## Think In Code
+
+For high-volume analysis:
+
+- Prefer focused commands, small scripts, or structured parsers over reading large raw files into context.
+- Return counts, paths, summaries, failing cases, and representative snippets.
+- Include context pressure, queue/delegation state, sync or memory outcome, and
+  skipped-check reasons only as compact fields when they affect the next
+  decision.
+- Keep temporary analysis outside repo-tracked files unless the task explicitly needs a reusable script.
+- Use project map, summary search, targeted enriched search, symbol/file tools,
+  `optimized_context`, and compression before broad shell reads when
+  useful.
+- Prefer `responseMode: "enriched"` only for a small targeted result set; it
+  includes full content and should not become a broad dump.
+
+## Thresholds
+
+Apply the firewall before bringing any of these raw artifacts into the main context:
+
+- Source, docs, logs, CSV, or reports over 200 lines or 20 KB.
+- Search, grep, MCP, or external research output over 50 hits.
+- Generated audit reports, screenshots, browser snapshots, crash/device logs, or raw NotebookLM/web research dumps.
+- Any subagent output, tool transcript, or diff where only counts, paths, representative snippets, or failing cases are needed for the next decision.
+
+## Tool Output Discipline
+
+- Do not paste raw logs, snapshots, huge diffs, CSVs, or long command output into the main conversation.
+- Summarize the result and include exact source pointers, commands, line numbers, or artifact paths.
+- Artifact, memory, and search output is metadata-and-summary by default: include keys, paths, versions, checksums, statuses, counts, short summaries, and exact next steps only.
+- Do not bring raw full artifact JSON, all-version artifact dumps, raw memory dumps, raw `search` result bodies, or long command transcripts into working context unless diagnosing corruption and no smaller proof can answer the question.
+- Summarize raw subagent output, raw diffs, raw search output, raw logs, raw transcripts, and external research before they reach the main context.
+- If conversation feedback is active, status lines may say what is being loaded, checked, blocked, or verified, but must not include raw tool output or private reasoning.
+- Re-open only the smallest raw segment needed to verify a claim.
+- If output is too large to inspect safely, delegate to a subagent or run a local summarizing command.
+
+## Subagent Firewall
+
+Use `references/agent-orchestration.md` for context-heavy research, verbose log inspection, or independent verification when delegation gates are met.
+
+The main agent receives only:
+
+- evidence
+- findings
+- risks and skipped checks
+- exact next step
+
+Subagents should not return raw dumps. The main agent still owns memory recall, persistence, synthesis, and the final Evidence Gate.
+
+## Persistence Boundary
+
+`massa-ai` remains the canonical memory layer for massa-ai workflows. Do not introduce `.notebook/`, SQLite, generated state files, or new persistence systems unless a separate workflow explicitly requires them.
+
+`references/conversation-feedback.md` is chat-visible progress only. It must not be treated as durable state, memory, or an event store.

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

@@ -0,0 +1,104 @@
+# Conversation Feedback
+
+Use this reference when a massa-ai workflow needs chat-visible status updates for routing, loading, memory, NotebookLM, subagents, divergences, errors, verification, or completion.
+
+## Principle
+
+Conversation feedback is a user-facing progress layer, not a log system. Keep each update readable, factual, and short enough that it helps the user understand what is happening without dragging raw tool output into the chat.
+
+## 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.
+
+## Line Shape
+
+Each status update must be 1-2 lines. Use an emoji, a capitalized label in square brackets, and one or two plain sentences.
+
+Do:
+
+```md
+🔵 [Start] Planning visual feedback for massa-ai. Workflow: Spec Driven. Session: Visual Feedback.
+🔄 [Loading] Reading AGENTS.md and massa-ai router guidance before planning.
+🧠 [Context] Found 8 relevant massa-ai memories and queried the requested NotebookLM source.
+🤖 [Agent Running] Plan Critic is checking failure modes for the proposed design.
+⚠️ [Divergence] Expected the legacy router path, but this checkout uses skills/massa-ai/SKILL.md.
+✅ [Verified] Stale-reference checks and skill validation passed.
+🏁 [Finished] Plan complete. Changed files: none. Remaining risk: none found.
+```
+
+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
+
+| Label | Use When |
+|---|---|
+| `Start` | A coding, planning, audit, debug, handoff, ADR, RFC, or TDD workflow begins. |
+| `Routing` | The workflow, entity, project, or session is selected. |
+| `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. |
+
+## When To Emit
+
+Emit status updates at lifecycle boundaries and during any work phase lasting >30 seconds:
+
+- workflow start and routing
+- before loading substantial rules, workflows, references, docs, NotebookLM sources, or broad context
+- after memory/search/context discovery when it changes the next step
+- before and after NotebookLM, web, MCP, or shell checks expected to take >30 seconds
+- after a Synapse fallback or schema divergence changes retrieval behavior;
+  report the behavior, not secret values or raw session payloads
+- before starting a subagent, while waiting on a long-running subagent, and after it returns
+- when repo reality diverges from expected paths, names, branches, files, docs, or user-provided assumptions
+- when a warning, recoverable tool failure, or blocking error appears
+- after deterministic verification
+- at final completion
+
+Skip updates for micro-events such as every small file read, every search retry, or repeated polling with no new state.
+
+## Privacy And Context Discipline
+
+Never include private reasoning, chain-of-thought, raw logs, raw diffs, raw snapshots, raw search output, raw subagent prompts, secrets, or long tool output in feedback updates.
+
+Use `references/context-firewall.md` when raw output is verbose. Feedback should summarize the visible state and point to evidence later in the final report.
+
+## 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.
+
+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.
+```
+
+## 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/debug-diagnosis-loop.md

@@ -0,0 +1,140 @@
+# Debug Diagnosis Loop
+
+Use this reference when `workflows/debug.md` asks for an evidence-first diagnosis loop.
+
+## Principle
+
+Debugging is a feedback-loop problem first and a code-change problem second. Before editing, establish a trustworthy way to observe the failure and later prove the fix, or document why only root-cause proof is possible.
+
+## Intake Packet
+
+Capture the smallest useful issue packet before broad investigation:
+
+- Expected behavior
+- Actual behavior
+- Environment: local, CI, staging, production, browser/device, service, region, tenant, or data set
+- Frequency: always, intermittent, percentage, time window, or reproduction count
+- Affected components and entry point
+- Reproducibility: command, request, user steps, fixture, trace, or missing repro
+- Recent changes: deploy, config, dependency, schema, data, feature flag, infrastructure, or permissions
+- Safety constraints: production access limits, data sensitivity, allowed mutation level, and rollback constraints
+
+If any field is unknown, continue with available evidence unless the missing field blocks a safe pass/fail loop.
+
+## Feedback-Loop Gate
+
+Pick the first reproduction ladder step that preserves the original failure signal and can be rerun after the fix:
+
+- Unit/component or CLI repro around the failing seam, including a focused failing test, regression scaffold, or command transcript
+- Integration/API/service repro, including `curl`/HTTP script, API client command, route smoke check, fixture, or trace replay
+- App/browser/device/simulator repro, including browser automation, UI artifact inspection, emulator/simulator/device run, or screenshot/video proof
+- Trace, replay, or event fixture
+- Throwaway harness in a temp location when production code is hard to reach
+- Fuzz/property loop when input space is the suspected trigger
+- `git bisect`, dependency diff, config diff, or differential run between known good and bad versions
+- Structured human-in-the-loop (HITL) script when the user must perform a step: exact action, exact observation, exact pass/fail signal
+
+Skipped-reason enum when no loop can run: `missing-credentials`, `missing-service`, `missing-hardware`, `unsafe-production`, `destructive-risk`, `tool-missing`, `data-unavailable`, or `not-reproducible-yet`.
+
+Loop quality rules:
+
+- Prefer deterministic, fast, local loops.
+- Preserve the original user-facing failure signal; do not replace it with a narrower check unless the original loop is also rerun before completion.
+- If the loop requires unavailable credentials, services, or data, state the missing dependency and use the strongest root-cause proof available.
+- Do not edit code to "see what happens" before the loop or proof exists.
+
+## Non-Deterministic Failures
+
+For flaky or production-only failures, raise the reproduction rate before root-cause guessing:
+
+- Measure the current reproduction rate, such as `3/50` runs or "appeared twice in 20 minutes".
+- Isolate entropy one source at a time: time, randomness, async scheduling, cache, filesystem, network, concurrency, global state, data ordering, environment variables, feature flags, clock/timezone, permissions, and external services.
+- Add controls or probes that increase signal: fixed seeds, fake timers, serialized execution, cache reset, narrowed input set, correlation IDs, or sampled traces.
+- If the failure cannot be made repeatable, keep the confidence label explicit and verify with multiple independent signals.
+
+## Minimize The Case
+
+Reduce noise while preserving the failure:
+
+- Smallest input, request body, fixture, trace, or UI step set that still fails
+- Smallest module path that still contains the divergence
+- Smallest environment difference or recent-change window that explains the symptom
+- Smallest commit/dependency/config range when regression timing matters
+
+Stop minimizing when further reduction would remove the actual behavior being debugged.
+
+## Hypothesis Board
+
+Before testing, create 3-5 falsifiable hypotheses. Use prior memories to avoid repeating ruled-out paths.
+
+```md
+| Rank | Hypothesis | Why plausible | Prediction | Probe | Disproof | Result |
+|---|---|---|---|---|---|---|
+| 1 | ... | evidence or memory | what should be true if this is root cause | command/log/assertion/inspection | what result rules it out | untested / supported / ruled out |
+```
+
+Rules:
+
+- Test the highest-value hypothesis first, not the easiest one if it has weak explanatory power.
+- Each probe must have a clear predicted result before running it.
+- Treat symptoms and root causes separately.
+- Update the board after each probe; do not retry the same failing command more than twice unchanged.
+- If evidence contradicts every hypothesis, revise the board instead of patching speculatively.
+
+## Instrumentation
+
+Instrument to answer one question at a time:
+
+- Prefer debugger, REPL, focused assertions, and small scripts before adding app logs.
+- Add targeted tagged logs only when they answer a named hypothesis.
+- Include correlation IDs, request IDs, timestamps, tenant/user-safe identifiers, or span IDs when needed to join events.
+- Use structured parsers or summary commands for large logs; load `references/context-firewall.md` before bringing verbose output into context.
+- Remove temporary instrumentation before completion unless the change is intentionally retained as observability, and document why it stays.
+
+## Production-Safe Diagnosis
+
+Use these only when concrete tools, access, and user/project policy allow them. Do not hard-require any vendor or platform.
+
+- OpenTelemetry spans, attributes, metrics, or trace correlation
+- Feature-flagged debug logging with sampling and expiration
+- Sampling profilers or read-only performance snapshots
+- Protected read-only inspection through existing approved tools
+- Canary, shadow traffic, replay, or staged rollout validation
+- Release, config, dependency, schema, and feature-flag diffing
+
+Production guardrails:
+
+- Do not expose secrets, tokens, PII, or sensitive customer data in logs or memory.
+- Avoid write operations against production during diagnosis unless the user explicitly approves and rollback is defined.
+- Prefer canary or sampled checks over broad instrumentation.
+- Record skipped production checks and why they could not run.
+
+## Fix And Prevention
+
+Fix the divergence point closest to the root cause:
+
+- Make the smallest behavior-preserving change that explains the evidence.
+- Do not bundle adjacent refactors with the debug fix.
+- Add regression coverage at the seam that failed: unit, integration, route, CLI, UI, contract, fixture, or monitor.
+- If no valid regression seam exists, document the missing seam, provide the strongest available proof, and persist a testability or architecture note only when durable.
+- Rerun the original feedback loop after the fix, plus the regression check and any validation assets from `references/verification-ladder.md`.
+
+## Output Contract
+
+A completed debug workflow should report:
+
+- Issue Summary: symptom, impact, frequency, and environment
+- Feedback Loop: command, tool, artifact, or root-cause proof that showed failure and then success
+- Hypothesis Board: ranked hypotheses and tested results
+- Root Cause: evidence-backed diagnosis with the divergence point
+- Fix + Validation: code/test strategy, verification recipe, and commands or artifacts checked
+- Prevention: regression test, monitor/runbook suggestion, and memory outcome
+
+## Memory Guidance
+
+Persist only durable debugging knowledge after recall and importance scoring:
+
+- Root cause as semantic `decision` memory when future agents could repeat the mistake
+- Reusable verification or diagnostic recipe as procedural `pattern` memory
+- Ruled-out hypotheses as episodic `conversation` memory only when rediscovery would waste future effort
+- Repeated failed tool loops as cognition lessons only when the lesson is reusable across sessions

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

@@ -0,0 +1,73 @@
+# Decision Engine Reference
+
+Load this when scoring memories, making a trade-off decision, or debugging with
+prior attempts. Do not load for simple edits where no memory write or design
+decision is needed.
+
+## Importance Calibration
+
+Use named levels, then pass only `importance` to `remember`.
+
+| Level | Float | Use when |
+|---|---:|---|
+| CRITICAL | 0.95 | Forgetting causes data loss, security holes, outage, or system-wide breakage. |
+| HIGH | 0.8 | Forgetting causes bugs, architectural drift, or repeated wrong choices. |
+| MEDIUM | 0.7 | Forgetting causes wasted effort or rediscovery. |
+| LOW | 0.6 | Useful acceleration context, not essential. |
+| SKIP | - | Trivial, local, duplicate, or not durable. |
+
+Score from base 0.5:
+
+| Question | Weight |
+|---|---:|
+| Would forgetting this cause a production bug/outage? | +0.15 |
+| Does it affect more than one module/service/feature? | +0.10 |
+| Would a future agent choose wrongly without it? | +0.15 |
+| Did it take meaningful effort to discover/decide? | +0.10 |
+| Is it a hard constraint rather than a preference? | +0.10 |
+
+Map score: 0.95 CRITICAL, 0.8 HIGH, 0.7 MEDIUM, 0.6 LOW, otherwise SKIP.
+
+## Memory Examples
+
+- CRITICAL: auth token algorithm constraint after a security incident.
+- HIGH: project architecture pattern future agents must follow.
+- MEDIUM: ruled-out hypothesis that took real investigation.
+- LOW: useful but nonessential local workflow context.
+- SKIP: user formatting preference or already-captured fact.
+
+## Trade-Off Template
+
+```text
+Decision: <what changed>
+Optimizing for: <benefit>
+Sacrificing: <cost>
+Reversibility: easy | hard | irreversible
+Confidence: high | medium | low
+Evidence: <source-backed facts>
+```
+
+## Product And System Checks
+
+Before a non-trivial change, ask:
+
+- What user problem does this solve?
+- Is it core flow or edge case?
+- What is the simplest solution that works?
+- What coupling, maintainability, observability, or scaling tradeoff changes?
+
+## Debugging Heuristics
+
+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.
+
+Avoid blind whole-repo scans when a targeted recall/search path exists.

package/skills/massa-ai/references/evidence-gate.md

@@ -0,0 +1,53 @@
+# Evidence Gate
+
+Read this before declaring a task complete, closing a session, or handing work to another agent.
+
+For non-trivial edits or broad workflow work, load `references/verification-ladder.md` and report the highest verification level reached.
+
+If Conversation Feedback Policy is active, emit a `Verified` status after deterministic evidence is collected and a `Finished` status only when the completion summary is ready. Feedback lines do not replace the evidence report.
+
+## Required Completion Evidence
+
+A completion report must include:
+
+- Deterministic evidence: clean exit code, static check output, test result, build result, or concrete artifact inspection
+- Verification ladder: level reached, validation assets protected, and skipped checks with reasons when applicable
+- Changed artifacts: file paths changed, generated outputs, or state that no files changed
+- Memory outcome: memories written, intentionally skipped with reason, duplicate skipped, forbidden payload skipped, or failed memory writes with recovery note
+- Residual risk: unresolved errors, skipped checks, missing environment, or explicit `none found`
+
+Completion reports must also state that tests, specs, fixtures, snapshots,
+schemas, public contracts, and validator checks were not weakened unless the
+user explicitly requested a validation-asset change.
+
+## Acceptable Evidence
+
+| Work type | Minimum evidence |
+|-----------|------------------|
+| Docs/skill changes | `rg` stale-reference checks and file existence checks |
+| Code changes | Verification recipe, relevant tests/build/lint/focused command output, and file-integrity check when validation assets are in scope |
+| Debug fix | Reproduction no longer fails or root-cause path is proven |
+| Audit / Implementation Audit | Concrete findings tied to files/lines, plus skipped-check notes |
+| Handoff | Session Guide with exact `workflowSessionId`, `projectId`, next step, and unresolved risks; ephemeral Synapse IDs are excluded |
+
+## Example
+
+Use this compact shape when closing docs or skill work:
+
+```md
+✅ [Verified] Skill validation and stale-reference scans passed.
+🏁 [Finished] Updated massa-ai references. Memory outcome: durable decision stored. Remaining risk: none found.
+
+Evidence: `rtk python3 skills/skill-architect/scripts/validate_skill.py skills/massa-ai --format json` passed; stale-reference and local-link scans passed.
+Changed artifacts: `skills/massa-ai/SKILL.md`, `workflows/spec-driven.md`, `references/spec-driven/`, and `references/memory-policy.md`.
+Memory outcome: wrote decision memory `dec_...`; no failed memory writes.
+Residual risk: none found.
+```
+
+## Failure Rules
+
+- Do not claim done if the only evidence is model self-evaluation.
+- Do not retry the same failing command more than twice unchanged; diagnose or instrument first.
+- If deterministic checks cannot run, state exactly why and provide the strongest available manual check.
+- Do not modify validation artifacts to make a check pass unless the user explicitly asked to update the validation itself.
+- Treat judge, faithfulness, or semantic checks as optional higher-order evidence only when a concrete tool or command exists.

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

@@ -0,0 +1,49 @@
+# Role: furps-analyst
+
+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 and return 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 `plan-critic` for The Fool, `investigator`/`verifier` 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 (`furps-analyst`)
+- 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.