@massa-ai/cursor-plugin 1.6.0

package/skills/massa-ai/workflows/security/security-audit.md

@@ -0,0 +1,113 @@
+### Security Audit
+
+Use this workflow for findings-only security review in a concrete target: modified files, explicit files/globs, commit ranges, branch comparisons, modules/packages, symbols/classes/functions, feature/runtime flows, explicitly requested whole-repo scope, or an implementation scope packet supplied by `workflows/implementation/implementation-audit.md`.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Do not use this workflow for generic correctness bugs; route those to `workflows/bugs/bugs-audit.md`. Do not use it for broad architecture, code quality, requirements, or test coverage audits; route those to their dedicated workflows.
+
+This workflow is findings-only. Do not edit code unless the user separately asks for fixes.
+
+1. Resolve/reuse `workflowSessionId`: `security-[entity]`
+2. Load shared references:
+   - `references/codebase-investigation.md`
+   - `references/audit-scope.md`
+   - `references/audit-report-io.md` before writing the final direct audit report
+   - `references/mobile-context.md` when the scope touches KMP, iOS, Android, native bridges, mobile permissions, secure storage, biometrics, deep links, push/background behavior, local persistence, offline queues, logs/crash privacy, or backend-mobile contracts
+   - `references/context-firewall.md` before inspecting large diffs, logs, snapshots, generated reports, or broad search output
+   - `references/synapse-policy.md` when repeated massa-ai searches are expected
+   - `references/agent-orchestration.md` only for large scopes, explicit parallel/subagent requests, PR subagent invocation, or independent verification of high-impact findings
+3. `recall` -> load prior security decisions, auth boundaries, validation rules, known regressions, project constraints, ADRs, fragile flows, and accepted exceptions for the target area.
+   - Apply the Memory Freshness Gate from `references/audit-scope.md`; recalled exceptions are leads, not proof.
+4. Establish the investigation scope before proceeding:
+   - Modified files scope: use when the user says modified files, changed files, current changes, uncommitted changes, staged changes, or unstaged changes.
+   - Explicit files/globs scope: use when the user names files, directories, or globs.
+   - Commit range scope: use when the user provides commits/ranges or asks for commits made by me, my branch commits, or security issues introduced by branch commits.
+   - Branch comparison scope: use when the user names base/head branches, refs, or a branch diff.
+   - Codebase area scope: use when the user names a path, module, package, feature area, trust boundary, or glob.
+   - Symbol/class/function scope: use when the user names handlers, middleware, validators, policies, classes, functions, or exported surfaces.
+   - Feature/flow scope: use when the user names a runtime flow, user journey, auth path, or data boundary.
+   - Whole-repo scope: use only when the user explicitly asks for a whole-repo security audit.
+   - Implementation parent scope: use only when `workflows/implementation/implementation-audit.md` invokes this workflow with a concrete implementation scope packet.
+   - If the target focus is missing, vague, or too broad, ask for a concrete target from the supported scope types in `references/audit-scope.md`.
+   - Build the shared scope packet from `references/audit-scope.md` and carry it into the report.
+5. For modified files scope:
+   - Include staged and unstaged tracked files from the working tree.
+   - Include untracked non-generated source, test, fixture, schema, config, and docs files only when they can affect runtime or validation behavior.
+   - Exclude deleted files unless their deletion can break imports, exports, routing, migrations, config, tests, packaging, secrets handling, or policy enforcement.
+   - Exclude generated, dependency, build, log, cache, temporary, and secret paths per repo rules.
+   - Inspect diffs first, then only the surrounding code needed to understand security behavior.
+6. For commit range scope:
+   - If the user supplied explicit commits or a revision range, use that exact range.
+   - If the user asked for commits made by me, resolve author identity from `git config user.email`; if empty, use `git config user.name`.
+   - For branch-relative commit scopes, resolve the branch base from the upstream merge-base first, then fall back in order to `origin/main`, `origin/master`, `main`, and `master`.
+   - If the user asked for commits made by me, review branch-unique commits authored by the resolved identity.
+   - If no explicit range, required author identity, or branch base can be resolved, ask the user for the missing value before proceeding.
+   - Inspect changed files and diffs from those commits, then auth boundaries, callers, tests, config, schemas, and policy definitions only as needed.
+7. For codebase area scope:
+   - Require a concrete path, module, package, feature area, or glob.
+   - If the target area is missing, ask for it before proceeding.
+   - Follow the shared retrieval order from `references/codebase-investigation.md` to find entry points, trust boundaries, policy checks, validators, tests, and adjacent config.
+8. For explicit files/globs, branch comparison, symbol/class/function, feature/flow, or explicitly requested whole-repo scope:
+   - Resolve the target with `references/audit-scope.md` and record the resolution method, base/head when relevant, resolved files, exclusions, and freshness timestamp.
+   - For symbol/class/function targets, inspect definitions, call paths, trust boundaries, validators, policies, tests, config, and schemas only as needed.
+   - For feature/flow targets, trace untrusted input, identity, authorization, validation, persistence, side effects, and logs through the named flow.
+   - If whole-repo scope is requested, map major trust boundaries first and report skipped depth checks rather than implying exhaustive review.
+9. For implementation parent scope:
+   - Accept the exact scope packet from `implementation-audit`; do not broaden beyond resolved files, surrounding code, called auth/validation helpers, config, schemas, and tests needed to verify a security claim.
+   - Return compact findings to the parent implementation audit; do not write broad project memories unless explicitly assigned.
+10. Investigation pass. Dispatch `audit-specialist` per `references/agent-orchestration.md` when the scope justifies an isolated read-only subagent:
+
+> **Dispatch: `massa-ai-audit-specialist`** (role: `audit-specialist`) — charter `skills/agents/audit-specialist/SKILL.md`
+> - trigger: large scope, explicit parallel/subagent request, PR subagent invocation, or independent verification of high-impact finding
+> - scope: the security audit target — files, trust boundaries, auth paths, validators
+> - permissions: read-only
+> - inputs: shared scope packet; `lens: security`; recalled security decisions, auth boundaries, validation rules, accepted exceptions
+> - sensors: trace untrusted input -> validation -> authorization -> transformation -> persistence; authn/authz, object ownership, tenant isolation, input validation, secret handling, injection risks
+> - output: findings with security boundary, asset, trigger/exploit path, severity, confidence, evidence, simplest fix direction, verification suggestion
+> - firewall: raw diffs/logs/search output summarized, not returned raw
+> - memory: suggest-only; main agent persists reusable security patterns
+
+    - Trace untrusted input -> validation -> authorization -> transformation -> persistence or side effect.
+   - Check authn/authz, object ownership, tenant isolation, input validation, output encoding, secret handling, cryptography use, SSRF/path traversal/injection risks, logging privacy, dependency/config exposure, and security-sensitive tests.
+   - For mobile scopes, check secure storage/keychain/keystore use, permission states, deep links and auth guards, push token handling, biometrics, local DB/cache and offline queues, logs/crash reports/screenshots, native bridge payload trust, and backend-mobile contract skew from `references/mobile-context.md`.
+   - For each candidate finding, record the concrete claim, source evidence, impacted asset or boundary, likely trigger, provisional severity, and what would disprove it.
+11. False-positive pass:
+   - Try to disprove every candidate before reporting it.
+   - Check guards, framework defaults, policy layers, middleware order, type checks, tests, feature flags, call paths, existing invariants, ADRs, and accepted exceptions.
+   - Use official docs or web research only when current external API, framework, or security behavior matters.
+   - Drop candidates disproven by evidence, downgrade candidates with partial mitigation, and mark low-confidence findings explicitly.
+12. Severity rules (apply the countable threshold first, then the qualitative clause):
+   - `critical`: likely auth bypass, privilege escalation, data exfiltration, secret exposure, remote code execution, tenant break, irreversible data corruption, OR affects >10 files; otherwise use the qualitative clause below.
+   - `high`: likely missing authorization, injection risk, sensitive data leak, broken security boundary, unsafe deserialization, or severe config exposure.
+   - `medium`: real edge-flow security bug, incomplete validation, privacy leak with limited scope (<=10 affected files), weak cryptographic/config practice with plausible exploitation, or meaningful test gap around security logic.
+   - `low`: defensive hardening opportunity, low-impact information exposure, incomplete evidence, or weakly supported concern.
+13. Final report:
+   - Findings first, ordered by severity: `critical`, `high`, `medium`, `low`.
+   - Each finding must use `SEC-<N>` and include the canonical fields from `references/audit-report-io.md`: severity, confidence, file/line, evidence, security boundary, asset, trigger or exploit path, negative test direction, simplest fix direction, and verification suggestion.
+   - If no security findings are found, say that clearly and list scope checked plus skipped checks.
+   - Include ruled-out candidates when they were plausible enough to matter.
+   - Include scope checked, deterministic evidence or skipped-check notes, memory outcome, and residual risk.
+   - Include the Verification/Test Fidelity Checklist from `references/audit-report-io.md`; tie every `SEC-*` finding or no-finding claim to deterministic sensors, commands/artifacts, results, validation assets, or skipped-check reasons. Model judgment alone cannot satisfy verification/testing all-clear.
+   - For direct top-level invocation, use the Plan Mode save rule and canonical report contract from `references/audit-report-io.md` for `audits/security/<YYYY-MM-DD security-audit>.md`.
+   - For implementation audit child invocation, return compact findings to the parent unless the parent explicitly requests saved audit artifacts.
+14. Persist only durable knowledge:
+   - Do not persist one-off findings.
+   - Persist repeated security patterns, project-specific security boundaries, accepted exceptions, or reusable verification recipes after scoring with the Importance Calibration System.
+   - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:security-audit`, `entity:<entity>`, and one `memory:<tier>` tag.
+15. Complete the Evidence Gate from `references/evidence-gate.md`.
+
+## Examples
+
+User asks: "Audit modified files for security issues."
+
+1. Use `workflowSessionId=security-modified-files`.
+2. Scope to staged, unstaged, and relevant untracked files; exclude generated/dependency/build/log/cache/secret paths.
+3. Inspect diffs first, then auth, validation, secret handling, config, and tests around the changed code.
+4. Run a false-positive pass before reporting findings.
+
+User asks: "Audit src/auth for security risks."
+
+1. Use `workflowSessionId=security-auth`.
+2. Scope to `src/auth` and adjacent policy, middleware, config, schema, and tests needed to verify claims.
+3. Report findings by severity with confidence, evidence, impact, and verification suggestions.

package/skills/massa-ai/workflows/security/security-fix.md

@@ -0,0 +1,97 @@
+### Security Fix
+
+Use this workflow only to execute fixes from a security audit markdown report.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+Do not use this workflow for findings-only security review; route that to `workflows/security/security-audit.md`. Do not use it for generic correctness fixes unless the security report identifies the correctness issue as part of an exploitable path.
+
+1. Resolve/reuse `workflowSessionId`: `security-fix-[entity]`
+2. Load shared references:
+   - `references/audit-report-io.md` before any code change
+   - `references/lessons.md` to load confirmed project lessons
+   - `references/codebase-investigation.md` before changing unfamiliar security boundaries
+   - `references/mobile-context.md` when the report target touches KMP, iOS, Android, native bridges, mobile permissions, secure storage, biometrics, deep links, push/background behavior, local persistence, offline queues, logs/crash privacy, or backend-mobile contracts
+   - `references/verification-ladder.md` before non-trivial edits
+   - `references/context-firewall.md` before inspecting large diffs, logs, generated reports, or broad search output
+   - `references/agent-orchestration.md` only for large/high-risk findings, disjoint implementation slices, or independent verification
+3. `recall` -> load auth boundaries, tenant rules, validation conventions, secret-handling policies, accepted exceptions, prior incidents, and verification recipes for the report target.
+4. Select the security audit report with execution focus:
+   - Establish the report selector, target focus, and optional finding selector before selecting a report. Target focus can be a trust boundary, route, module, flow, files/globs, branch comparison, commit range, symbol/class/function, or explicit whole-repo target.
+   - If the user gives a path, read that exact markdown file.
+   - If the user asks for "latest" or gives no path, require a concrete target focus first; do not run the latest security report against an unspecified target.
+   - Select the latest `audits/security/<YYYY-MM-DD security-audit>.md` only after target focus is known, using `references/audit-report-io.md`.
+   - Stop if no report exists; do not infer findings from conversation history.
+   - Validate the report with `references/audit-report-io.md`: workflow, `ProjectId`, `Target`, `Target Focus`, scope, git base/head, required fields, `SEC-` IDs, resolved files or material scope evidence, and current file/line evidence. Stop on invalid, stale, target-drifted, or ambiguous reports before editing.
+5. Extract actionable findings:
+   - Keep findings with concrete `Security Boundary`, `Asset`, `Location`, `Evidence`, exploit path or trigger, `Negative Test Direction`, `Simplest Fix Direction`, and `Verification Suggestion`.
+   - Ignore ruled-out candidates, no-finding sections, and low-confidence hardening ideas unless the user explicitly asks to include them.
+   - If the user supplied finding IDs, extract only those IDs after validating they exist and match the current target focus.
+   - Rank by exploitability, severity, affected asset, dependency order, and regression risk.
+6. Build a threat-model fix map before editing:
+   - Finding ID -> attacker or misuse path, trust boundary, missing/weak guard, data asset, required invariant, negative test, and rollback path.
+   - Identify whether the fix belongs in authentication, authorization, ownership/tenant isolation, validation, output encoding, persistence, logging, crypto, config, or tests.
+   - For mobile findings, identify whether the fix belongs in secure storage, permission handling, deep-link routing, push/background token handling, biometric fallback, local persistence/offline queue, logs/crash privacy, native bridge payload validation, or backend-mobile contract hardening.
+7. Size each finding with `references/verification-ladder.md`:
+   - Quick: local guard, schema validation, log redaction, config hardening, or focused negative test.
+   - Standard: policy-layer change, middleware ordering, ownership rule, public API validation, data-access guard, or multi-file regression coverage; define verification recipe first.
+   - Spec-driven: security model redesign, role model change, tenant model migration, crypto migration, or behavior change needing stakeholder approval; pause and route to `workflows/spec-driven.md` or ask for approval.
+8. Apply security fixing methods:
+   - Authentication: fail closed on missing/invalid identity, preserve session/token invariants, and avoid bypass paths.
+   - Authorization: enforce permission checks at stable boundaries, verify object ownership and tenant isolation, and deny by default.
+   - Validation: validate untrusted input before transformation or persistence; prefer schema or framework validators over ad hoc checks.
+   - Output and privacy: encode or sanitize outputs, redact secrets and sensitive personal data from logs/errors, and avoid leaking existence of protected resources.
+   - Injection and traversal: parameterize queries, constrain paths/URLs, validate protocols/hosts, and avoid unsafe deserialization or dynamic execution.
+   - Secrets and crypto: remove hardcoded secrets, use safe config sources, avoid weak algorithms, and preserve key/credential rotation paths.
+   - Mobile trust boundaries: preserve platform parity, fail closed on denied/restricted permissions when security-sensitive, validate native bridge payloads before trust, redact local logs/crash artifacts, and protect tokens or personal data in secure storage and offline queues.
+9. Preserve security intent with tests:
+   - Add or update negative tests for the exploit path when feasible.
+   - Include positive tests for allowed behavior so the fix does not over-block legitimate use.
+   - Do not weaken existing security assertions to make tests pass.
+10. Use agent orchestration only when it improves signal. Dispatch per `references/agent-orchestration.md`:
+
+> **Dispatch: `massa-ai-builder`** (role: `builder`) — charter `skills/agents/builder/SKILL.md`
+> - trigger: large/high-risk finding, disjoint implementation slice, or explicit subagent request
+> - scope: one isolated security finding with a disjoint write set
+> - permissions: write (disjoint write set)
+> - inputs: the finding ID, impacted asset/boundary, exploit path, current guards, and simplest fix direction
+> - sensors: report's verification suggestion or equivalent deterministic command; negative tests that attempt to disprove the fix
+> - output: implementation summary, commands run, test counts, deviations
+> - firewall: raw diffs/logs summarized
+> - memory: suggest-only; main agent persists reusable security patterns
+
+> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
+> - trigger: independent verification of a high-risk security fix
+> - scope: the fixed finding's guard restoration, middleware order, redaction, and report claim closure
+> - permissions: read-only
+> - inputs: the finding, the applied fix, the verification suggestion, and validation assets
+> - sensors: deterministic command (negative tests, middleware-order inspection, redaction check) and report claim closure
+> - output: confirmed/disproven closure verdict with evidence
+> - firewall: raw test output/logs summarized
+> - memory: suggest-only; main agent persists reusable verification recipes
+   - Main agent owns report parsing, prioritization, memory writes, final synthesis, and Evidence Gate.
+11. Verify each completed finding:
+   - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
+     `python3 skills/massa-ai/scripts/lessons.py --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
+   - Apply the Mandatory Verification Fix Gate from `references/verification-ladder.md`: run the report's Verification Suggestion or an equivalent deterministic command/artifact check for each selected finding or coherent group.
+   - A finding cannot be marked `fixed` when a target-relevant command or artifact check exists but was not attempted; if verification cannot run, mark it `blocked`, `deferred`, or `skipped` with an allowed skipped-check reason.
+   - Run the report's verification suggestion when available.
+   - Run targeted tests for negative and positive paths, plus lint/type/build checks relevant to touched files.
+   - Inspect logs/config/errors when the finding involves data exposure.
+   - Record command/artifact, result, skipped reason or `none`, highest Verification Ladder level reached, validation assets protected, and residual risk.
+12. At completion, persist only durable knowledge:
+   - Security boundary decisions, accepted exceptions, reusable exploit-path tests, or incident-prevention patterns after scoring with the Importance Calibration System.
+   - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:security-fix`, `entity:<entity>`, and one `memory:<tier>` tag.
+13. Complete the Evidence Gate from `references/evidence-gate.md`.
+
+## Examples
+
+User asks: "Use security-fix to fix latest audit findings for user routes."
+
+1. Confirm target focus is `user routes`, then read the latest matching `audits/security/* security-audit.md`.
+2. Validate metadata, target focus, freshness, required fields, and current evidence before editing.
+3. Fix critical/high exploit paths first.
+4. Add negative tests for denied access, invalid input, or redacted output.
+5. Run deterministic tests and report residual security risk.

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

@@ -0,0 +1,217 @@
+### Spec-Driven
+
+Use this workflow for explicit spec-driven requests and broad, ambiguous, migration-heavy, cross-boundary, public-contract, or long-running delivery that needs requirements-through-verification control. Ordinary localized fixes and clear small features stay in `debug`, `feature`, `refactor`, or `general` unless the user explicitly requests this workflow.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+## TLC v3 Flow
+
+Run the integrated TLC Spec-Driven v3 flow:
+
+`Specify -> (Design) -> (Tasks) -> Execute`
+
+- `Specify` and `Execute` are always required.
+- Validation is the mandatory final Execute gate, not a separate optional phase.
+- `Design` is included for Large/Complex work and whenever architecture, interfaces, data model, migration, security/privacy, public contract, or reusable pattern decisions exist.
+- `Tasks` is included for Large/Complex work and whenever execution has more than 3 obvious linear steps or has dependency, branch, join, parallelism, or sequencing complexity.
+- Large/Complex work must include full requirement IDs, the implicit-requirement sweep, design approach tradeoffs, a task breakdown, and final validation.
+- If a skipped phase becomes necessary later, stop, create or revise the phase artifact, record the safety-valve reason, and resume from the updated contract.
+
+## Execution Contract — Non-Negotiable
+
+Holds for every task, even if reference files are not opened:
+
+1. Tests derive from the spec's acceptance criteria and assert spec-defined outcomes — they never mirror the implementation.
+2. The gate must pass (tests pass) before a task is done — the test runner decides, not self-assessment.
+3. One atomic commit per task. Never batch tasks; never weaken, skip, or delete tests to make them pass.
+4. After the last task, a fresh verification-agent always runs automatically (author ≠ verifier) — spec-anchored outcome check plus discrimination sensor. Never optional, never prompted.
+
+## Auto-Sizing
+
+Complexity determines depth, not a fixed pipeline. Assess scope first, apply only what is needed:
+
+| Scope | What | Specify | Design | Tasks | Execute |
+| --- | --- | --- | --- | --- | --- |
+| Small | ≤3 files, one sentence | One-liner inline | Skip | Skip | Implement + verify inline |
+| Medium | Clear feature, <10 tasks | Brief spec | Skip — inline | Skip — implicit | Implement + verify |
+| Large | >10 tasks OR multi-component feature | Full spec + requirement IDs | Architecture + components | Full breakdown + deps | Implement + verify per task |
+| Complex | Ambiguity or new domain (unfamiliar vocabulary, no prior pattern) | Full spec + discuss gray areas | Research + architecture | Breakdown + phase plan | Implement + interactive UAT |
+
+A "phase" is a group of tasks sharing a dependency boundary or a checkpoint commit — it is distinct from a single task or atomic step. The sub-agent offer fires when a formal `tasks.md` packs into more than one task-budgeted batch (> ~8 tasks).
+
+- Specify and Execute are always required.
+- Design is skipped when straightforward (no architectural decisions, no new patterns).
+- Tasks is skipped when ≤3 obvious steps (implicit in Execute).
+- Discuss runs inside Specify when gray areas or any implicit-requirement dimension is present (persistence/state, external calls, auth, payments, concurrency, state transitions).
+- Interactive UAT runs inside Execute only for user-facing features with complex behavior.
+
+## Quick Mode Guardrails
+
+Quick mode is the Small/auto-sized path: a single change touching **max 3 files** with no new dependency and no design decision. It is the fast lane, not a parallel pipeline — it still closes requirements and runs the Execute gate.
+
+Enter Quick mode only when **all** hold:
+
+- The change touches max 3 files.
+- No new dependency is introduced.
+- No design decision is required (no architecture, interface, data model, migration, security/privacy, or public-contract choice).
+
+Exit Quick mode immediately — run the full Specify → (Design) → (Tasks) → Execute pipeline — when **any** of these appears mid-task:
+
+- A new dependency.
+- Any design decision surfaces.
+- The change grows past max 3 files.
+
+Promote to a feature when **5+ quick tasks** accumulate in one area: that signal means the work has hidden coupling and belongs in a tracked feature with full requirements, not a string of quick fixes. Record the promotion in `.specs/project/STATE.md` and open the feature under `.specs/features/<slug>/`.
+
+Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line intent + acceptance) and a `SUMMARY.md` (files changed + gate evidence). See `references/spec-driven/artifact-store.md` for templates. Quick tasks are listed in the STATE.md Quick Tasks table (see `references/spec-driven/memory.md`).
+
+## Workflow
+
+1. Resolve/reuse `projectId` and `workflowSessionId`: `spec-[entity]`.
+2. Restore context before planning:
+   - `recall` for exact-session continuity, durable decisions, rejected approaches, patterns, blockers, and handoffs.
+   - Load `references/spec-driven/artifact-store.md` before reading or writing feature registry, state, handoff, phase artifacts, validation reports, or lessons.
+   - Load `references/synapse-policy.md` when two or more related searches are expected. When the investigation involves multi-search, call `synapse_task_begin` with `id` (the `synapseSessionId`) and `taskContext` before the first search to open a task envelope; call `synapse_prefetch` with `id` and `filePath` after opening a file for deep investigation to warm the buffer; call `synapse_task_end` with `id` when the investigation phase completes. `synapse_task_begin`/`synapse_task_end` require an existing `synapse_session` id.
+   - Load `references/context-firewall.md` before broad source inspection, generated reports, external research, or verbose tool output.
+   - Keep the loaded context budget under the `references/spec-driven/context-limits.md` target; summarize or narrow before loading bulky artifacts.
+   - Use `references/spec-driven/code-analysis.md` when source inspection needs structural search or tool fallback.
+   - Load current canonical artifacts from `.specs/` files: `.specs/project/FEATURES.json`, `.specs/project/STATE.md`, `.specs/HANDOFF.md`, existing `.specs/features/<slug>/` phase artifacts, lessons, and project source. Current repository source and approved `.specs/` artifacts override stale memory, old handoff notes, external summaries, debug exports, or unapproved generated plans.
+   - `search` only counts as codebase evidence when it is fresh for the current repository path and commit/worktree state, or when the result is confirmed against source files read in this session.
+   - Load confirmed project lessons through `references/lessons.md` when `.specs/lessons.json` exists:
+     `python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed`
+3. Run `Specify` with `references/spec-driven/specify.md`.
+   - Capture stable requirement IDs, testable acceptance criteria, edge cases, and explicit out-of-scope items.
+   - Run `references/spec-driven/discuss.md` inside Specify when gray areas, implicit requirements, persistence/state, external calls, auth, payments, concurrency, or state transitions affect behavior.
+   - For Android, iOS, or KMP Compose Multiplatform UI work, load `references/mobile-context.md` and run the optional design-source gate: ask for one or more Figma links, node IDs, a readable desktop selection, supplied screenshots, or explicit `none`; record `Figma Source: none by user choice` when declined. Screenshots are context-only unless paired with structured Figma evidence. For unsupported targets, record the source as outside mobile Figma scope and do not run mobile Figma.
+   - Apply the Requirement Closure Gate: every open requirement question is resolved with the user or recorded as an accepted assumption before execution begins.
+4. Decide whether `Design` is required. If yes, run `references/spec-driven/design.md`; if no, record why the skip is valid. When Design is skipped and a design concern appears later, stop and create `design.md` before continuing.
+5. Decide whether `Tasks` is required. If yes, run `references/spec-driven/tasks.md`; if no, list the inline atomic execution steps before editing. If the inline list reveals more than 5 steps or complex dependencies, stop and create `tasks.md` — the Tasks phase was wrongly skipped (safety valve).
+6. Run `Execute` with `references/spec-driven/execute.md`.
+   - Load `references/spec-driven/coding-principles.md` before implementation.
+   - Use the Test Coverage Matrix and Gate Check Commands from `tasks.md`, or state their inline equivalents when Tasks was skipped.
+   - Ask the MCP and skill question in Tasks or inline Execute when tool choice can change correctness or verification.
+   - If a formal `tasks.md` packs into more than one task-budgeted batch (> ~8 tasks), present the sub-agent offer from `references/spec-driven/sub-agents.md` before starting Execute. Offer-then-confirm — never auto-spawn; the user must accept before any sub-agent is dispatched. One worker per batch (~7 tasks, whole phases): each batch worker executes all its tasks in order (implement → gate → atomic commit), then reports a compact summary (tasks done, commit hashes, test counts, deviations). Workers never spawn further sub-agents.
+   - Implement one atomic step or approved task at a time.
+   - For long-running task sequences, create a checkpoint via `create_checkpoint` at task boundaries with `taskId`, `description`, `progressPercent`, `currentStep`, `nextAction`, `fileChanges`, and `checkpointType: "manual"` so progress is resumable after interruption.
+   - If resuming after interruption, call `list_checkpoints` with the `taskId` and `restore_checkpoint` to recover task state before continuing. If `create_checkpoint` is unavailable (e.g. `task_checkpoints` table missing), continue with `.specs/` artifact state as the fallback.
+   - Use per-task commits when the environment and user permissions allow commits; otherwise record the skipped reason.
+   - Keep validation assets protected.
+   - Update logical feature artifacts in `.specs/features/<slug>/` and `.specs/project/STATE.md` after meaningful progress.
+    - Finish Execute by running `references/spec-driven/validate.md`. Dispatch `verification-agent` (author ≠ verifier) per `references/agent-orchestration.md`; the verification-agent always runs automatically and writes `.specs/features/<slug>/validation.md`. Without subagents, run the standalone fresh-eyes fallback in `validate.md`.
+
+> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
+> - trigger: spec-driven Execute final gate; author ≠ verifier independence required
+> - scope: the feature's git diff surface, test files, and spec ACs
+> - permissions: read-only
+> - inputs: `spec.md` (ACs = source of truth), `references/spec-driven/validate.md` as operating checklist, commit range, test files in scope
+> - sensors: (1) spec-anchored outcome check — each test's asserted value matches the spec-defined expected outcome; (2) discrimination sensor — injects behavior-level faults in scratch state, confirms tests kill them, discards mutations; surviving mutants become fix tasks
+> - output: `.specs/features/<slug>/validation.md` (PASS/FAIL, per-AC evidence, sensor result, diff range); compact verdict + ranked gap list; gaps become fix tasks
+> - firewall: raw diffs/logs/test output summarized; mutations run in scratch state only
+> - memory: suggest-only; main agent persists validation outcomes
+
+    - The verification-agent re-derives coverage independently using evidence-or-zero and does not inherit the author's mental model.
+   - The fix → re-verify loop is capped at 3 iterations before escalating to `Blocked`.
+   - Distill lesson signals through `references/lessons.md` when validation produces grounded reusable failures.
+7. Update `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `references/spec-driven/memory.md` records for decisions, blockers, handoff, and completion evidence.
+8. When the user splits planning and implementation across clean chats, resume from the canonical `.specs/` artifacts — `.specs/project/STATE.md`, `.specs/project/FEATURES.json`, `.specs/HANDOFF.md`, and the feature's phase files. This workflow owns the spec phase contracts on both sides of the split; there is no separate save/load procedure.
+9. Complete the configured Plan Challenge Gate for non-trivial plans and complete `references/evidence-gate.md` before claiming completion.
+
+## Artifact Ownership
+
+- Feature artifacts live under `.specs/features/<slug>/`.
+- Active harness state is `.specs/project/STATE.md`.
+- Feature registry is `.specs/project/FEATURES.json`.
+- Handoff is `.specs/HANDOFF.md`.
+- `.specs/` files are canonical and git-tracked; there is no secondary store.
+- `.specs/lessons.json` is the machine-owned canonical lessons state; `.specs/LESSONS.md` is its rendered view, regenerated by `scripts/lessons.py` on every write — do not hand-edit.
+- Optional `.specs-exports/` projections are untracked debug aids only.
+- `remember` remains canonical for durable cross-session decisions, rejected approaches, reusable patterns, and verification recipes.
+
+## Failure Handling
+
+- `.specs/` directory missing or not writable: block spec-driven state mutation; do not fall back to memory or chat.
+- massa-ai search or durable memory unavailable: continue from current source and `.specs/` artifacts; report that discovery or durable-memory synchronization was skipped.
+- Synapse unavailable: continue with stateless targeted search.
+- Artifact missing: create it only through an approved first write; otherwise block and ask for direction.
+- Requirement cannot close: keep Specify open and ask the user, or record an explicit accepted assumption before execution.
+- Design or Tasks was skipped incorrectly: stop, create the missing artifact, and resume from the updated contract.
+- Validation command unavailable: record the missing command/tool in `validation.md` and mark `Blocked`.
+- Discrimination sensor cannot be made safely reversible: mark `Blocked` unless the verification-agent can prove equivalent discrimination with an existing deterministic mutation fixture.
+- Validation conflict: stop for user resolution when a validation asset conflicts with an approved specification.
+- Fix loop exceeds 3 iterations: stop with `Blocked`, preserve evidence, and ask for direction.
+
+## Knowledge Verification Chain
+
+When researching, designing, or making any technical decision, follow this chain in strict order. Never skip steps.
+
+```
+Step 1: Codebase → existing code, conventions, patterns already in use
+Step 2: Project docs → README, docs/, inline comments, .specs/project/STATE.md (Decisions)
+Step 3: Context7 MCP → resolve library ID, then query for current API/patterns
+Step 4: Web search → official docs, reputable sources, community patterns
+Step 5: Flag as uncertain → "I'm not certain about X — here's my reasoning, but verify"
+```
+
+- If a chain step's tool is unavailable (Context7 MCP not registered, no web
+  access), record it as a skipped sensor with its reason and continue to the next
+  step. An unavailable step is skipped, never silently treated as answered.
+- Never skip to Step 5 if Steps 1-4 are available.
+- Step 5 is always flagged uncertain — never presented as fact.
+- Never assume or fabricate. If no answer is found, say "I don't know" or "I couldn't find documentation for this". Uncertainty is always preferable to fabrication; invented APIs/patterns cause cascading failures across design → tasks → implementation.
+
+## Brownfield Onboarding — 7-Doc Codebase Mapping
+
+When the spec-driven work targets a codebase the agent has not yet mapped (brownfield, new repo, or cold project), derive a 7-doc codebase map before Specify closes. The map is the shared factual ground for requirements, design, and task derivation; it is not busywork — each doc feeds a downstream phase.
+
+| Doc | Derives | Feeds |
+| --- | --- | --- |
+| `STACK.md` | languages, runtimes, frameworks, key libraries | Design constraints, verification commands |
+| `ARCHITECTURE.md` | layers, modules, boundaries, data flow | Design, risk surface |
+| `CONVENTIONS.md` | naming, file layout, commit/test conventions | Tasks, Execute |
+| `STRUCTURE.md` | directory map, where new code goes | Tasks, file placement |
+| `TESTING.md` | test runner, how to run gates, coverage tooling | Gate Check Commands, verification recipe |
+| `INTEGRATIONS.md` | external services, APIs, contracts, auth | Discuss, risk escalation |
+| `CONCERNS.md` | known risks, tech debt, migration landmines, security/privacy hotspots | Risk-domain escalation, validation focus |
+
+Minimum bar: derive at least **`CONCERNS.md`** (risk surface — drives risk-domain escalation and validation focus) and **`TESTING.md`** (gate derivation — exact commands the Execute gate will run). If time or access is constrained, these two are non-negotiable; the other five are derived as the work needs them. Record the map under `.specs/features/<slug>/` (or the project onboarding dir) and confirm it against current source, not memory or external summaries.
+
+## Commands
+
+Feature-level (auto-sized):
+
+| Trigger Pattern | Reference |
+| --- | --- |
+| Specify feature, define requirements | `references/spec-driven/specify.md` |
+| Discuss feature, capture context, how should this work | `references/spec-driven/discuss.md` |
+| Design feature, architecture | `references/spec-driven/design.md` |
+| Break into tasks, create tasks | `references/spec-driven/tasks.md` |
+| Implement task, build, execute | `references/spec-driven/execute.md` |
+| Validate, verify, test, UAT, walk me through it | `references/spec-driven/validate.md` |
+
+Memory:
+
+| Trigger Pattern | Reference |
+| --- | --- |
+| Record decision, project-level decision | `references/spec-driven/memory.md` |
+| Pause work, end session, I need to stop | `references/spec-driven/memory.md` |
+| Resume work, continue, pick up where we left off | `references/spec-driven/memory.md` |
+| Load lessons, what have we learned, apply past lessons | `references/spec-driven/lessons.md` |
+| Record lesson, distill lessons (auto-runs after validation) | `references/spec-driven/lessons.md` |
+
+## Output Behavior
+
+After lightweight tasks (validation, feature-level checks), mention once per session that such tasks suit faster/cheaper models. For heavy tasks (complex design, large features), briefly note the reasoning requirements before starting. Be conversational, not robotic — add as a natural closing note, skip if the user is experienced or has already acknowledged the tip.
+
+## Example
+
+User asks: "Specify offline draft sync, design it, create tasks, implement it, and verify it."
+
+1. Reuse `projectId` and `workflowSessionId=spec-offline-draft-sync`; recall prior sync decisions and load current `.specs/` artifacts.
+2. Run Specify and close requirements.
+3. Include Design because sync affects data, migration, and public behavior.
+4. Include Tasks because execution has dependency complexity.
+5. Execute one approved task at a time.
+6. Finish Execute with independent validation, including the discrimination sensor, then write `validation.md`.
+<!-- validator anchors: .specs/ files | current repository source and approved .specs/ artifacts override stale memory | .specs/ directory missing | 3 verification iterations -->

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

@@ -0,0 +1,71 @@
+### TDD (Technical Design Document)
+
+Use this workflow when the readiness checklist is true: one product direction is selected, a named requirements source exists, and no unresolved API, data, security/privacy, migration, rollout, or public compatibility decision blocks implementation design. Route unresolved proposals or competing directions to `workflows/rfc.md`, isolated finalized architecture decisions to `workflows/adr.md`, and broad requirements-to-delivery work to `workflows/spec-driven.md`.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+## Workflow
+
+1. Resolve or reuse `projectId` and `workflowSessionId=tdd-[entity]`.
+2. Establish evidence before asking questions:
+   - `recall` approved RFCs, ADRs, prior TDD decisions, constraints, rejected approaches, and verification patterns.
+   - Load `references/tdd/discovery-and-sizing.md`.
+   - Inspect current source, tests, source sets, project instructions, architecture documents, and existing design artifacts. Current source and approved project artifacts override stale memory.
+   - For testing plans, find whether each planned test file already exists and which source set owns it before choosing a location such as `commonTest`, `androidUnitTest`, `unitTest`, or the repository's actual equivalent.
+   - For UI/UX-affecting method, class, enum, sealed type, mapper, or state changes, enumerate parallel rendering surfaces and mappers that consume the affected symbol.
+   - When supplied Figma links, nodes, desktop selections, or screenshots materially affect supported Android, iOS, or KMP Compose Multiplatform UI design, use `workflows/design.md` as optional child context and keep this TDD as the owner of architecture, contracts, rollout, and verification strategy. Screenshots are context-only unless paired with structured Figma evidence.
+   - Run a pre-TDD `Strings Audit` when mappers branch on a type and call `stringResource`; record affected string keys/resources, branches, fallback behavior, and surfaces before proposing string changes.
+   - Load `references/synapse-policy.md` when two or more related searches are expected and `references/context-firewall.md` before broad or verbose source inspection.
+3. Confirm workflow fit with the readiness checklist in `references/tdd/discovery-and-sizing.md` and classify the document as Compact, Standard, or High-Risk from the exact sizing rules there. Do not size by guessed calendar duration.
+   - Record a `project_type` intake tag from this taxonomy: `integration`, `feature`, `refactor`, `infrastructure`, `payment`, `auth`, `data`. The `project_type` selects which conditional concerns in `references/tdd/document-contract.md` apply and which calibrated reference values from `references/tdd/calibrated-examples.md` are relevant; it does not mandate section counts or a fixed document shape.
+   - Apply the critical-section MANDATORY trigger mapping below. These are workflow-level selectors that point at the Conditional Concerns table in `references/tdd/document-contract.md`; they do not duplicate that table. When a trigger fires, the matching concerns are mandatory, not optional:
+     - `payment`, `auth`, PII, or regulated data → Security is mandatory.
+     - production or customer-facing rollout → Monitoring and Rollback are mandatory.
+     - external or cross-service integration → Dependencies and Security are mandatory.
+4. Resolve only material unknowns:
+   - Reuse facts already available in source or approved documents.
+   - Ask at most three related questions at a time, in the user's language.
+   - Distinguish verified facts, evidence-backed inferences, proposed decisions, and unresolved questions.
+   - Never invent owners, links, APIs, schemas, vendors, dates, thresholds, estimates, approvals, or project facts to complete a template.
+5. Load `references/tdd/document-contract.md`, plus `references/naming-standards.md` when the design names proposed components, modules, states, events, schemas, or fields, and draft the smallest decision-complete TDD for the selected depth.
+   - Write in the user's language while preserving established project terminology and technical identifiers.
+   - Focus on architecture, ownership boundaries, stable interfaces, data flow, failure behavior, and implementation strategy.
+   - Include implementation detail when it defines a contract or removes material ambiguity; exclude production implementation code and incidental framework syntax.
+   - For implementation planning, group task rows into independently buildable and testable PR groups using the TDD implementation task table contract. Prefer Small PRs; use Medium PRs only when splitting would break build, tests, UI, or review coherence; treat Large PRs as exceptions requiring split, stacked PR, or feature-flag rationale.
+   - Order non-breaking PR groups by layer when applicable: Data first, then Domain, then Presentation/Navigation. If the target project does not use clean layer names, map those labels to the closest repository boundaries and state the mapping.
+   - Include a test strategy checklist table. For each planned test file, write `amplify in existing location: <path> (<sourceSet>)` when source inspection finds an existing test, or `create in <sourceSet>: <path>` only when evidence supports the new location.
+   - Include a parallel rendering surfaces checklist for UI/UX-affecting changes, covering every discovered rendering surface and mapper that consumes the affected method, class, enum type, state, or model.
+   - Include `Decisions Revised During Implementation` and `Pre-Merge TDD Fidelity Check` sections so implementation-time divergences remain visible instead of silently rewriting the original design.
+   - Use a diagram only when it communicates interactions or state more clearly than prose. Use `mermaid-studio` when installed and rendering or complex diagram validation is valuable; otherwise use valid inline Mermaid or prose.
+6. Choose the artifact path from an explicit user path or an existing project convention. Otherwise default to `docs/design/<entity>.md`.
+   - If the target exists, treat the request as an update only when the user explicitly requested one; otherwise ask before overwriting it.
+   - When file mutation is unavailable or the user requested plan-only output, present the complete draft and intended path without writing.
+7. Run the configured Plan Challenge Gate. TDD plans require the full gate under the default policy; revise valid critical or high findings before finalization.
+8. Load `references/tdd/quality-and-lifecycle.md`, validate the document, and resolve blocking gaps. Keep non-blocking unknowns explicit with owners or decision points when known.
+9. If the implementation task table is stable and validated, discover whether Atlassian MCP has readable Jira project metadata and issue-creation capability.
+   - If Atlassian MCP is unavailable or read-only, leave the table's `Jira Key` values as `Unavailable` and report that ticket creation was skipped.
+   - If Atlassian MCP is available, ask whether the user wants to create Jira tickets now. If declined, set `Jira Key` to `Not requested`.
+   - If the user accepts, invoke `workflows/ticket.md`; Jira creation remains owned solely by the ticket workflow. Create one standard Jira issue per PR group. Create row-level sub-tasks only when the selected ticket hierarchy requires them.
+   - Update `Jira Key` only with confirmed Jira keys returned by the ticket workflow. Use `Pending` for approved-but-uncreated PR groups and never fabricate keys.
+10. Save the document as `Draft` or `In Review`. Never mark it `Approved`, invent sign-off, or begin downstream implementation without the required human decision.
+11. Persist only durable architecture constraints, accepted trade-offs, rejected approaches, compatibility requirements, and verification recipes through `remember` after recall, deduplication, and scoring. Use `decision` with `memory:semantic` for the architectural blueprint.
+12. Complete `references/evidence-gate.md` and report the artifact path, included conditional sections, unresolved questions, Jira creation outcome, memory outcome, and residual risk.
+
+## Failure Handling
+
+- massa-ai unavailable: continue from current source and project documents; report skipped durable-memory synchronization.
+- Synapse unavailable: continue with stateless targeted search.
+- Evidence is insufficient: ask the smallest blocking question set or mark the point unresolved; do not fabricate completion.
+- Direction is still disputed: stop and route to RFC rather than embedding an unapproved choice in the TDD.
+- Existing document conflicts with current source or approved decisions: surface the conflict and request resolution before replacing the authoritative statement.
+- Diagram tooling unavailable: use simple validated Mermaid or prose; diagram rendering must not block a complete design.
+
+## Example
+
+User asks: "Create a TDD for moving password reset tokens from the users table into a dedicated store."
+
+1. Recall approved auth decisions and inspect the current token flow, persistence model, tests, and operational constraints.
+2. Classify High-Risk because the design affects authentication and sensitive data.
+3. Ask only unresolved security, compatibility, or rollout questions that source cannot answer.
+4. Draft the core design plus conditional security, data migration, observability, rollout, and rollback sections.
+5. Challenge the plan, revise serious findings, validate decision completeness, and save a Draft without fabricated approval.