@massa-ai/cursor-plugin 1.6.0

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

@@ -0,0 +1,160 @@
+# Synapse Policy
+
+Load this reference when a task is expected to issue more than one
+`search`, when parallel agents need isolated retrieval context, or when
+Synapse compatibility/fallback behavior matters.
+
+## Two Session IDs
+
+- `workflowSessionId`: stable, durable task identity used by recall, remember,
+  tags, reports, handoffs, and continuation packages.
+- `synapseSessionId`: ephemeral ID returned by `synapse_session`; pass it
+  only as `search.sessionId`.
+
+Never persist `synapseSessionId` as the task's durable session identity. A
+resumed handoff reuses `workflowSessionId` and opens a fresh Synapse session.
+
+## Activation
+
+- One-shot lookup: skip Synapse.
+- Planned related `search` calls >= 2: create a Synapse session before the first search.
+- Parallel subagents: each agent gets its own Synapse session while retaining
+  the parent/child `workflowSessionId` tags.
+- 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:
+
+- 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:
+
+- Working-memory buffer holds **20 entries** by default. Priming or prefetching
+  more than that evicts the earlier ones — seed the few memories that matter,
+  not a whole recall page.
+- Sessions expire after **1h**, sliding forward on every `synapse_get` or
+  recorded access.
+
+Config knobs (env, read by the server, not by the agent):
+
+| Env var | Default | Effect |
+|---|---|---|
+| `SYNAPSE_ENABLED` | `true` | Master kill switch; `false` bypasses the whole pipeline, and `search` behaves statelessly even when a `sessionId` is passed. |
+| `SYNAPSE_ATTENTION_ENABLED` | `false` | Multi-signal attention re-ranker. **Off by default** — do not attribute re-ranking to Synapse unless it is on. |
+| `LOG_LEVEL` | `info` | `debug` emits one pipeline log line per query (see Reading Pipeline Output). |
+
+## MCP-First Lifecycle
+
+1. Call `synapse_session` with explicit `agentId`, `workspaceId`,
+   one-sentence `taskContext`, and `ttlMs`. Omit `sessionId` so the server
+   generates a collision-free ID. Keep `agentId` stable across the whole task —
+   agent affinity needs one identity.
+2. Call `recall` using `workflowSessionId` and project/entity context.
+3. Open a task envelope with `synapse_task_begin` (`id` = the session id, plus a
+   one-sentence `taskContext`) before the task's searches.
+4. Prime the buffer when the adapter supports it, within the 20-entry bound.
+5. Pass the returned `synapseSessionId` as `sessionId` on every related
+   `search` call.
+6. Call `synapse_prefetch` right after deciding to open a specific file, so the
+   buffer is warm before the next search.
+7. After consuming a result, record its `memoryId` through the verified access
+   route when available.
+8. Close the task envelope with `synapse_task_end` when the task's work is done.
+   Update `taskContext` only when the *kind* of work changes, never per query.
+
+Verified v2.0.2 adapter warnings:
+
+- MCP prime exposes `{ id, results }`, but the installed adapter forwarded that
+  body unchanged to REST, which requires `{ entries }`, and returned HTTP 422.
+- MCP access returned `Session not found or expired` for a live session that
+  REST could inspect and update; direct REST access with the same `memoryId`
+  succeeded.
+
+Treat MCP prime and access as compatibility-sensitive. Do not retry the same
+failing call; use REST or skip the optional step. Always use `memoryId` for
+access recording. File-path-only access is unsupported until a runtime probe
+proves adapter translation.
+
+## REST Lifecycle Fallback
+
+Use REST only when `MASSA_AI_API_URL` is available and the operation is absent or
+broken in MCP. Default local URL is `http://localhost:3333`.
+
+If `MASSA_AI_API_KEY` is configured, send it as `x-api-key`. Never print, persist,
+or place the key in memory, reports, status updates, command transcripts, or
+committed files.
+
+REST-only lifecycle operations:
+
+| Operation | Route | Use |
+|---|---|---|
+| Inspect | `GET /api/v1/synapse/session/:id` | Confirm state or diagnose expiry. |
+| Update focus | `PATCH /api/v1/synapse/session/:id` | Replace task context after a major focus shift. |
+| Prime | `POST /api/v1/synapse/session/:id/prime` | Send `{ "entries": [...] }` when MCP priming fails. |
+| Prefetch | `POST /api/v1/synapse/session/:id/prefetch` | Warm context for a file that will be investigated. |
+| Close | `DELETE /api/v1/synapse/session/:id` | Free resources after completion when practical. |
+
+REST prime entries require `id` and `content`; `score` and `metadata` are
+optional. REST prefetch requires `filePath` and may include `symbols`, `chains`,
+`maxResults`, `minImportance`, or `entries`.
+
+## Reading Pipeline Output
+
+With `LOG_LEVEL=debug`, the server emits one structured line per Synapse-scoped
+query. Use it to decide whether Synapse is helping or whether the query needs
+refining — not as evidence about the codebase.
+
+```json
+{
+  "before": 16, "after": 14,
+  "queryClass": "specific",
+  "intent": "decision",
+  "appliedFilters": ["buffer-hit","pre-gate","attention","chain","diversity","temporal","confidence-gate","spectrum","buffer-put"],
+  "flags": { "lowConfidence": false, "noStrongMatch": false, "definitiveMatch": true,
+             "spread": 0.31, "mean": 0.78, "confidence": 0.24 }
+}
+```
+
+| Signal | Reading |
+|---|---|
+| `appliedFilters` has `buffer-hit` | Buffer had warm results — priming/prefetch is paying off. |
+| `appliedFilters` has `pre-gate` | Early raw-score filter cut noise before attention. |
+| `appliedFilters` lacks `attention` | `SYNAPSE_ATTENTION_ENABLED=false`; task alignment did not re-rank. |
+| `queryClass = "specific"` | Symbol-like query; confidence gate at 0.55. |
+| `queryClass = "focused"` | Tech terms; gate at 0.40. |
+| `queryClass = "broad"` | Exploratory; gate at 0.25. |
+| `intent != "general"` | Chain inhibition modulated results by memory type. |
+| `flags.definitiveMatch = true` | One dominant hit; the top result is trustworthy. |
+| `flags.lowConfidence = true` | Results clustered — the query is ambiguous. Refine it; this is not a failure. |
+| `flags.noStrongMatch = true` | Nothing crossed the threshold — the answer is probably not in the corpus. Fall back to source reads. |
+
+## Failure Policy
+
+- Session creation fails: continue with stateless massa-ai search.
+- Priming or access fails: use verified REST exactly once after recording the MCP failure mode; if REST fails or is unavailable, continue without priming/access.
+- Search rejects `sessionId`: retry once without it and report the divergence.
+- REST unavailable or unauthorized: stay MCP-only and let TTL expire.
+- Session expires or disappears after server restart: create a new session; do
+  not reuse the old ID. Synapse state is ephemeral and process-local.
+- Never reset or reindex a project to repair a Synapse-only failure.
+
+## Anti-Patterns
+
+- Reusing one session across unrelated tasks: task-alignment, agent-affinity,
+  and buffer signals drift into noise. Open a fresh session per task.
+- Updating `taskContext` after every query — the signal stops meaning anything.
+- Priming hundreds of entries against a 20-entry buffer.
+- Sending a different `agentId` per call.
+- Passing `synapseSessionId` on a one-shot stateless lookup.
+- Treating `flags.lowConfidence` as "search failed".
+- Persisting `synapseSessionId` as the task's durable session identity.
+
+## Completion
+
+Close the REST session when the endpoint is available and cleanup is cheap.
+Otherwise rely on the explicit TTL. Report Synapse failures only when they
+changed retrieval confidence, skipped expected behavior, or exposed a contract
+regression.

