@massa-ai/codex-plugin 1.26.0 → 1.27.0

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

@@ -1,12 +1,20 @@
+---
+name: requirements-audit
+description: "Findings-only review of whether a concrete target matches stated requirements without out-of-scope drift; routes correctness, security, and quality findings elsewhere."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Requirements Audit
 
-Use this workflow for findings-only review of whether a concrete target matches stated requirements without out-of-scope drift. Accepted targets include 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`.
+Findings-only review of whether a concrete target matches stated requirements without out-of-scope drift. Accepted targets include 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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-Do not use this workflow for generic correctness bugs, security findings, architecture findings, code quality findings, or test coverage findings. Route correctness bugs to `workflows/bugs/bugs-audit.md` and route the other categories to their dedicated workflows.
+Not for generic correctness bugs, security findings, architecture findings, code quality findings, or test coverage findings. Route correctness bugs to `workflows/bugs/bugs-audit.md` and route the other categories to their dedicated workflows.
 
-This workflow is findings-only. Do not edit code unless the user separately asks for fixes.
+Findings-only: do not edit code unless the user separately asks for fixes.
 
 1. Resolve/reuse `workflowSessionId`: `requirements-[entity]`
 2. Load shared references:
@@ -32,33 +40,8 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - 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`.
    - If requirements source is missing after checking the prompt, PR description, task file, spec, issue text, and repo docs, ask for the requirements source before proceeding.
    - 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 required behavior.
-   - Exclude deleted files unless their deletion can break required behavior, imports, exports, routing, migrations, config, tests, packaging, or documentation contracts.
-   - Exclude generated, dependency, build, log, cache, temporary, and secret paths per repo rules.
-   - Inspect diffs first, then only the surrounding code needed to compare implementation against requirements.
-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 requirements sources, callers, tests, config, schemas, and docs 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, public API, tests, config, docs, and acceptance criteria.
-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, requirements source, and freshness timestamp.
-   - For symbol/class/function targets, inspect definitions, call paths, public contracts, tests, config, docs, and requirement links only as needed.
-   - For feature/flow targets, map expected behavior from the requirements source to implementation, tests, docs, and public contracts.
-   - If whole-repo scope is requested, map top-level requirement areas first and report skipped depth checks rather than implying exhaustive coverage.
-9. For implementation parent scope:
-   - Accept the exact scope packet and requirement source from `implementation-audit`.
-   - Do not broaden beyond resolved files, surrounding code, public contracts, tests, config, docs, and requirements needed to verify a 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:
+5. Resolve the selected branch's mechanics (modified files, commit range, codebase area, explicit-files/branch/symbol/feature/whole-repo, or implementation parent scope) per `references/audit-scope.md` (Lens Audit Scope Resolution Procedure, Requirements row of Per-Lens Scope Deltas). Implementation parent scope additionally carries the requirement source from `implementation-audit`.
+6. 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
@@ -75,16 +58,16 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Compare implementation and tests against each checklist item.
    - Prioritize missing requirements, contradicted requirements, out-of-scope behavior, changed public contracts, compatibility breaks, incomplete edge cases, and docs or tests that misrepresent delivered behavior.
    - For each candidate finding, record the concrete claim, source evidence, affected requirement, impacted flow, provisional severity, and what would disprove it.
-11. False-positive pass:
+7. False-positive pass:
    - Try to disprove every candidate before reporting it.
    - Check requirement wording, accepted scope changes, ADRs, feature flags, compatibility notes, tests, docs, call paths, and user-provided constraints.
    - 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):
+8. Severity rules (apply the countable threshold first, then the qualitative clause):
    - `critical`: implementation violates a mandatory requirement in a way that blocks release, causes data loss, breaks auth/privacy, OR affects >10 files; otherwise use the qualitative clause below.
    - `high`: missing or contradictory core requirement, significant out-of-scope behavior, public contract break, or major compatibility regression.
    - `medium`: incomplete edge-case requirement, unclear acceptance gap, recoverable behavior mismatch (<=10 affected files), missing required docs/test coverage around a requirement, or scoped regression.
    - `low`: minor requirement ambiguity, wording mismatch, low-impact out-of-scope behavior, incomplete evidence, or weakly supported concern.