package/skills/massa-ai/references/tdd/calibrated-examples.md

@@ -0,0 +1,54 @@
+# Calibrated Examples
+
+The values below are starting reference values, not requirements. They are calibration anchors, not mandates. Treat every number as a starting-point reference to be confirmed against the project's own SLOs, load profile, and regulatory scope; override per project and record the override in the TDD. None of these tables restore a prescriptive count schema or a fixed section-count mandate.
+
+Load this reference only when the TDD's conditional concerns (rollback, rollout, latency, compliance) apply and the team needs a concrete starting point. It complements `references/tdd/document-contract.md` (which owns the Conditional Concerns trigger table) by giving example budgets; it does not replace project-verified SLOs or legal obligations.
+
+## Rollback-Trigger Table
+
+Calibration anchors, not mandates. Each row is a starting-point signal that typically warrants a rollback (or the documented forward-recovery equivalent); confirm thresholds against project telemetry before relying on them.
+
+| Signal | Starting reference threshold | Action |
+|---|---|---|
+| Error-rate spike | error rate exceeds 2x the pre-rollout baseline for 5 consecutive minutes | rollback (or documented forward-recovery) |
+| SLO burn | error-budget burn rate > 10x the normal burn rate over the rollout window | rollback (or documented forward-recovery) |
+| Data-corruption signal | any confirmed write that violates a documented invariant (lost row, wrong field, orphaned reference) | rollback immediately and preserve forensic state |
+| Latency regression | p95 latency exceeds 1.5x the pre-rollout p95 for the affected route | rollback (or documented forward-recovery) |
+| Failed dependency | a critical dependency the rollout relies on is confirmed down | rollback (or pause rollout and contain) |
+
+Rollback is not always technically possible; where it is not, the TDD must document forward recovery, containment, restore, or compensating actions instead of falsely promising reversibility (see `references/tdd/document-contract.md`).
+
+## Rollout Percentages Reference
+
+Calibration anchors, not mandates. This is a common starting-point rollout curve with hold windows; pick the curve that matches the project's risk and reversibility, and record the chosen curve plus its stop conditions in the TDD.
+
+| Stage | Starting reference traffic share | Hold window (reference) | Exit signal |
+|---|---|---|---|
+| Canary | 1% | observe one full business cycle or the project's monitoring window | telemetry within thresholds for the period |
+| Early ramp | 10% | hold until stability signals hold | no rollback-trigger threshold hit |
+| Mid ramp | 50% | hold until stability signals hold | no rollback-trigger threshold hit |
+| General availability | 100% | post-release verification | rollout complete and verified |
+
+Shorter or longer curves are valid when reversibility, blast radius, or regulatory review differ. State the actual curve used; do not copy this reference verbatim into a final document.
+
+## Latency Reference Values
+
+Calibration anchors, not mandates. p50, p95, and p99 are standard percentile definitions; the example budgets are starting points only and must be replaced by project-verified SLOs.
+
+- **p50 (median):** 50% of requests complete at or below this latency. Reference example budget for an interactive API route: 100 ms.
+- **p95:** 95% of requests complete at or below this latency. Reference example budget for an interactive API route: 300 ms.
+- **p99 (tail):** 99% of requests complete at or below this latency. Reference example budget for an interactive API route: 800 ms.
+
+These example budgets fit a typical interactive user-facing API; batch, streaming, and background work have different profiles. Record the project's actual SLO targets and the measurement methodology (window, load, warm or cold) in the TDD rather than citing these reference numbers as if they were the project's budget.
+
+## Compliance Matrix
+
+Calibration anchors, not mandates, and not legal advice. Verify applicability per project; do not claim compliance from generic controls. Each row names the kind of obligation a regime typically implies; it does not certify any system as compliant. Confirm applicability and specific obligations with the project's legal, security, or privacy owner before relying on any row.
+
+| Regime | Typical obligation kind (verify per project) | Verification note |
+|---|---|---|
+| GDPR | lawful basis, data-subject rights, data minimization, cross-border transfer controls, breach notification | applicability depends on processing EU residents' personal data; confirm scope with privacy owner |
+| PCI-DSS | cardholder-data protection, access control, logging, segmentation, vulnerability management | applicability depends on storing, processing, or transmitting cardholder data; confirm scope with security owner |
+| LGPD | legal basis, data-subject rights, purpose limitation, international transfer, DPO accountability | applicability depends on processing Brazil personal data; confirm scope with privacy owner |
+
+This matrix is a starting-point index, not a compliance attestation. Per `references/tdd/document-contract.md`, do not claim compliance from generic controls; identify each applicable obligation as verified, proposed, or unresolved.