-13. Final report:
+9. Final report:
    - Findings first, ordered by severity: `critical`, `high`, `medium`, `low`.
    - Each finding must use `REQ-<N>` and include the canonical fields from `references/audit-report-io.md`: severity, confidence, requirement source, requirement ID or quote, requirement gap type, file/line, evidence, impact, simplest fix direction, and verification suggestion.
    - If no requirements findings are found, say that clearly and list scope checked, requirement source used, and skipped checks.
@@ -93,11 +76,11 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Include the Verification/Test Fidelity Checklist from `references/audit-report-io.md`; tie every `REQ-*` 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/requirements/<YYYY-MM-DD requirements-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:
+10. Persist only durable knowledge:
    - Do not persist one-off findings.
    - Persist durable requirements decisions, accepted scope constraints, repeated requirement-drift patterns, or reusable verification recipes after scoring with the Importance Calibration System.
    - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:requirements-audit`, `entity:<entity>`, and one `memory:<tier>` tag.
-15. Complete the Evidence Gate from `references/evidence-gate.md`.
+11. Complete the Evidence Gate from `references/evidence-gate.md`.
 
 ## Examples
 

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

@@ -1,12 +1,20 @@
+---
+name: requirements-fix
+description: "Executes fixes from a saved requirements audit report; not for findings-only review or broad feature design when acceptance criteria are missing."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Requirements Fix
 
-Use this workflow only to execute fixes from a requirements audit markdown report.
+Execute fixes from a requirements audit markdown report only.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one symptom, stop editing and load `references/root-cause-scripts.md`.
 
-Do not use this workflow for findings-only requirements review; route that to `workflows/requirements/requirements-audit.md`. Do not use it for broad feature design when acceptance criteria are missing; route that to `workflows/spec-driven.md`.
+Not for findings-only requirements review — route to `workflows/requirements/requirements-audit.md`. Not for broad feature design when acceptance criteria are missing — route to `workflows/spec-driven.md`.
 
 1. Resolve/reuse `workflowSessionId`: `requirements-fix-[entity]`
 2. Load shared references:
@@ -23,7 +31,7 @@ Do not use this workflow for findings-only requirements review; route that to `w
    - If the user asks for "latest" or gives no path, require a concrete target focus first; do not run the latest requirements report against an unspecified target.
    - Select the latest `audits/requirements/<YYYY-MM-DD requirements-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, `REQ-` IDs, requirement source, resolved files or material scope evidence, and current file/line evidence. Stop on invalid, stale, target-drifted, or ambiguous reports before editing.
+   - Validate the report deterministically: `bun skills/massa-ai/scripts/validate_audit_report.ts <path> --family requirements` (`references/audit-report-io.md`, Deterministic Validation, checks `Requirements Source` too); non-zero exit blocks editing. Also confirm resolved files or material scope evidence and current file/line evidence; stop on stale, target-drifted, or ambiguous reports.
 5. Extract actionable findings:
    - Keep findings with concrete `Requirement Source`, `Requirement ID or Quote`, `Requirement Gap Type`, `Location`, `Evidence`, `Impact`, `Simplest Fix Direction`, and `Verification Suggestion`.
    - Ignore ruled-out candidates and no-finding sections.

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

@@ -1,8 +1,16 @@
+---
+name: rfc
+description: "Use this workflow when a significant technical, process, product, vendor, tool, or policy decision is still open and stakeholders need a structured proposal before committing."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### RFC (Request for Comments)
 
-Use this workflow when a significant technical, process, product, vendor, tool, or policy decision is still open and stakeholders need a structured proposal before committing to a direction. Route a finalized architecture decision to `workflows/adr.md`, settled implementation design to `workflows/tdd.md`, and broad requirements-through-delivery work to `workflows/spec-driven.md`.
+Use when a significant technical, process, product, vendor, tool, or policy decision is still open and stakeholders need a structured proposal before committing to a direction. Route a finalized architecture decision to `workflows/adr.md`, settled implementation design to `workflows/tdd.md`, and broad requirements-through-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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
 ## Workflow
 

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

@@ -1,12 +1,20 @@
+---
+name: security-audit
+description: "Findings-only security review workflow for a concrete target; routes generic correctness bugs and other audit categories to their dedicated workflows."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 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`.
+Findings-only security review scoped to 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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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.
+Not for generic correctness bugs — route to `workflows/bugs/bugs-audit.md`. Not for broad architecture, code quality, requirements, or test coverage audits — route to their dedicated workflows.
 