package/skills/massa-ai/references/tdd/discovery-and-sizing.md

@@ -0,0 +1,83 @@
+# TDD Discovery And Sizing
+
+Load this reference before source investigation, document sizing, or clarification questions for the TDD workflow.
+
+## Evidence Order
+
+Use the narrowest authoritative source first:
+
+1. Current repository source, schemas, tests, configuration, and project instructions.
+2. Approved project RFCs, ADRs, TDDs, requirements, architecture documents, and tickets available in the workspace.
+3. Relevant current massa-ai memories, treated as evidence rather than authority.
+4. Official dependency or platform documentation when the design depends on external behavior.
+5. External research only when local and official sources cannot answer a material question and browsing is allowed.
+
+Record the source of consequential claims. If sources conflict, prefer current source and explicitly approved artifacts, then stop for user resolution when authority remains ambiguous.
+
+## Testing And UI/UX Discovery
+
+Before drafting implementation or verification sections:
+
+- Inspect existing tests and build/source-set configuration before naming any test file location. For Android or Kotlin Multiplatform repositories, distinguish `commonTest`, `androidUnitTest`, `unitTest`, or the repository's actual equivalent from evidence.
+- For each planned test, decide from source evidence whether the TDD should say `amplify in existing location: <path> (<sourceSet>)` or `create in <sourceSet>: <path>`.
+- For UI/UX-affecting method, class, enum type, sealed type, mapper, state, or model changes, search references and list parallel rendering surfaces and mappers that consume the affected symbol.
+- Before proposing string changes, grep or search for mappers that branch on the affected type and call `stringResource`; run a `Strings Audit` when that pattern exists.
+
+## Fact Discipline
+
+Classify design inputs as:
+
+- **Verified:** directly supported by current source or an authoritative document.
+- **Inferred:** strongly implied by evidence; label the inference and its basis.
+- **Proposed:** a design choice introduced by the TDD and awaiting review.
+- **Unknown:** not discoverable from available evidence.
+
+Never convert an inference or example into a project fact. Omit optional metadata when absent or mark it `TBD`; do not invent people, ticket links, dates other than the actual document date, system names, traffic numbers, SLAs, compliance obligations, estimates, or approvals.
+
+## Workflow Fit
+
+- Use TDD when the direction is selected and implementation design remains.
+- Use RFC when stakeholders still need options compared or the primary direction approved.
+- Use ADR when one significant decision and its consequences need recording without a full implementation blueprint.
+- Use spec-driven when the request spans requirements, design, tasks, and implementation or needs staged approval across those phases.
+- Use feature, refactor, debug, or general for localized work that does not need a durable design artifact.
+
+TDD readiness checklist:
+
+- One product direction is selected.
+- A named requirements source exists, such as user prompt, approved spec, ticket, ADR, RFC outcome, product doc, or current source contract.
+- No unresolved API, data model, security/privacy, migration, rollout, public compatibility, or cross-service decision blocks implementation design.
+- Required owners, decision deadlines, or explicit open questions are known for any non-blocking unknowns.
+
+If any of the first three checks fail, route to RFC, ADR, spec-driven, or clarification before drafting the TDD.
+
+## Adaptive Depth
+
+### Compact
+
+Use when all are true: <=3 files, <=200 changed LOC expected, one implementation path, no new public contract, no new dependency, no migration, no security/privacy boundary, and rollback is delete/revert-level. Include context, chosen design, affected files, tests, and completion criteria.
+
+### Standard
+
+Use when any are true and High-Risk is false: 4-10 files, 201-500 changed LOC expected, multiple components in one ownership area, changed internal interface, new test surface, non-destructive dependency/config change, or one coordinated rollout path. Include relevant contracts, alternatives, rollout, observability, and ownership boundaries.
+
+### High-Risk
+
+Use when any are true: authentication, authorization, privacy, regulated or sensitive data, irreversible operation, migration, cross-service contract, public compatibility, high availability, data-loss/outage risk, >10 files, >500 changed LOC expected, multiple teams/ownership areas, or unclear rollback. Require explicit threat/failure analysis, migration safety, rollout, rollback or forward-recovery strategy, and operational verification.
+
+Do not use week-based project-size heuristics. Effort estimates are useful only when the user or project planning process requires them and evidence supports them; use ranges and assumptions rather than fabricated precision.
+
+## Clarification Policy
+
+Inspect first, ask second. Ask only when the answer changes architecture, scope, a public contract, safety, rollout, or acceptance.
+
+- Group at most three related questions per turn.
+- Offer meaningful choices when alternatives are known; otherwise ask concise free-form questions.
+- Ask in the user's language.
+- Do not require owner, team, ticket, API, risk-count, or timeline fields merely to satisfy a template.
+- If an unknown is non-blocking, record it in Open Questions with its decision deadline or owner when known.
+- If a blocking unknown cannot be resolved, stop before claiming the design is decision-complete.
+
+## Language And Terminology
+
+Write the TDD in the language of the user's request unless they specify another language. Preserve code identifiers, protocol names, product names, and established domain terms. Translate headings naturally rather than using a fixed translation table.