-This workflow is findings-only. Do not edit code unless the user separately asks for fixes.
+Findings-only: do not edit code unless the user separately asks for fixes.
 
 1. Resolve/reuse `workflowSessionId`: `security-[entity]`
 2. Load shared references:
@@ -31,32 +39,8 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - 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:
+5. Resolve the selected branch's mechanics (modified files, commit range, codebase area, explicit-files/branch/symbol/feature/whole-repo, or implementation parent scope) per `references/audit-scope.md` (Lens Audit Scope Resolution Procedure, Security row of Per-Lens Scope Deltas).
+6. 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
@@ -73,17 +57,17 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - 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:
+7. 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):
+8. 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:
+9. 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.
@@ -92,11 +76,11 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - 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:
+10. 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`.
+11. Complete the Evidence Gate from `references/evidence-gate.md`.
 
 ## Examples
 

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

@@ -1,12 +1,20 @@
+---
+name: security-fix
+description: "Executes fixes from a saved security audit report; not for findings-only security review or generic correctness fixes outside an exploitable path."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Security Fix
 
-Use this workflow only to execute fixes from a security audit markdown report.
+Execute fixes from a security audit markdown report only.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one 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.
+Not for findings-only security review — route to `workflows/security/security-audit.md`. Not 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:
@@ -24,7 +32,7 @@ Do not use this workflow for findings-only security review; route that to `workf
    - 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.
+   - Validate the report deterministically: `bun skills/massa-ai/scripts/validate_audit_report.ts <path> --family security` (`references/audit-report-io.md`, Deterministic Validation); non-zero exit blocks editing. Also confirm resolved files or material scope evidence and current file/line evidence; stop on stale, target-drifted, or ambiguous reports.
 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.

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

@@ -1,10 +1,18 @@
+---
+name: spec-driven
+description: "Use this workflow for explicit spec-driven requests and broad, ambiguous, migration-heavy, or cross-boundary delivery needing requirements-through-verification control."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 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.
+Use 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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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, and `references/repo-rules-discovery.md` to discover and enforce the target repository's own `.claude/`, `.cursor/`, and module/unit-test/testing-area conventions. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate), `references/code-annotation.md` (doc blocks, rationale, test coverage), and `references/repo-rules-discovery.md` (enforce the target repo's own `.claude/`/`.cursor/` and module/test conventions). After two consecutive failed fixes on one symptom, stop editing and load `references/root-cause-scripts.md`.
 
 ## TLC v3 Flow
 
@@ -40,7 +48,7 @@ Complexity determines depth, not a fixed pipeline. Assess scope first, apply onl
 | 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 an ordered group of Tasks sharing a dependency boundary or a checkpoint commit — it is distinct from a single Task or atomic step. Report sizing in the uniform vocabulary: `1 Phase = X Tasks`; the whole plan is `Y Phases = Z Tasks`. The sub-agent offer fires when a formal `tasks.md` has more than 3 Tasks — packing itself still uses ~7-Task Phase groups; a 4–8-Task feature is offered as a single Phase-group worker.
+A "Phase" is an ordered group of Tasks sharing a dependency boundary or a checkpoint commit — distinct from a single Task or atomic step. Report sizing in the uniform vocabulary: `1 Phase = X Tasks`; the whole plan is `Y Phases = Z Tasks`. The sub-agent offer fires when a formal `tasks.md` has more than 3 Tasks — packing itself still uses ~7-Task Phase groups; a 4–8-Task feature is offered as a single Phase-group worker.
 
 - Specify and Execute are always required.
 - Design is skipped when straightforward (no architectural decisions, no new patterns).
@@ -50,7 +58,7 @@ A "Phase" is an ordered group of Tasks sharing a dependency boundary or a checkp
 
 ## 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.
+Quick mode is the Small/auto-sized path: a single change touching **max 3 files** with no new dependency and no design decision. Fast lane, not a parallel pipeline — it still closes requirements and runs the Execute gate.
 
 Enter Quick mode only when **all** hold:
 