package/skills/massa-ai/references/tdd/document-contract.md

@@ -0,0 +1,136 @@
+# TDD Document Contract
+
+Load this reference when drafting or revising a TDD. Use the smallest set of sections that makes the design decision-complete; headings may be renamed to match the user's language and project conventions.
+
+## Core Sections
+
+Every TDD must cover these concerns, though Compact documents may combine sections:
+
+1. **Title And Metadata:** status, actual created/updated dates, owner and related artifacts only when known.
+2. **Context And Current State:** existing behavior, affected domain, evidence inspected, and why the design is needed now.
+3. **Problem, Goals, And Non-Goals:** outcome, measurable acceptance where known, explicit scope, and excluded work.
+4. **Constraints And Assumptions:** technical, product, operational, organizational, compatibility, and regulatory constraints; label assumptions by evidence state.
+5. **Proposed Design:** component responsibilities, ownership boundaries, interactions, state transitions, data flow, and failure behavior.
+6. **Contracts And Data:** only relevant APIs, events, schemas, storage ownership, consistency, idempotency, concurrency, versioning, and error semantics.
+7. **Decisions And Rationale:** important selected approaches, alternatives rejected, trade-offs, consequences, and reversibility. Link a separate ADR when a decision deserves an independent durable record.
+8. **Risks And Mitigations:** concrete technical, delivery, operational, dependency, and adoption risks with impact, likelihood, detection, mitigation, and accepted residual risk where useful.
+9. **Verification Strategy:** acceptance criteria and the unit, integration, contract, end-to-end, migration, performance, security, or operational checks needed to prove them.
+10. **Implementation And Delivery Plan:** ordered phases, dependencies, ownership when known, verification gates, rollout sequence, and stop conditions. Avoid fictional estimates.
+11. **Decisions Revised During Implementation:** living-document log for decisions changed after implementation reveals new evidence.
+12. **Pre-Merge TDD Fidelity Check:** final checklist proving implementation still matches the TDD or documents intentional divergence.
+13. **Open Questions:** unresolved decisions that materially affect implementation, including owner or decision point when known.
+
+## Test Strategy Checklist
+
+When a TDD includes downstream implementation work, the Verification Strategy must include a test file checklist table with these exact columns:
+
+| Done | Test File | Source Set / Location | Action | Coverage Target | Gate Command |
+|---|---|---|---|---|---|
+| [ ] | `<path>` | `<sourceSet or repo equivalent>` | `amplify in existing location: <path> (<sourceSet>)` or `create in <sourceSet>: <path>` | `<behavior or risk>` | `<command>` |
+
+Use the `Done` checkbox as a pre-merge gate. Before choosing a source set, inspect existing test files and source-set configuration. When a relevant test already exists, specify `amplify in existing location: <path> (<sourceSet>)`. Create a new test only after evidence supports the source set and path; write `create in <sourceSet>: <path>`. For Android or Kotlin Multiplatform projects, distinguish `commonTest`, `androidUnitTest`, `unitTest`, or the repository's actual equivalent from build configuration and existing tests rather than defaulting to a preferred source set.
+
+## Implementation Task Table
+
+When a TDD includes downstream implementation work, the Implementation And Delivery Plan must include a reviewable task table with these exact columns:
+
+| Order | PR Group | Layer | PR Size | Included Work | Dependencies | Verification Gate | Jira Key |
+|---|---|---|---|---|---|---|---|
+
+Use one row per reviewable PR group, not one row per incidental file change. A PR group must be independently buildable and testable, with no intermediate state that breaks tests, UI, migrations, public contracts, or required runtime behavior. If a group would be 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 and reviewable.
+
+Use these PR sizes exactly:
+
+- **Small:** `1-200 LOC / 1-3 files`. Prefer Small PRs, with a sweet spot under 50-100 LOC when practical.
+- **Medium:** `201-500 LOC / 3-10 files`. Use Medium only when splitting further would break buildability, testability, UI coherence, or implementation dependency order.
+- **Large:** `500+ LOC / 10+ files`. Treat Large as an exception and include explicit split, stacked PR, feature-flag, or other containment rationale in `Included Work` or `Dependencies`.
+
+Order non-breaking groups by layer when applicable: `Data`, then `Domain`, then `Presentation/Navigation`. Data covers DTOs, DAOs, data sources, repositories, analytics, persistence, and data-layer interfaces. Domain covers use cases, models, mappers, configs, exceptions, monitoring, and business rules. Presentation/Navigation covers 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 the table.
+
+`Jira Key` must contain only a confirmed Jira key, `Not requested`, `Unavailable`, or `Pending`. Never invent ticket keys, links, owners, estimates, or approvals.
+
+## Parallel Rendering Surfaces
+
+When a method, class, enum type, sealed type, mapper, state, or model affects UI/UX, include an affected surfaces checklist before finalizing scope:
+
+| Done | Affected Symbol | Rendering Surface / Mapper | Consumption Path | Required Update | Verification |
+|---|---|---|---|---|---|
+| [ ] | `<method/class/enum/type>` | `<screen/composable/view/mapper>` | `<file or reference path>` | `<change or none>` | `<test or review gate>` |
+
+Enumerate all discovered parallel rendering surfaces and mappers that consume the symbol. Mark a surface `none` only with evidence, such as reference search, mapper inspection, or platform/source-set ownership.
+
+## Strings Audit
+
+Run a pre-TDD `Strings Audit` when mappers branch on a type and call `stringResource`. Record the branch condition, type values, string keys/resources, fallback behavior, localization impact, and affected rendering surfaces before proposing production or test work. If the repository has no matching mapper or no `stringResource` usage in scope, state that the audit was not applicable with the evidence used.
+
+## Decisions Revised During Implementation
+
+Keep this section in every TDD that includes downstream implementation work. It starts empty in the draft and is updated as implementation reveals new facts; do not silently rewrite the original decision as if it was always known.
+
+| Date | Original Decision | New Evidence | Revised Decision | Impact | Follow-up |
+|---|---|---|---|---|---|
+| `TBD` | `TBD` | `TBD` | `TBD` | `TBD` | `TBD` |
+
+## Pre-Merge TDD Fidelity Check
+- [ ] All planned test files exist
+- [ ] All planned production changes implemented
+- [ ] Divergences documented with rationale
+- [ ] Extra scope listed with justification
+- [ ] Decision revisions noted
+
+## Conditional Concerns
+
+Include a dedicated section or explicit subsection when evidence triggers it:
+
+Security, privacy, migration, compatibility, and production-operability concerns are conditional by context but mandatory when their trigger applies.
+
+| Trigger | Required concerns |
+|---|---|
+| Authentication, authorization, secrets, payments, PII, regulated data | threat boundaries, abuse cases, least privilege, data classification, retention/deletion, secret handling, auditability, compliance assumptions, security verification |
+| Production behavior or customer-facing rollout | metrics, logs, traces, dashboards, alert conditions, ownership, rollout stages, rollback or forward-recovery triggers, post-release verification |
+| Schema change, backfill, storage move, or protocol migration | compatibility window, expand/migrate/contract ordering, data validation, restartability, idempotency, dual-read/write risks, cutover, recovery, decommission criteria |
+| External or cross-service integration | dependency ownership, versioning, timeout/retry/circuit behavior, rate limits, failure isolation, contract tests, degraded behavior |
+| Public API, event, SDK, CLI, or persisted-format change | compatibility policy, versioning, deprecation, consumer migration, error semantics, rollout coordination |
+| Performance or availability-sensitive path | workload assumptions, budgets or SLOs when known, capacity/scaling behavior, load and failure tests, bottlenecks, cost trade-offs |
+| User-visible behavior | user flows, accessibility/localization impacts, analytics or success signals, release and support implications |
+| Material alternative or hard-to-reverse choice | alternatives considered, decision criteria, why the selected approach wins, reversal cost |
+
+Testing is never optional as a concern, but its depth scales to risk. Rollback is not always technically possible; document forward recovery, containment, restore, or compensating actions instead of falsely promising reversible migrations.
+
+## Detail Boundary
+
+Include exact details when they are part of the contract or necessary to prevent incompatible implementations:
+
+- endpoint methods, message/event names, request/response shapes, status and error semantics
+- schema fields, ownership, constraints, indexes, consistency, retention, and migration invariants
+- module or file boundaries when the current repository makes them stable and relevant
+- algorithms, state machines, ordering, concurrency, idempotency, retry, and timeout behavior
+- feature-flag, rollout, compatibility, and observability contracts
+
+When the TDD proposes names for modules, states, events, schemas, fields, or public contract identifiers, follow `references/naming-standards.md`: use domain or precise role vocabulary supported by evidence, keep public/persisted compatibility explicit, and mark uncertain domain names as proposed rather than verified facts.
+
+Exclude full production implementations, long command transcripts, decorative boilerplate, and framework syntax that does not express a durable constraint. Small pseudocode, tables, or schemas are acceptable when they clarify behavior better than prose.
+
+## High-Level vs Implementation
+
+The durable design states what must hold; implementation detail records how the current codebase satisfies it. Durable design statements survive framework, library, and tooling changes; implementation detail belongs in the task table or inline task notes, not in the durable design prose. The following framework-migration litmus test separates the two.
+
+Framework-migration litmus test: ask "If we change frameworks, does this statement still apply?" If yes, it is high-level design and belongs in the Proposed Design or Contracts And Data sections. If no, it is implementation detail and belongs in the implementation task table, not the durable design.
+
+Worked pairs (BAD = implementation detail leaking into the durable design; GOOD = high-level design intent):
+
+- BAD: "Use Spring's `@Transactional` on the service method." (Framework-specific; fails the litmus test.) GOOD: "The transfer must be atomic across both account writes; partial writes must roll back." (Survives a framework change; names the invariant.)
+- BAD: "Expose the endpoint via a Retrofit `@POST` interface." (Library-specific; fails the litmus test.) GOOD: "The client submits the request over HTTPS with idempotency-key semantics; duplicate retries must not double-apply the operation." (Survives a client-library change; names the contract.)
+
+Use implementation-detail statements freely in the task table's `Included Work` and verification gates; keep the durable design prose to statements that pass the litmus test.
+
+## Diagram Policy
+
+Use diagrams for multi-component interactions, state transitions, deployment topology, or migration sequencing. Keep diagrams evidence-backed and consistent with the prose. A diagram is not mandatory when a table or short flow is clearer.
+
+## Anti-Fabrication Rules
+
+- Do not insert example vendors, tools, endpoints, tables, metrics, thresholds, dates, or team names into the final document unless the project uses them or they are clearly labeled proposals.
+- Do not mandate arbitrary counts such as three risks, three in-scope items, two paragraphs, or one API endpoint.
+- Do not claim compliance from generic controls; identify applicable obligations as verified, proposed, or unresolved.
+- Do not claim approval, completed reviews, configured alerts, tested rollback, or production readiness without evidence.

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