@@ -74,7 +82,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
 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/synapse-policy.md` when two or more related searches are expected. For multi-search investigations, run the Synapse task envelope per that reference: `synapse_task_begin` before the first search, `synapse_prefetch` on deep file open, `synapse_task_end` at completion (both `task` calls 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.
@@ -85,19 +93,18 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
 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. When Figma links or node IDs are supplied, load `references/figma-pre-analysis.md` and run its two-stage sequential retrieval protocol before consuming the design evidence. 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.
+   - For Android, iOS, or KMP Compose Multiplatform UI work, run the optional design-source intake gate from `references/mobile-context.md` (Design-Source Intake Gate).
    - 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.
+4. Decide whether `Design` is required. If yes, run `references/spec-driven/design.md`, including its deterministic validation before presenting `design.md` for confirmation; 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.
    - Run repo-rules discovery from `references/repo-rules-discovery.md` before the first repository mutation: record the harness sources loaded (or `repo-rules: none present`), and implement so every new or changed file conforms to the target repo's module layout, unit-test location, and testing-area conventions. A repo rule wins over a skill default for placement and gate commands; record any deviation with an explicit reason. Never fabricate rules or create `.claude/`/`.cursor/` directories the repo lacks.
    - 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` has more than 3 Tasks, present the sub-agent offer from `references/spec-driven/sub-agents.md` before starting Execute — even when packing yields a single Phase group (a 4–8-Task feature is offered as one Phase-group worker). Offer-then-confirm — never auto-spawn; the user must accept before any sub-agent is dispatched. One worker per Phase group (~7 Tasks, whole Phases): each 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.
+   - If a formal `tasks.md` has more than 3 Tasks, present the sub-agent offer from `references/spec-driven/sub-agents.md` before starting Execute — even when packing yields a single Phase group (a 4–8-Task feature is offered as one Phase-group worker).
    - 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.
+   - For long-running task sequences, use the checkpoint mechanism in `references/spec-driven/execute.md` (Pause / End of Session) so progress is resumable after interruption.
    - 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.
@@ -117,7 +124,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
     - 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. Before the delivery chain's Propose stage (PR creation), write and commit `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `.specs/project/FEATURES.json` on the branch — not merely "after meaningful progress" during Execute, but committed before `gh pr create`. **Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/check_specs_delivered.ts <feature> [--root .]` — a non-zero exit blocks Propose (see `references/implementation-delivery.md` stage 3.5 and GATE-02). If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved). Record `references/spec-driven/memory.md` decisions, blockers, handoff, and completion evidence per that reference's write triggers.
+7. Before the delivery chain's Propose stage (PR creation), write and commit `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `.specs/project/FEATURES.json` on the branch — not merely "after meaningful progress" during Execute, but committed before `gh pr create`. **Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/check_specs_delivered.ts <feature> [--root .]` — a non-zero exit blocks Propose (see `references/implementation-delivery.md` stage 3.5 and GATE-02). If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved). Record decisions, blockers, handoff, and completion evidence per `references/spec-driven/memory.md`'s write triggers.
 8. When the user splits planning and implementation across clean chats, resume from the canonical `.specs/` artifacts — `.specs/project/STATE.md`, `.specs/project/FEATURES.json`, `.specs/HANDOFF.md`, and the feature's phase files. This workflow owns the spec phase contracts on both sides of the split; there is no separate save/load procedure.
 9. Complete the configured Plan Challenge Gate for non-trivial plans and complete `references/evidence-gate.md` before claiming completion.
 
@@ -166,17 +173,7 @@ Step 5: Flag as uncertain → "I'm not certain about X — here's my reasoning,
 
 ## 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 |
+When the spec-driven work targets a codebase the agent has not yet mapped (brownfield, new repo, or cold project), derive the 7-doc codebase map from `references/spec-driven/brownfield-mapping.md` before Specify closes — not busywork, each doc feeds a downstream phase.
 
 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.
 

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

@@ -1,8 +1,16 @@
+---
+name: tdd
+description: "Use this workflow to write a Technical Design Document once one product direction is selected and no unresolved API, data, security, or rollout decision blocks implementation."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 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`.
+Use 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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
 ## Workflow
 

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

@@ -1,12 +1,20 @@
+---
+name: tests-audit
+description: "Findings-only audit of test coverage, regression protection, assertion quality, fixture reliability, and missing deterministic sensors in a concrete target."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Tests Audit
 
-Use this workflow for findings-only audit of test coverage, regression protection, assertion quality, fixture reliability, and missing deterministic sensors 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`.
+Findings-only audit of test coverage, regression protection, assertion quality, fixture reliability, and missing deterministic sensors, scoped to 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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-Do not use this workflow to write, run, or fix test findings as the main task; route that to `workflows/tests/tests-fix.md`. Do not use it for generic correctness, security, architecture, code quality, or requirements findings; route those to the dedicated workflows.
+Not to write, run, or fix test findings as the main task — route to `workflows/tests/tests-fix.md`. Not for generic correctness, security, architecture, code quality, or requirements findings — route to the dedicated workflows.
 
-This workflow is findings-only. Do not edit code unless the user separately asks for fixes.
+Findings-only: do not edit code unless the user separately asks for fixes.
 
 1. Resolve/reuse `workflowSessionId`: `test-audit-[entity]`
 2. Load shared references:
@@ -31,32 +39,8 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - 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, validation, or test behavior.
-   - Exclude deleted files unless their deletion can break test coverage, imports, exports, routing, migrations, config, tests, or packaging.
-   - Exclude generated, dependency, build, log, cache, temporary, and secret paths per repo rules.
-   - Inspect diffs first, then tests and surrounding code needed to understand regression risk.
-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 tests, fixtures, config, schemas, and prior bug patterns 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 production entry points, tests, fixtures, mocks, test commands, and coverage-sensitive 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, behavior contracts, tests, fixtures, mocks, and test commands only as needed.
-   - For feature/flow targets, map changed or targeted behavior to existing tests and deterministic harnesses.
-   - If whole-repo scope is requested, map major test surfaces first and report skipped depth checks rather than implying exhaustive coverage.
-9. For implementation parent scope:
-   - Accept the exact scope packet from `implementation-audit`; do not broaden beyond resolved files, nearby tests, fixtures, config, and callers needed to verify regression protection.
-   - 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:
+5. Resolve the selected branch's mechanics (modified files, commit range, codebase area, explicit-files/branch/symbol/feature/whole-repo, or implementation parent scope) per `references/audit-scope.md` (Lens Audit Scope Resolution Procedure, Tests row of Per-Lens Scope Deltas).
+6. 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
@@ -74,17 +58,17 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - For mobile scopes, check KMP shared and platform-specific `actual` tests, Android/iOS harnesses, native bridge payload coverage, permissions, lifecycle, offline sync, deep links, push/background flows, UI snapshots/screenshots, device-matrix assumptions, and platform parity claims from `references/mobile-context.md`.
    - Check weak assertions, tests that only assert implementation details, fixture drift, nondeterminism, hidden network/time/filesystem dependencies, skipped tests, and weakened snapshots.
    - For each candidate finding, record the concrete claim, source evidence, impacted behavior, likely regression path, provisional severity, and what would disprove it.
-11. False-positive pass:
+7. False-positive pass:
    - Try to disprove every candidate before reporting it.
    - Check existing unit, integration, e2e, contract, snapshot, fixture, and harness coverage; also check framework-generated coverage and accepted exceptions.
    - If a deterministic test command is cheap and in scope, run it as a sensor; if not, report the skipped command and reason.
    - 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):
+8. Severity rules (apply the countable threshold first, then the qualitative clause):
    - `critical`: missing or broken tests around data loss, auth/privacy, migration, deployment-blocking, irreversible corruption risk, OR >10 affected files; otherwise use the qualitative clause below.
    - `high`: missing or weak tests around a core flow, public contract, persistence behavior, validation, security boundary, or severe regression risk.
    - `medium`: missing edge-flow coverage, flaky or nondeterministic test risk, fixture drift, weak assertions, or missing regression coverage around changed logic (<=10 affected files).
    - `low`: minor coverage gap, low-impact assertion hardening, incomplete evidence, or weakly supported concern.