@@ -0,0 +1,83 @@
+# TDD Quality And Lifecycle
+
+Load this reference before challenging, finalizing, saving, or updating a TDD.
+
+## Quality Gate
+
+The document is decision-complete only when an implementer can proceed without inventing architecture or contract decisions. Verify:
+
+- The problem, goals, non-goals, scope, and constraints agree with approved product or RFC direction.
+- Current-state claims and proposed changes are distinguishable and evidence-backed.
+- Component ownership, interactions, data authority, contracts, and failure behavior are explicit where relevant.
+- Important choices include rationale, trade-offs, consequences, and compatibility impact.
+- Security, privacy, migration, production, integration, performance, and user-facing concerns are included when triggered.
+- Risks include detection and concrete mitigation rather than generic warnings.
+- Verification maps to goals, contracts, failure modes, and migration invariants.
+- Verification includes a test file checklist with `Done`, `Test File`, `Source Set / Location`, `Action`, `Coverage Target`, and `Gate Command` when implementation work is planned.
+- Planned tests specify `amplify in existing location: <path> (<sourceSet>)` for existing tests or `create in <sourceSet>: <path>` for new tests, backed by inspected source-set evidence such as `commonTest`, `androidUnitTest`, `unitTest`, or the repository's actual equivalent.
+- Implementation phases are ordered by dependency and include gates, rollout, and stop conditions.
+- Implementation task tables use the exact columns `Order`, `PR Group`, `Layer`, `PR Size`, `Included Work`, `Dependencies`, `Verification Gate`, and `Jira Key` when implementation work is planned.
+- PR groups are independently buildable and testable. Small PRs are preferred, Medium PRs have a dependency or coherence reason, and Large PRs include split, stacked PR, feature-flag, or containment rationale.
+- Non-breaking implementation groups are ordered Data, Domain, then Presentation/Navigation, or the TDD explicitly maps those labels to the repository's actual boundaries.
+- Jira creation remains delegated to `workflows/ticket.md`; `Jira Key` contains only confirmed keys, `Not requested`, `Unavailable`, or `Pending`.
+- UI/UX-affecting symbol changes include a parallel rendering surfaces and mappers checklist, or explicitly state why none apply.
+- A `Strings Audit` is present when scoped mappers branch on a type and call `stringResource`, or the TDD records evidence that the audit was not applicable.
+- `Decisions Revised During Implementation` is present for living implementation updates.
+- `Pre-Merge TDD Fidelity Check` is present and all checkboxes are resolved before merge.
+- Unknowns are explicit; no placeholder is presented as a decided fact.
+- The document contains no fabricated approvals, estimates, metrics, vendors, or project details.
+
+If a blocking item fails, revise the draft or ask the user. Non-blocking gaps remain visible under Open Questions.
+
+## 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.
+
+Challenge at least:
+
+- the assumption most likely to invalidate the design
+- boundary, ownership, or dependency failures
+- data-loss, compatibility, migration, and rollback/forward-recovery risks
+- operational detection gaps and untestable success claims
+- implementation sequencing that creates an unsafe intermediate state
+- PR grouping that hides multiple independent outcomes, creates a Large PR without containment, or relies on fabricated Jira keys
+- planned test files that are missing, assigned to unverified source sets, or not reflected in the pre-merge fidelity checklist
+- UI/UX parallel rendering surfaces, mapper branches, or string resources that can drift from the production change
+
+Revise valid critical or high findings before presentation. Keep accepted residual risks explicit.
+
+## Lifecycle
+
+Use honest document states:
+
+- **Draft:** design is being developed or has unresolved blocking review.
+- **In Review:** decision-complete draft awaits named review or approval.
+- **Approved:** use only after explicit human approval is available in the current context or authoritative project records.
+- **Superseded:** retain a pointer to the replacement when project convention preserves design history.
+
+When updating an existing TDD:
+
+1. Read the current document and its linked decisions.
+2. Identify what evidence or requirement changed.
+3. Preserve still-valid constraints and rationale.
+4. Add material implementation-time changes to `Decisions Revised During Implementation` instead of rewriting history.
+5. Reconcile the test file checklist, source-set actions, parallel rendering surfaces, `Strings Audit`, and `Pre-Merge TDD Fidelity Check`.
+6. Update the date and status honestly.
+7. Summarize material design changes and newly invalidated assumptions.
+
+Do not silently replace an existing TDD, erase unresolved risks, or rewrite history to make the new design appear previously approved.
+
+## Artifact And Completion
+
+Follow an explicit path or established repository convention. Otherwise use `docs/design/<entity>.md`. Create only directories required for the approved artifact.
+
+Before completion:
+
+1. Check Markdown structure and local links.
+2. Validate Mermaid syntax when diagrams are present and tooling exists.
+3. Run repository-specific documentation or schema checks when available.
+4. Confirm stale statements or placeholders are not presented as final decisions.
+5. Persist only durable decisions after recall, deduplication, and scoring.
+6. Complete the shared Evidence Gate.
+
+Report the artifact path and status, depth selected, conditional concerns included, challenge revisions, unresolved questions, deterministic checks, memory outcome, and residual risk.