-13. Final report:
+9. Final report:
    - Findings first, ordered by severity: `critical`, `high`, `medium`, `low`.
    - Each finding must use `TST-<N>` and include the canonical fields from `references/audit-report-io.md`: severity, confidence, file/line, evidence, impacted behavior, regression risk, simplest test direction, deterministic sensor, and verification suggestion.
    - If no test audit findings are found, say that clearly and list scope checked plus skipped checks.
@@ -93,11 +77,11 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Include the Verification/Test Fidelity Checklist from `references/audit-report-io.md`; tie every `TST-*` 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/tests/<YYYY-MM-DD tests-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:
+10. Persist only durable knowledge:
    - Do not persist one-off findings.
    - Persist repeated test gap patterns, project-specific testing conventions, accepted exceptions, flaky-test patterns, or reusable verification recipes after scoring with the Importance Calibration System.
    - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:tests-audit`, `entity:<entity>`, and one `memory:<tier>` tag.
-15. Complete the Evidence Gate from `references/evidence-gate.md`.
+11. Complete the Evidence Gate from `references/evidence-gate.md`.
 
 ## Examples
 

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

@@ -1,12 +1,20 @@
+---
+name: tests-fix
+description: "Executes fixes from a saved tests audit report; not for findings-only coverage review or generic test-writing work without an audit report."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Tests Fix
 
-Use this workflow only to execute fixes from a tests audit markdown report.
+Execute fixes from a tests audit markdown report only.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one symptom, stop editing and load `references/root-cause-scripts.md`.
 
-Do not use this workflow for findings-only test coverage, assertion quality, fixture health, flakiness, or regression-risk review; route that to `workflows/tests/tests-audit.md`. Do not use it for generic "write some tests" work without an audit report; route broad test planning through the relevant feature, debug, refactor, or spec-driven workflow.
+Not for findings-only test coverage, assertion quality, fixture health, flakiness, or regression-risk review — route to `workflows/tests/tests-audit.md`. Not for generic "write some tests" work without an audit report — route broad test planning through the relevant feature, debug, refactor, or spec-driven workflow.
 
 1. Resolve/reuse `workflowSessionId`: `tests-fix-[entity]`
 2. Load shared references:
@@ -24,7 +32,7 @@ Do not use this workflow for findings-only test coverage, assertion quality, fix
    - If the user asks for "latest" or gives no path, require a concrete target focus first; do not run the latest tests report against an unspecified target.
    - Select the latest `audits/tests/<YYYY-MM-DD tests-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, `TST-` IDs, resolved files or material scope evidence, and current file/line evidence. Stop on invalid, stale, target-drifted, or ambiguous reports before editing.
+   - Validate the report deterministically: `bun skills/massa-ai/scripts/validate_audit_report.ts <path> --family tests` (`references/audit-report-io.md`, Deterministic Validation); non-zero exit blocks editing. Also confirm resolved files or material scope evidence and current file/line evidence; stop on stale, target-drifted, or ambiguous reports.
 5. Extract actionable test findings:
    - Keep findings with concrete `Location`, `Evidence`, impacted behavior, regression risk, `Simplest Test Direction`, `Deterministic Sensor`, and `Verification Suggestion`.
    - Ignore ruled-out candidates, no-finding sections, and low-confidence hardening ideas unless the user explicitly asks to include them.

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

@@ -1,10 +1,18 @@
+---
+name: the-fool
+description: "Use this workflow for direct requests to challenge ideas, plans, decisions, or evidence, and as the configured post-plan challenge gate after other workflows construct a plan."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### The Fool
 
-Use this workflow for direct requests to challenge ideas, plans, decisions, proposals, architectures, evidence, or assumptions. Also use it as the configured post-plan challenge gate after other massa-ai workflows construct a plan.
+Use for direct requests to challenge ideas, plans, decisions, proposals, architectures, evidence, or assumptions. Also use as the configured post-plan challenge gate after other massa-ai workflows construct a plan.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-Do not use this workflow to build the initial plan, make the decision, or execute implementation work. It critiques and strengthens existing thinking.
+Not to build the initial plan, make the decision, or execute implementation work. It critiques and strengthens existing thinking.
 
 ## Configuration