package/skills/massa-ai/references/the-fool/cognitive-bias-inventory.md

@@ -0,0 +1,103 @@
+# Cognitive Bias Inventory
+
+Structured bias detection for use during every challenge pass. Integrates findings from Fasolo, Heard & Scopelliti (2025) and the DeBiasMe metacognitive framework.
+
+## Core Principle
+
+Cognitive biases are not accusations — they are patterns in human reasoning that systematically distort judgment. The Fool's job is to flag when a bias may be influencing a decision, not to shame the user. Frame bias findings as: "This pattern is common in this type of decision, and here's how it might be affecting your reasoning."
+
+## When to Use This File
+
+Read this file on every challenge pass, regardless of mode. After generating your mode-specific challenges, scan the user's reasoning against this inventory. Weave bias findings into your challenges — do not present them as a separate "bias report."
+
+## The Primary Bias Inventory
+
+### Decision-Making Biases
+
+| Bias | Description | Detection Signal | Debiasing Technique |
+|------|-------------|-----------------|---------------------|
+| **Confirmation bias** | Seeking evidence that confirms existing belief | Only positive evidence cited; no counter-evidence considered | "What evidence would you need to see to change your mind?" |
+| **Anchoring** | Over-relying on first piece of information | First estimate unchanged despite new data; round numbers dominate | "Generate your own estimate BEFORE looking at others" |
+| **Sunk cost fallacy** | Continuing because of past investment | "We've already spent 6 months on this" as justification to continue | "If you were starting fresh today with no prior investment, would you choose this?" |
+| **Status quo bias** | Preferring current state despite evidence for change | "It's always been this way" or "changing is risky" without quantifying | "What is the cost of NOT changing? Is doing nothing really free?" |
+| **Overconfidence** | Overestimating the accuracy of one's predictions | Point estimates instead of ranges; no contingency planning | "Give me a confidence interval: what's the 10th and 90th percentile outcome?" |
+| **Planning fallacy** | Underestimating time, cost, and risk of future actions | Best-case estimates presented as likely; no buffer for unknowns | "What happened the last 3 times you estimated something similar?" |
+
+### Social and Group Biases
+
+| Bias | Description | Detection Signal | Debiasing Technique |
+|------|-------------|-----------------|---------------------|
+| **Groupthink** | Desire for conformity suppresses dissent | "The whole team agrees" with no documented dissent | "Was there a moment where someone almost disagreed? What stopped them?" |
+| **Authority bias** | Deferring to authority regardless of evidence quality | "The CTO/architect/Google says so" as primary evidence | "If this proposal came from a junior engineer, would the evidence be sufficient?" |
+| **Bandwagon effect** | "Everyone is doing it" as justification | Trend adoption without fitness assessment | "Is the reason everyone is doing it the same reason you should?" |
+| **Survivorship bias** | Focusing on successes, ignoring failures | "All the successful companies do X" | "How many companies tried X and failed? What happened to them?" |
+
+### Information Processing Biases
+
+| Bias | Description | Detection Signal | Debiasing Technique |
+|------|-------------|-----------------|---------------------|
+| **Availability heuristic** | Overweighting recent or vivid examples | Decision based on one memorable incident | "What does the base rate data say? Is this incident representative or exceptional?" |
+| **Dunning-Kruger** | Overconfidence in unfamiliar domain | Confident claims about areas outside expertise | "How much experience does the team have with this specific technology at this scale?" |
+| **Framing effect** | Decision changes based on how the question is framed | Positive framing hiding negatives (or vice versa) | "Reframe: instead of '90% success rate,' say '10% failure rate.' Does that change the decision?" |
+| **Recency bias** | Overweighting recent events | Last quarter's incident driving architecture decisions | "Is this a trend or an outlier? What does the 12-month data show?" |
+| **Narrative fallacy** | Creating a coherent story from random events | Clean cause-and-effect narrative with no uncertainty | "What parts of this story are we connecting retroactively?" |
+
+## Bias Detection Workflow
+
+For each challenge pass, run this quick scan:
+
+### Step 1: Check the Evidence Chain
+
+- Is evidence selectively presented? → **Confirmation bias**
+- Is the first data point dominating the analysis? → **Anchoring**
+- Is a single vivid example driving the decision? → **Availability heuristic**
+- Is the source of evidence interested in the outcome? → **Authority bias** or **vendor bias**
+
+### Step 2: Check the Decision Frame
+
+- Is past investment being used to justify continuing? → **Sunk cost fallacy**
+- Is the status quo being treated as free? → **Status quo bias**
+- Are estimates point values instead of ranges? → **Overconfidence**
+- Is the timeline based on best-case? → **Planning fallacy**
+
+### Step 3: Check the Social Dynamics
+
+- Did "everyone agree" suspiciously fast? → **Groupthink**
+- Is a senior person's opinion treated as evidence? → **Authority bias**
+- Is "industry trend" the primary justification? → **Bandwagon effect**
+- Are only success stories referenced? → **Survivorship bias**
+
+## Bias Mitigation Techniques Summary
+
+These are the gold-standard debiasing techniques (Fasolo et al. 2025, Nature Scientific Reports 2025):
+
+| Technique | What It Does | When to Apply |
+|-----------|-------------|---------------|
+| **Reference class forecasting** | Use historical base rates instead of inside-view estimates | Any predictive claim or timeline estimate |
+| **Pre-mortem** | Imagine failure first | Planning fallacy, overconfidence |
+| **Red team / devil's advocate** | Structural dissent | Groupthink, confirmation bias |
+| **Blind evaluation** | Strip names, titles, vendors from proposals | Authority bias, halo effect |
+| **Probabilistic framing** | Force confidence intervals and probability ranges | Overconfidence, binary thinking |
+| **Fresh-start framing** | "If starting today with no history, would you choose this?" | Sunk cost, status quo bias |
+| **Inversion** | "What would guarantee failure?" | Confirmation bias, planning fallacy |
+| **Seek disconfirming evidence** | Actively look for evidence AGAINST your position | Confirmation bias |
+| **The Magic Question** | "What would it take to change your mind?" | All biases — tests commitment to evidence |
+
+## Integration with Modes
+
+| Mode | Most Common Biases to Check |
+|------|---------------------------|
+| Socratic Questioning | Confirmation bias, framing effect, narrative fallacy |
+| Dialectic Synthesis | Status quo bias, authority bias, groupthink |
+| Pre-mortem Analysis | Planning fallacy, overconfidence, survivorship bias |
+| Red Team | Availability heuristic, anchoring, Dunning-Kruger |
+| Evidence Audit | Confirmation bias, survivorship bias, authority bias |
+
+## Anti-Patterns in Bias Communication
+
+| Anti-Pattern | Problem | Better Approach |
+|-------------|---------|-----------------|
+| "You have confirmation bias" | Accusatory, triggers defensiveness | "I notice the evidence cited is all supportive — what does the counter-evidence look like?" |
+| Listing 10 biases at once | Overwhelms, loses impact | Flag the 1-2 most relevant biases, woven into specific challenges |
+| Using bias as a trump card | "You're biased therefore wrong" | Bias affects the reasoning process, not necessarily the conclusion |
+| Naming the bias first | Academic tone alienates | Describe the pattern, then (optionally) name it |