@massa-ai/cursor-plugin 1.35.0 → 1.35.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.cursor-plugin/plugin.json +1 -1
- package/package.json +1 -1
- package/skills/massa-ai/references/agent-orchestration.md +4 -0
- package/skills/massa-ai/references/artifact-persistence.md +46 -0
- package/skills/massa-ai/references/audit-report-io.md +50 -0
- package/skills/massa-ai/references/brownfield-mapping.md +22 -0
- package/skills/massa-ai/references/codebase-investigation.md +1 -1
- package/skills/massa-ai/references/discrimination-sensor.md +42 -0
- package/skills/massa-ai/references/implementation-delivery.md +8 -3
- package/skills/massa-ai/references/knowledge-verification-chain.md +25 -0
- package/skills/massa-ai/references/maestro/cloud.md +2 -0
- package/skills/massa-ai/references/maestro/fact-ledger.md +2 -0
- package/skills/massa-ai/references/maestro/patterns.md +7 -1
- package/skills/massa-ai/references/mobile-figma-matcher/core.md +13 -0
- package/skills/massa-ai/references/spec-driven/artifact-store.md +2 -32
- package/skills/massa-ai/references/spec-driven/design.md +1 -1
- package/skills/massa-ai/references/spec-driven/validate.md +9 -31
- package/skills/massa-ai/references/verification-ladder.md +16 -0
- package/skills/massa-ai/scripts/check_fix_closure.ts +335 -0
- package/skills/massa-ai/scripts/check_specs_delivered.ts +61 -15
- package/skills/massa-ai/scripts/validate_audit_report.ts +2 -1
- package/skills/massa-ai/workflows/architecture/architecture-fix.md +29 -19
- package/skills/massa-ai/workflows/bugs/bugs-fix.md +27 -16
- package/skills/massa-ai/workflows/code-quality/code-quality-fix.md +34 -21
- package/skills/massa-ai/workflows/debug.md +42 -15
- package/skills/massa-ai/workflows/exploration.md +1 -16
- package/skills/massa-ai/workflows/feature.md +24 -4
- package/skills/massa-ai/workflows/general.md +26 -4
- package/skills/massa-ai/workflows/implementation/implementation-fix.md +23 -16
- package/skills/massa-ai/workflows/maestro/maestro-fix.md +23 -4
- package/skills/massa-ai/workflows/mobile-figma/mobile-figma-fix.md +49 -16
- package/skills/massa-ai/workflows/refactor.md +32 -3
- package/skills/massa-ai/workflows/requirements/requirements-fix.md +29 -17
- package/skills/massa-ai/workflows/security/security-fix.md +28 -17
- package/skills/massa-ai/workflows/spec-driven.md +4 -21
- package/skills/massa-ai/workflows/tests/tests-fix.md +31 -17
- package/skills/massa-ai/references/spec-driven/brownfield-mapping.md +0 -16
|
@@ -3,7 +3,7 @@ name: bugs-fix
|
|
|
3
3
|
description: "Executes fixes from a saved bugs audit report; not for findings-only discovery, single known issues without a report, or broad product changes."
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
|
-
version: "1.
|
|
6
|
+
version: "1.2.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
### Bugs Fix
|
|
@@ -12,7 +12,7 @@ Execute fixes from a bugs audit markdown report only.
|
|
|
12
12
|
|
|
13
13
|
Load `references/project-context.md` (intake sweep) before the first substantive read.
|
|
14
14
|
|
|
15
|
-
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`.
|
|
15
|
+
Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate — its Stage 3 delivery-authorization scope covers one go-ahead through PR creation; force-push/deploy/merge stay separately gated) 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`.
|
|
16
16
|
|
|
17
17
|
**Isolation Gate — before the first file edit:** execute `references/implementation-delivery.md` Stage 0–1 now (fetch base, create the worktree + branch, work inside it) and record the worktree path + branch — or one of Stage 1's two legal skip reasons, verbatim — before any repository mutation.
|
|
18
18
|
|
|
@@ -26,6 +26,9 @@ Not for findings-only bug discovery — route to `workflows/bugs/bugs-audit.md`.
|
|
|
26
26
|
- `references/verification-ladder.md` before non-trivial edits
|
|
27
27
|
- `references/context-firewall.md` before inspecting large diffs, logs, snapshots, generated reports, or broad search output
|
|
28
28
|
- `references/agent-orchestration.md` only for large/high-risk findings, disjoint implementation slices, or independent verification
|
|
29
|
+
- `references/discrimination-sensor.md` before closing any finding under the Mandatory Verification Fix Gate
|
|
30
|
+
- `references/knowledge-verification-chain.md` when the bug's root cause depends on an external library's or API's actual behavior
|
|
31
|
+
- `references/brownfield-mapping.md` (Minimum Bar only, Standard+ bug findings) when recall returns no hit for the bug's target and no gate command can be derived from the report's evidence
|
|
29
32
|
3. `recall` -> load prior bug patterns, known regressions, fragile flows, accepted exceptions, testing conventions, and reusable verification recipes for the report target.
|
|
30
33
|
4. Select the bugs audit report with execution focus:
|
|
31
34
|
- Establish the report selector, target focus, and optional finding selector before selecting a report. Target focus can be a flow, module, files/globs, branch comparison, commit range, symbol/class/function, feature area, or explicit whole-repo target.
|
|
@@ -54,7 +57,7 @@ Not for findings-only bug discovery — route to `workflows/bugs/bugs-audit.md`.
|
|
|
54
57
|
- Prefer the smallest behavior-preserving fix: guard, validation, state update, ordering, await/async correction, persistence constraint, config default, or call-site contract alignment.
|
|
55
58
|
- Add or update regression tests for the trigger path when feasible; include positive coverage so the fix does not over-block valid behavior.
|
|
56
59
|
- Do not weaken tests, fixtures, snapshots, types, or public contracts to make the fix pass.
|
|
57
|
-
9. Use agent orchestration only when it improves signal. Dispatch per `references/agent-orchestration.md`:
|
|
60
|
+
9. Use agent orchestration only when it improves signal, except independent verification of the bug fix, which is mandated at the tiers named in `references/agent-orchestration.md`'s Independent Verification Exception. Dispatch per `references/agent-orchestration.md`:
|
|
58
61
|
|
|
59
62
|
> **Dispatch: `massa-ai-builder`** (role: `builder`) — charter `skills/agents/builder/SKILL.md`
|
|
60
63
|
> - trigger: large/high-risk finding, disjoint implementation slice, or explicit subagent request
|
|
@@ -67,18 +70,6 @@ Not for findings-only bug discovery — route to `workflows/bugs/bugs-audit.md`.
|
|
|
67
70
|
> - memory: suggest-only; main agent persists reusable bug patterns
|
|
68
71
|
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
69
72
|
|
|
70
|
-
> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
|
|
71
|
-
> - trigger: independent verification of a high-risk bug fix
|
|
72
|
-
> - scope: the fixed finding's repro path, tests, and report claim closure
|
|
73
|
-
> - permissions: read-only
|
|
74
|
-
> - inputs: the finding, the applied fix, the verification suggestion, and validation assets
|
|
75
|
-
> - sensors: deterministic command (repro path, focused tests, inspection) and report claim closure
|
|
76
|
-
> - output: confirmed/disproven closure verdict with evidence
|
|
77
|
-
> - firewall: raw test output/logs summarized
|
|
78
|
-
> - memory: suggest-only; main agent persists reusable verification recipes
|
|
79
|
-
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
80
|
-
- Main agent owns report parsing, prioritization, memory writes, final synthesis, and Evidence Gate.
|
|
81
|
-
|
|
82
73
|
> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
|
|
83
74
|
> - trigger: implementation complete, before the verification gate — never optional
|
|
84
75
|
> - scope: the fix's diff surface and its task/AC context
|
|
@@ -91,19 +82,36 @@ Not for findings-only bug discovery — route to `workflows/bugs/bugs-audit.md`.
|
|
|
91
82
|
> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
|
|
92
83
|
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
93
84
|
|
|
85
|
+
> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
|
|
86
|
+
> - trigger: mandatory at Standard+/Spec-driven bug-fix size or high/critical bug severity, per the Independent Verification Mandate tier gate in `references/verification-ladder.md`
|
|
87
|
+
> - scope: the fixed bug finding's repro path, regression tests, and report claim closure
|
|
88
|
+
> - permissions: read-only
|
|
89
|
+
> - inputs: the bug finding, the applied root-cause fix, the verification suggestion, and validation assets
|
|
90
|
+
> - sensors: deterministic command (repro path, focused regression tests, inspection) and report claim closure; discrimination sensor per `references/discrimination-sensor.md` (the divergence-point fix just applied)
|
|
91
|
+
> - output: confirmed/disproven bug-closure verdict with evidence
|
|
92
|
+
> - firewall: raw repro transcripts and test/log output summarized
|
|
93
|
+
> - memory: suggest-only; main agent persists bug-closure verification outcomes
|
|
94
|
+
> - fallback: if the subagent is unavailable, run a standalone fresh-eyes re-check of the bug-fix closure evidence against this output contract and record the skipped-delegation reason
|
|
95
|
+
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
96
|
+
- Main agent owns report parsing, prioritization, memory writes, final synthesis, and Evidence Gate.
|
|
97
|
+
|
|
94
98
|
10. Verify each completed finding:
|
|
95
99
|
- If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
|
|
96
100
|
`bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
|
|
97
101
|
- 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.
|
|
98
102
|
- 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.
|
|
99
103
|
- Run the report's verification suggestion when available.
|
|
104
|
+
- The red→green reproduction proves the regression test catches this bug; the discrimination sensor proves that same assertion would also discriminate against a future wrong implementation — complementary, and both required at Standard+.
|
|
105
|
+
- At the tiers named in the verification-agent dispatch's trigger above, run the discrimination sensor per `references/discrimination-sensor.md` against the divergence-point fix; a surviving mutant marks the finding's closure row `blocked` and records the `surviving_mutant` lessons signal even when the reproduction test is green.
|
|
106
|
+
- The fix→re-verify cycle is capped per `references/verification-ladder.md`'s Bounded Fix→Re-verify Loop; this is a separate counter from the two-consecutive-failed-fixes breaker into `references/root-cause-scripts.md` above, which fires inside one iteration and neither consumes nor resets the loop count.
|
|
100
107
|
- Run focused regression tests first, then relevant lint/type/build/test commands when feasible.
|
|
101
108
|
- Confirm validation assets were not weakened.
|
|
102
109
|
- Record command/artifact, result, skipped reason or `none`, highest Verification Ladder level reached, validation assets protected, and residual risk.
|
|
103
110
|
11. At completion, persist only durable knowledge:
|
|
104
111
|
- Root causes, fragile project-specific flows, accepted exceptions, or reusable regression-test recipes after scoring with the Importance Calibration System.
|
|
105
112
|
- Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:bugs-fix`, `entity:<entity>`, and one `memory:<tier>` tag.
|
|
106
|
-
12.
|
|
113
|
+
12. Write the Fix Closure Report per `references/audit-report-io.md`'s Fix Closure Report Contract (`audits/bugs/<YYYY-MM-DD bugs-fix-closure>.md`), then run `bun skills/massa-ai/scripts/check_fix_closure.ts <closure.md> --family bugs` before Propose and the Evidence Gate — a non-zero exit blocks both. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
|
|
114
|
+
13. Complete the Evidence Gate from `references/evidence-gate.md`.
|
|
107
115
|
|
|
108
116
|
## Examples
|
|
109
117
|
|
|
@@ -120,3 +128,6 @@ User asks: "Fix BUG-2 from audits/bugs/2026-06-07 bugs-audit.md."
|
|
|
120
128
|
1. Read the specified report and only execute `BUG-2`.
|
|
121
129
|
2. Preserve other bug findings for later.
|
|
122
130
|
3. Report evidence for `BUG-2` closure and residual risks.
|
|
131
|
+
|
|
132
|
+
<!-- validator anchors: "Independent Verification Exception", "the divergence-point fix just applied", "audits/bugs/<YYYY-MM-DD bugs-fix-closure>.md", "check_fix_closure.ts <closure.md> --family bugs", "The red→green reproduction proves the regression test catches this bug", "Bounded Fix→Re-verify Loop" -->
|
|
133
|
+
|
|
@@ -3,7 +3,7 @@ name: code-quality-fix
|
|
|
3
3
|
description: "Executes fixes from a saved code quality audit report; not for findings-only SOLID, Clean Code, KISS, YAGNI, DRY, or overengineering analysis."
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
|
-
version: "1.
|
|
6
|
+
version: "1.2.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
### Code Quality Fix
|
|
@@ -12,7 +12,7 @@ Execute fixes from a code quality audit markdown report only.
|
|
|
12
12
|
|
|
13
13
|
Load `references/project-context.md` (intake sweep) before the first substantive read.
|
|
14
14
|
|
|
15
|
-
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`.
|
|
15
|
+
Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate — its Stage 3 delivery-authorization scope covers one go-ahead through PR creation; force-push/deploy/merge stay separately gated) 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`.
|
|
16
16
|
|
|
17
17
|
**Isolation Gate — before the first file edit:** execute `references/implementation-delivery.md` Stage 0–1 now (fetch base, create the worktree + branch, work inside it) and record the worktree path + branch — or one of Stage 1's two legal skip reasons, verbatim — before any repository mutation.
|
|
18
18
|
|
|
@@ -24,9 +24,12 @@ Not for findings-only SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, or o
|
|
|
24
24
|
- `references/lessons.md` to load confirmed project lessons
|
|
25
25
|
- `references/codebase-investigation.md` before changing unfamiliar code
|
|
26
26
|
- `references/verification-ladder.md` before non-trivial edits
|
|
27
|
+
- `references/discrimination-sensor.md` before closing a behavior-preservation finding at Standard+/Spec-driven size or high/critical severity, to size the mutation-target sensor against the transformed code
|
|
28
|
+
- `references/knowledge-verification-chain.md` when the fix direction depends on an external library or API's current behavior rather than in-repo convention
|
|
27
29
|
- `references/naming-standards.md` before renaming identifiers, introducing domain vocabulary, or changing public contract names
|
|
28
30
|
- `references/context-firewall.md` before inspecting large diffs, logs, generated reports, or broad search output
|
|
29
31
|
- `references/agent-orchestration.md` only for large/high-risk findings, disjoint implementation slices, or independent verification
|
|
32
|
+
- `references/brownfield-mapping.md` (Minimum Bar) when a Standard+ finding's target has no recall hit and the report's evidence yields no derivable gate command
|
|
30
33
|
3. `recall` -> load project style rules, accepted quality exceptions, testing conventions, prior anti-patterns, and verification recipes for the report target.
|
|
31
34
|
4. Select the code quality audit report with execution focus:
|
|
32
35
|
- Establish the report selector, target focus, and optional finding selector before selecting a report. Target focus can be a module, service layer, files/globs, branch comparison, commit range, symbol/class/function, feature/flow, or explicit whole-repo target.
|
|
@@ -61,7 +64,7 @@ Not for findings-only SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, or o
|
|
|
61
64
|
- Run or identify characterization tests before changing behavior-adjacent code.
|
|
62
65
|
- Do not weaken tests, fixtures, snapshots, types, or public contracts to make cleanup pass.
|
|
63
66
|
- Prefer small reversible edits; verify after each finding or coherent group.
|
|
64
|
-
10. Use agent orchestration only when it improves signal. Dispatch per `references/agent-orchestration.md`:
|
|
67
|
+
10. Use agent orchestration only when it improves signal — except the verification-agent dispatch below, which `references/agent-orchestration.md`'s Independent Verification Exception mandates at the tiers named in its trigger regardless of signal improvement. Dispatch per `references/agent-orchestration.md`:
|
|
65
68
|
|
|
66
69
|
> **Dispatch: `massa-ai-builder`** (role: `builder`) — charter `skills/agents/builder/SKILL.md`
|
|
67
70
|
> - trigger: large/high-risk finding, disjoint implementation slice, or explicit subagent request
|
|
@@ -74,30 +77,31 @@ Not for findings-only SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, or o
|
|
|
74
77
|
> - memory: suggest-only; main agent persists reusable code-quality patterns
|
|
75
78
|
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
76
79
|
|
|
77
|
-
> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
|
|
78
|
-
> - trigger: independent verification of a high-risk code-quality fix
|
|
79
|
-
> - scope: the fixed finding's behavior preservation, imports, tests, and report claim closure
|
|
80
|
-
> - permissions: read-only
|
|
81
|
-
> - inputs: the finding, the applied fix, the verification suggestion, and validation assets
|
|
82
|
-
> - sensors: deterministic command (behavior-preservation check, import graph, tests) and report claim closure
|
|
83
|
-
> - output: confirmed/disproven closure verdict with evidence
|
|
84
|
-
> - firewall: raw test output/logs summarized
|
|
85
|
-
> - memory: suggest-only; main agent persists reusable verification recipes
|
|
86
|
-
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
87
|
-
- Main agent owns report parsing, prioritization, memory writes, final synthesis, and Evidence Gate.
|
|
88
|
-
|
|
89
80
|
> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
|
|
90
|
-
> - trigger: implementation complete, before the verification gate — never optional
|
|
81
|
+
> - trigger: implementation of the CQ finding complete, before the verification gate — never optional
|
|
91
82
|
> - scope: the fix's diff surface and its task/AC context
|
|
92
83
|
> - permissions: read-only
|
|
93
|
-
> - inputs: diff, acceptance context, recalled code-quality conventions
|
|
84
|
+
> - inputs: diff, CQ acceptance context, recalled code-quality conventions
|
|
94
85
|
> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
|
|
95
|
-
> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
|
|
86
|
+
> - output: ranked findings, blocking vs advisory; blocking findings become CQ fix items before verification runs
|
|
96
87
|
> - firewall: summarized findings only, never raw diff dumps
|
|
97
|
-
> - memory: suggest-only; main agent persists
|
|
88
|
+
> - memory: suggest-only; main agent persists review outcomes for the code-quality fix
|
|
98
89
|
> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
|
|
99
90
|
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
100
91
|
|
|
92
|
+
> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
|
|
93
|
+
> - trigger: mandatory per the verification-ladder's Independent Verification Mandate at Standard+/Spec-driven finding size or high/critical severity; at Quick size the subagent hop is skipped and the standalone fresh-eyes check below runs instead
|
|
94
|
+
> - scope: the fixed finding's behavior-preservation claim over the moved/transformed code, its call sites/imports, and report claim closure
|
|
95
|
+
> - permissions: read-only
|
|
96
|
+
> - inputs: the finding, the applied fix, the verification suggestion, and validation assets
|
|
97
|
+
> - sensors: deterministic command (behavior-preservation check, import graph, characterization tests); discrimination sensor per `references/discrimination-sensor.md` (mutate the pre-fix moved/transformed code the behavior-preservation claim protects, never newly introduced code)
|
|
98
|
+
> - output: confirmed/disproven closure verdict with evidence
|
|
99
|
+
> - firewall: raw test output/logs summarized
|
|
100
|
+
> - memory: suggest-only; main agent persists code-quality verification outcomes
|
|
101
|
+
> - fallback: if the subagent is unavailable, run a standalone fresh-eyes re-check of the code-quality closure evidence against this output contract and record the skipped-delegation reason
|
|
102
|
+
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
103
|
+
- Main agent owns report parsing, prioritization, memory writes, final synthesis, and Evidence Gate.
|
|
104
|
+
|
|
101
105
|
11. Verify each completed finding:
|
|
102
106
|
- If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
|
|
103
107
|
`bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
|
|
@@ -108,10 +112,16 @@ Not for findings-only SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, or o
|
|
|
108
112
|
- Perform a focused diff review for touched identifiers and confirm generic names are either replaced with precise domain/role names or justified by narrow conventional scope.
|
|
109
113
|
- Check validation assets were not weakened unless explicitly requested.
|
|
110
114
|
- Record command/artifact, result, skipped reason or `none`, highest Verification Ladder level reached, validation assets protected, and residual risk.
|
|
111
|
-
|
|
115
|
+
- At the same Standard+/Spec-driven-or-high/critical tiers as the Independent Verification Mandate, run the discrimination sensor from `references/discrimination-sensor.md` against the pre-fix moved/transformed code the behavior-preservation claim protects; Quick mechanical transforms (rename, inline, delete) are exempt. A surviving mutant is an unproven preservation claim: strengthen the characterization test or close the row `blocked` and emit the `surviving_mutant` lessons signal — do not mark it `fixed`.
|
|
116
|
+
- When a survivor traces to cross-boundary coupling rather than a weak assertion, route it through this workflow's step 5 reclassification gate (bounded-context/dependency-direction/seam/module-depth invalidity check) to `workflows/architecture/architecture-fix.md` instead of forcing a local fix.
|
|
117
|
+
- The fix→re-verify cycle is capped per `references/verification-ladder.md`'s Bounded Fix→Re-verify Loop; exceeding the cap stops the finding at `Blocked` with evidence preserved. That cap is a separate counter from the two-consecutive-failed-fixes breaker in the preamble above — the breaker fires inside a single iteration and neither consumes nor resets the cap.
|
|
118
|
+
12. Close out with the Fix Closure Report:
|
|
119
|
+
- Write the Fix Closure Report per `references/audit-report-io.md` (Fix Closure Report Contract) to `audits/code-quality/<YYYY-MM-DD code-quality-fix-closure>.md`, one Closure Matrix row per selected finding.
|
|
120
|
+
- Run `bun skills/massa-ai/scripts/check_fix_closure.ts <closure.md> --family code-quality` before Propose/Evidence Gate; a non-zero exit blocks Propose. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
|
|
121
|
+
13. At completion, persist only durable knowledge:
|
|
112
122
|
- Repeated anti-patterns, accepted quality exceptions, project-specific refactoring recipes, or reusable checks after scoring with the Importance Calibration System.
|
|
113
123
|
- Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:code-quality-fix`, `entity:<entity>`, and one `memory:<tier>` tag.
|
|
114
|
-
|
|
124
|
+
14. Complete the Evidence Gate from `references/evidence-gate.md`.
|
|
115
125
|
|
|
116
126
|
## Examples
|
|
117
127
|
|
|
@@ -122,3 +132,6 @@ User asks: "Use code-quality-fix to fix latest findings for billing services."
|
|
|
122
132
|
3. Execute confirmed non-suspect findings by severity and behavior risk.
|
|
123
133
|
4. Prefer delete/inline/rename/extract before introducing new abstractions.
|
|
124
134
|
5. Verify behavior and validation assets after each finding group.
|
|
135
|
+
|
|
136
|
+
<!-- validator anchors: references/discrimination-sensor.md; references/knowledge-verification-chain.md; references/brownfield-mapping.md; Independent Verification Exception; Fix Closure Report Contract; check_fix_closure.ts --family code-quality; Bounded Fix→Re-verify Loop; Stage 3 delivery-authorization scope -->
|
|
137
|
+
|
|
@@ -3,7 +3,7 @@ name: debug
|
|
|
3
3
|
description: "Use this workflow for evidence-backed root-cause diagnosis of broken behavior, failures, regressions, or crashes; route new capabilities to feature and broad redesign to spec-driven."
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
|
-
version: "1.
|
|
6
|
+
version: "1.2.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
### 🔴 Debug
|
|
@@ -36,29 +36,33 @@ Before the first repository mutation, load `references/implementation-delivery.m
|
|
|
36
36
|
`search.sessionId`.
|
|
37
37
|
- For large files (>200 lines) or derived-value computation, call `execute_file` with `path`, `language`, and `code` to run analysis code over the file instead of loading the entire file into context. Respect the local-dev-only trust model (no untrusted-client exposure).
|
|
38
38
|
- After opening a file for deep investigation, call `synapse_prefetch` with `id` (the `synapseSessionId`) and `filePath` to warm the Synapse buffer before the next search. Requires an existing `synapse_session` id.
|
|
39
|
-
6.
|
|
39
|
+
6. IF step 3's `recall` returned no hit for the debug target AND no `.specs/project/onboarding/` docs already exist for this codebase: run the brownfield Minimum Bar gate in `references/brownfield-mapping.md` — derive `TESTING.md` (feeds the feedback loop's gate commands in step 7) and `CONCERNS.md` (feeds the Hypothesis Board's ranking in step 9) under `.specs/project/onboarding/`. A fix that already looks Quick-sized may proceed on `TESTING.md` alone.
|
|
40
|
+
7. Build or request a trustworthy feedback loop before editing:
|
|
40
41
|
- Use the reproduction ladder in `references/debug-diagnosis-loop.md`: unit/CLI repro, integration/API repro, app/browser/device repro, then structured HITL.
|
|
41
42
|
- IF no loop can run, record a skipped-reason enum from the debug reference and collect the strongest root-cause proof available
|
|
42
|
-
|
|
43
|
-
|
|
43
|
+
8. Reproduce and minimize the user-described failure without losing the original failure signal
|
|
44
|
+
9. Rank 3-5 falsifiable hypotheses before testing:
|
|
44
45
|
- include evidence, prediction, probe, disproof criteria, and tested result
|
|
45
46
|
- test one hypothesis at a time; instrument only to answer the current hypothesis
|
|
46
47
|
- for flaky failures, measure and improve reproduction rate before root-cause guessing
|
|
47
|
-
|
|
48
|
+
- When a hypothesis's disproof turns on external library/API behavior (a narrow case — most debug work is internal to this codebase), run the chain in `references/knowledge-verification-chain.md` before accepting or ruling out that hypothesis.
|
|
49
|
+
10. Apply debugging heuristics (see `references/decision-engine.md`):
|
|
48
50
|
- Trace data flow: input → transformation → output
|
|
49
51
|
- Compare expected vs actual behavior
|
|
50
52
|
- Check recent changes first
|
|
51
53
|
- Minimize search space to relevant modules
|
|
52
54
|
- For call/data-flow path tracing, call `trace_path` with `function_name` (or `qualifiedName`), `project`, `direction` (outbound/inbound/both), `mode` (calls/data_flow/cross_service/all), and `depth` to trace typed-edge BFS paths. `trace_path` only counts as evidence when the index is fresh for the current repository path and commit/worktree state; fall back to `search`/`get_references` and record reduced retrieval confidence when the index is stale or unavailable.
|
|
53
|
-
|
|
55
|
+
11. Size the fix before editing:
|
|
54
56
|
- Use the exact Quick, Standard, and Spec-driven thresholds in `references/verification-ladder.md`.
|
|
55
57
|
- Refactor route applies only when the fix becomes behavior-preserving cleanup after the root cause is proven.
|
|
56
|
-
|
|
58
|
+
12. Define the verification recipe before changing code:
|
|
57
59
|
- reproduction or root-cause proof
|
|
58
60
|
- commands, tests, or artifact checks that prove the fix
|
|
59
61
|
- file-integrity checks for validation assets such as tests, specs, benchmarks, fixtures, and snapshots
|
|
60
|
-
|
|
61
|
-
|
|
62
|
+
13. Fix the divergence point closest to the root cause
|
|
63
|
+
14. Add regression coverage at the correct seam, or document why no valid regression seam exists:
|
|
64
|
+
- (a) write the test first, asserting the exact previously-broken behavior at the divergence point
|
|
65
|
+
- (b) at Standard+, prove the coverage discriminates: run the sensor in `references/discrimination-sensor.md` against the just-fixed code; a surviving mutant means the regression test does not yet prove the fix
|
|
62
66
|
|
|
63
67
|
> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
|
|
64
68
|
> - trigger: implementation complete, before the verification gate — never optional
|
|
@@ -72,19 +76,32 @@ Before the first repository mutation, load `references/implementation-delivery.m
|
|
|
72
76
|
> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
|
|
73
77
|
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
74
78
|
|
|
75
|
-
|
|
79
|
+
> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
|
|
80
|
+
> - trigger: mandatory at Standard+/Spec-driven fix size, per the Independent Verification Mandate tier gate in `references/verification-ladder.md`; a Quick-tier fix takes the fallback below instead
|
|
81
|
+
> - scope: the fixed divergence point from step 13, its reproduction path, and the regression test added in step 14
|
|
82
|
+
> - permissions: read-only
|
|
83
|
+
> - inputs: the root cause, the reproduction evidence, the regression test, and the changed files — not spec acceptance criteria
|
|
84
|
+
> - sensors: re-run of the reproduction/feedback loop confirming the original failure signal no longer reproduces; discrimination sensor per `references/discrimination-sensor.md` (mutate the fixed code; the regression test must kill it)
|
|
85
|
+
> - output: confirmed/disproven root-cause-closure verdict with evidence
|
|
86
|
+
> - firewall: raw reproduction transcripts and logs summarized, never raw dumps
|
|
87
|
+
> - memory: suggest-only; main agent persists debug verification outcomes
|
|
88
|
+
> - fallback: if the subagent is unavailable, run a standalone fresh-eyes re-check of root cause, reproduction, and regression coverage, and record the skipped-delegation reason
|
|
89
|
+
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
90
|
+
|
|
91
|
+
15. If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
|
|
76
92
|
`bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
|
|
77
|
-
Rerun the original feedback loop, run the verification recipe, and remove temporary instrumentation unless intentionally retained as observability
|
|
78
|
-
|
|
79
|
-
|
|
93
|
+
Rerun the original feedback loop, run the verification recipe, and remove temporary instrumentation unless intentionally retained as observability. The fix → re-verify cycle is capped by `references/verification-ladder.md`'s Bounded Fix→Re-verify Loop; a reached cap stops the session `Blocked` with the evidence preserved. That cap counts re-verify cycles across the whole symptom and is a separate counter from the two-consecutive-failed-fixes breaker into `references/root-cause-scripts.md` named in this file's preamble — that breaker fires inside a single edit iteration and neither consumes nor resets the re-verify count.
|
|
94
|
+
16. Use `references/agent-orchestration.md` for isolated investigation branches; the Standard+ verifier dispatch above is mandated by that reference's Independent Verification Exception, not merely loaded when it improves signal.
|
|
95
|
+
17. IF fix found:
|
|
80
96
|
- Persist the root cause via `remember` as a scored `decision` memory with `memory:semantic`
|
|
81
97
|
- Persist the fix pattern via `remember` as a scored `pattern` memory with `memory:procedural`
|
|
82
98
|
- If a prior debugging memory for this entity is now stale or contradicted by the fix, call `memory_update` with its `id` and the corrected `content` (re-embeds automatically)
|
|
83
|
-
|
|
99
|
+
18. IF NOT resolved:
|
|
84
100
|
- Persist what was ruled out via `remember` as a scored `conversation` memory with `memory:episodic`
|
|
85
101
|
- Persist repeated failed tool loops as procedural cognition lessons only when they are reusable
|
|
86
102
|
- Document remaining hypotheses for future sessions
|
|
87
|
-
|
|
103
|
+
19. At Standard+ size, serialize this file's Output Contract sections into `.specs/debug/<slug>/REPORT.md` and run `bun skills/massa-ai/scripts/check_specs_delivered.ts <slug> --kind debug` before the Evidence Gate; a non-zero exit blocks completion. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved). See `references/artifact-persistence.md` for the canonical-store and precedence rules governing this artifact.
|
|
104
|
+
20. Complete the Evidence Gate from `references/evidence-gate.md`
|
|
88
105
|
|
|
89
106
|
## Output Contract
|
|
90
107
|
|
|
@@ -96,6 +113,12 @@ Before the first repository mutation, load `references/implementation-delivery.m
|
|
|
96
113
|
- Prevention: regression test, monitor/runbook suggestion, and memory outcome
|
|
97
114
|
- For mobile bugs: device matrix, platform parity, crash/log artifact, and impacted/unaffected platform validation
|
|
98
115
|
|
|
116
|
+
## Failure Handling
|
|
117
|
+
|
|
118
|
+
- `.specs/debug/<slug>/` unwritable at Standard+: block the `REPORT.md` write and record the blocker; never substitute a memory write or chat summary for the canonical debug artifact.
|
|
119
|
+
- Fix → re-verify loop reaches the `references/verification-ladder.md` cap: stop the session `Blocked`, preserve the collected reproduction and verification evidence, and ask the user for direction.
|
|
120
|
+
- Discrimination sensor mutation on the fixed divergence point is not safely reversible: mark `Blocked` unless the verification-agent can show equivalent discrimination from an existing deterministic mutation fixture.
|
|
121
|
+
|
|
99
122
|
## Example
|
|
100
123
|
|
|
101
124
|
User asks: "The login route returns 500 after deploy."
|
|
@@ -107,3 +130,7 @@ User asks: "The login route returns 500 after deploy."
|
|
|
107
130
|
5. Trace request → auth middleware → session lookup → response, then fix the divergence point closest to the root cause.
|
|
108
131
|
6. Define the verification recipe: rerun the original route check, add or update regression coverage at the failing seam, and confirm validation assets were not weakened.
|
|
109
132
|
7. If root cause is a missing `DATABASE_URL`, persist via `remember`: a semantic decision memory for the root cause and a procedural pattern memory for the deploy-env verification command.
|
|
133
|
+
8. At Standard+ size, dispatch `massa-ai-verification-agent` to independently re-run the reproduction against the `DATABASE_URL` fix and confirm the regression test kills a mutant on the restored connection check before closing.
|
|
134
|
+
|
|
135
|
+
<!-- validator anchors: brownfield Minimum Bar gate | references/knowledge-verification-chain.md | prove the coverage discriminates | Dispatch: `massa-ai-verification-agent` | Independent Verification Exception | Bounded Fix→Re-verify Loop | .specs/debug/<slug>/REPORT.md | check_specs_delivered.ts <slug> --kind debug | graceful degradation preserved | references/artifact-persistence.md | ## Failure Handling -->
|
|
136
|
+
|
|
@@ -26,22 +26,7 @@ Write and search in the user's human language. Match the user's prompt language
|
|
|
26
26
|
|
|
27
27
|
## Knowledge Verification Chain
|
|
28
28
|
|
|
29
|
-
When researching or resolving any technical question during exploration, follow
|
|
30
|
-
|
|
31
|
-
```
|
|
32
|
-
Step 1: Codebase → existing code, conventions, patterns already in use
|
|
33
|
-
Step 2: Project docs (leads, not truth) → README, docs/, inline comments, .specs/project/STATE.md (Decisions) — verify against current source before relying
|
|
34
|
-
Step 3: Context7 MCP → resolve library ID, then query for current API/patterns
|
|
35
|
-
Step 4: Web search → official docs, reputable sources, community patterns
|
|
36
|
-
Step 5: Flag as uncertain → "I'm not certain about X — here's my reasoning, but verify"
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
- If a chain step's tool is unavailable (Context7 MCP not registered, no web
|
|
40
|
-
access), record it as a skipped sensor with its reason and continue to the next
|
|
41
|
-
step. An unavailable step is skipped, never silently treated as answered.
|
|
42
|
-
- Never skip to Step 5 if Steps 1-4 are available.
|
|
43
|
-
- Step 5 is always flagged uncertain — never presented as fact.
|
|
44
|
-
- Never assume or fabricate. If no answer is found, say "I don't know" or "I couldn't find documentation for this". "I don't know" beats invention.
|
|
29
|
+
When researching or resolving any technical question during exploration, follow the 5-step chain in `references/knowledge-verification-chain.md` in strict order — codebase, project docs, Context7 MCP, web search, then flag-as-uncertain. Never skip steps, record an unavailable step as a skipped sensor with its reason, and never present Step 5 output as fact. "I don't know" beats invention.
|
|
45
30
|
|
|
46
31
|
1. Resolve/reuse `projectId` and `workflowSessionId`: `explore-[entity]`.
|
|
47
32
|
2. Load shared references:
|
|
@@ -3,7 +3,7 @@ name: feature
|
|
|
3
3
|
description: "Use this workflow to add a new capability, screen, command, integration, or user-facing improvement with clear intent; route broken behavior to debug and broad work to spec-driven."
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
|
-
version: "1.
|
|
6
|
+
version: "1.2.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
### 🟡 Feature
|
|
@@ -28,6 +28,8 @@ Before the first repository mutation, load `references/implementation-delivery.m
|
|
|
28
28
|
- `references/naming-standards.md` before writing or renaming code identifiers, public contract fields, tests, fixtures, or implementation-facing design names
|
|
29
29
|
- `references/pr-task-fix.md` when the verification ladder trigger table applies
|
|
30
30
|
- `references/lessons.md` when `.specs/lessons.json` exists, to load confirmed project lessons before sizing
|
|
31
|
+
- `references/knowledge-verification-chain.md` when the feature depends on an external library or API whose behavior is not already established from this codebase, running the 5-step chain (codebase → project docs → Context7 → web → flag-uncertain) before relying on that dependency's behavior
|
|
32
|
+
- `references/brownfield-mapping.md` (Minimum Bar only — CONCERNS.md + TESTING.md) when the feature touches an area this codebase does not already document; the full onboarding need stays the existing route-to-`workflows/spec-driven.md` boundary stated above for broad, ambiguous, or cross-boundary work, not a new escalation here
|
|
31
33
|
4. For Android, iOS, KMP Compose Multiplatform UI, or work whose target matches the enumerated mobile-context trigger set (KMP, iOS, Android, native bridges, mobile lifecycle, offline/sync, permissions, push/background behavior, local persistence, or backend-mobile contracts), run the design-source intake gate from `references/mobile-context.md` (Design-Source Intake Gate) before implementation.
|
|
32
34
|
5. Size the task before implementation:
|
|
33
35
|
- Use the exact Quick, Standard, and Spec-driven thresholds in `references/verification-ladder.md`.
|
|
@@ -40,13 +42,14 @@ Before the first repository mutation, load `references/implementation-delivery.m
|
|
|
40
42
|
8. Establish the verification recipe before Standard edits and before Quick edits that touch validation assets, including file-integrity checks for tests, specs, benchmarks, fixtures, and snapshots used as validation assets
|
|
41
43
|
- Include a focused naming review when the feature introduces or renames identifiers. New names should use domain or precise role vocabulary, and public/persisted names should not change without explicit compatibility handling.
|
|
42
44
|
9. For mobile features, capture the mobile context packet, choose shared vs platform-specific boundaries, state platform parity expectations, and include the cheapest relevant mobile verification sensor from `references/mobile-context.md`
|
|
43
|
-
10. Use `references/agent-orchestration.md`
|
|
44
|
-
11. Capture 1-5 testable acceptance criteria in the conversation before implementation starts, or reference an existing spec artifact (e.g. `.specs/features/<slug>/spec.md`) when one already states them. These captured acceptance criteria are the anchor the verification step below checks outcomes against.
|
|
45
|
+
10. Use `references/agent-orchestration.md` for isolated implementation slices; independent verification is not merely an optional signal-improving choice here — the Independent Verification Exception in that reference mandates a separate verifier at Standard tier and above (dispatch block after PR-group implementation, below)
|
|
46
|
+
11. Capture 1-5 testable acceptance criteria in the conversation before implementation starts, or reference an existing spec artifact (e.g. `.specs/features/<slug>/spec.md`) when one already states them. These captured acceptance criteria are the anchor the verification step below checks outcomes against. Persist them per tier per `references/artifact-persistence.md`: Quick work writes `.specs/quick/NNN-slug/TASK.md` (plus `SUMMARY.md` at completion); Standard tier and above write `.specs/features/<slug>/spec.md` and, once verified, `validation.md`, reusing spec-driven's shape so `validate_state.ts` and the delivery Stage 3.5 gate work unmodified. An unwritable artifact location blocks the workflow rather than proceeding silently.
|
|
45
47
|
12. Implement the feature by PR group when `references/pr-task-fix.md` applies:
|
|
46
48
|
- Order non-breaking groups by Data, Domain, then Presentation/Navigation, mapping those labels to repository boundaries when needed.
|
|
47
49
|
- Validate each group with the verification recipe before committing.
|
|
48
50
|
- Invoke `workflows/commit.md` for each verified group; do not duplicate commit staging, message, audit-exclusion, or Jira-prefix rules in this workflow.
|
|
49
51
|
- When every group has a confirmed Jira key, follow the optional stacked branch flow in `references/pr-task-fix.md` (Jira-Key Stacked Branches).
|
|
52
|
+
- All PR groups decomposed under this feature share one feature-level delivery go-ahead: no individual group seeks or receives its own Stage 3 sign-off — see `references/implementation-delivery.md` Stage 3.
|
|
50
53
|
|
|
51
54
|
> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
|
|
52
55
|
> - trigger: implementation complete, before the verification gate — never optional
|
|
@@ -60,10 +63,27 @@ Before the first repository mutation, load `references/implementation-delivery.m
|
|
|
60
63
|
> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
|
|
61
64
|
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
62
65
|
|
|
63
|
-
|
|
66
|
+
> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
|
|
67
|
+
> - trigger: Standard tier or above per the Independent Verification Mandate in `references/verification-ladder.md` — mandatory once every implemented PR group has cleared reviewer fix items; Quick tier substitutes the fallback below
|
|
68
|
+
> - scope: the new code landed across this feature's PR groups from step 12, plus the tests and validation assets those groups touch
|
|
69
|
+
> - permissions: read-only
|
|
70
|
+
> - inputs: the 1-5 acceptance criteria captured in step 11 (or the referenced spec artifact) as the outcome source, the feature's diff surface across all PR groups, and its test suite
|
|
71
|
+
> - sensors: check the diff and tests against each acceptance criterion; discrimination sensor per `references/discrimination-sensor.md` (mutate the feature's new code, one PR group at a time — covering tests must kill each mutant or that group is not verified)
|
|
72
|
+
> - output: a pass/fail verdict per acceptance criterion, any surviving-mutant findings, and an overall verified/blocked verdict per PR group
|
|
73
|
+
> - firewall: summarized per-AC and per-mutant findings only, never raw diff dumps
|
|
74
|
+
> - memory: suggest-only; main agent persists feature verification outcomes
|
|
75
|
+
> - fallback: if the subagent is unavailable, run a standalone fresh-eyes re-check of each AC against the diff and tests, and record the skipped-delegation reason
|
|
76
|
+
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
77
|
+
|
|
78
|
+
If verification fails, bound the retry with the Bounded Fix→Re-verify Loop cap from `references/verification-ladder.md`: at most 3 fix→re-verify iterations on the same PR group before reporting `Blocked`. This cap governs the post-implementation review/verify cycle and is distinct from the two-consecutive-failed-fixes trigger earlier in this file that loads `references/root-cause-scripts.md`, which fires on repeated failed attempts to fix one symptom during implementation itself.
|
|
79
|
+
|
|
80
|
+
13. Run the verification recipe and check outcomes against the captured acceptance criteria from step 11, not only against a generic verification recipe; report skipped checks explicitly. At Standard tier and above, back this with `bun skills/massa-ai/scripts/validate_state.ts <slug>` against the persisted `validation.md` — it must be real, report `PASS`, and cite `file:line` evidence per acceptance criterion. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved). If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
|
|
64
81
|
`bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
|
|
65
82
|
14. At completion, persist (run the scoring rubric from `references/decision-engine.md` for each):
|
|
66
83
|
- Design decisions made via `remember` as scored `decision` memories
|
|
67
84
|
- New patterns introduced via `remember` as scored `pattern` memories
|
|
68
85
|
- Trade-offs accepted via `remember` as scored `conversation` memories
|
|
69
86
|
15. Complete the Evidence Gate from `references/evidence-gate.md`
|
|
87
|
+
|
|
88
|
+
<!-- validator anchors: massa-ai-verification-agent dispatch block; Independent Verification Mandate (Standard tier and above); Bounded Fix→Re-verify Loop cap (3 iterations); validate_state.ts <slug> deterministic backing; graceful degradation preserved; .specs/quick/NNN-slug/TASK.md and SUMMARY.md; .specs/features/<slug>/spec.md and validation.md; one feature-level delivery go-ahead across PR groups -->
|
|
89
|
+
|
|
@@ -3,7 +3,7 @@ name: general
|
|
|
3
3
|
description: "Final fallback workflow for coding, planning, review, or implementation work when no specialized massa-ai workflow is a better match."
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
|
-
version: "1.
|
|
6
|
+
version: "1.2.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
### General Coding Workflow
|
|
@@ -17,8 +17,8 @@ Before the first repository mutation, load `references/implementation-delivery.m
|
|
|
17
17
|
**Isolation Gate — before the first file edit:** execute `references/implementation-delivery.md` Stage 0–1 now (fetch base, create the worktree + branch, work inside it) and record the worktree path + branch — or one of Stage 1's two legal skip reasons, verbatim — before any repository mutation.
|
|
18
18
|
|
|
19
19
|
1. Resolve or reuse `projectId` and a stable `workflowSessionId`: `general-[entity]`.
|
|
20
|
-
2. Run General fallback preflight before source work: name the specialized workflow considered, the exact rejected reason, and why fallback does not change verification, mutation behavior, or memory scope. Ask the user only when the rejected workflow would change those behaviors.
|
|
21
|
-
3. Recall relevant durable context with `recall`. Treat recalled memory as a lead until current source confirms it. Confirm against current source before relying on it only when the change touches the enumerated risk-domain set: public API, data loss, auth/PII, migrations, or cross-service contracts. Otherwise trust recalled memory and cite it with a one-line source note.
|
|
20
|
+
2. Run General fallback preflight before source work: name the specialized workflow considered, the exact rejected reason, and why fallback does not change verification, mutation behavior, or memory scope. Ask the user only when the rejected workflow would change those behaviors. One delivery authorization obtained here covers the fallback change's commits, push, and PR creation; force-push, deploy, or merge are separately gated (`references/implementation-delivery.md` Stage 3).
|
|
21
|
+
3. Recall relevant durable context with `recall`. Treat recalled memory as a lead until current source confirms it. Confirm against current source before relying on it only when the change touches the enumerated risk-domain set: public API, data loss, auth/PII, migrations, or cross-service contracts. Otherwise trust recalled memory and cite it with a one-line source note. When recall returns no hit and the repository is otherwise unmapped on Standard+ fallback work, run the Minimum Bar sweep from `references/brownfield-mapping.md` first, writing only `CONCERNS.md` and `TESTING.md` into `.specs/project/onboarding/` before continuing.
|
|
22
22
|
4. Create a Synapse session when planned related `search` calls >=2, following `references/synapse-policy.md`.
|
|
23
23
|
5. Load confirmed project lessons through `references/lessons.md` when `.specs/lessons.json` exists:
|
|
24
24
|
`bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed`
|
|
@@ -29,6 +29,7 @@ Before the first repository mutation, load `references/implementation-delivery.m
|
|
|
29
29
|
- prefer current repository truth over stale or conflicting memories
|
|
30
30
|
6. Execute the requested work using existing repository conventions. Tie verification depth to the Verification Ladder tier table in `references/verification-ladder.md`: Quick (<=3 files and <=200 changed LOC) runs static + file-integrity checks; Standard (<=10 files or <=500 changed LOC) adds a named verification recipe and behavioral checks; Spec-driven (>10 files, >500 changed LOC) escalates to `workflows/spec-driven.md`. Do not invent new thresholds; load specialized references only when the task needs their exact contracts.
|
|
31
31
|
- For analysis that benefits from running code (derived values, data inspection, bulk transforms), call `execute` with `language` and `code` or `batch_execute` with `commands`[] instead of loading raw data into context. Respect the local-dev-only trust model (no untrusted-client exposure).
|
|
32
|
+
- When the chosen approach leans on an external library's or API's exact behavior, resolve it through the 5-step chain in `references/knowledge-verification-chain.md` (codebase, project docs, Context7, web, flag-uncertain) before committing to that approach — the trigger is the dependence itself, not the task's Quick/Standard/Spec-driven tier.
|
|
32
33
|
7. Use `compress` only when accumulated source or conversation context is reducing execution quality; preserve decisions, constraints, current state, and next steps rather than raw history.
|
|
33
34
|
8. Before completion, if verification found a reusable signal, record it via `references/lessons.md`. Score potential memories using `references/decision-engine.md` when that guidance is not already loaded:
|
|
34
35
|
`bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
|
|
@@ -49,12 +50,30 @@ Before the first repository mutation, load `references/implementation-delivery.m
|
|
|
49
50
|
> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
|
|
50
51
|
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
51
52
|
|
|
52
|
-
|
|
53
|
+
> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
|
|
54
|
+
> - trigger: fallback work reaching Standard+ on the Verification Ladder, or any Quick-sized change inside the risk-domain set named in step 3 (public API, data loss, auth/PII, migrations, cross-service) — the Independent Verification Mandate in `references/verification-ladder.md` applies at that gate even when file/LOC counts stay Quick
|
|
55
|
+
> - scope: the fallback change's diff surface plus the acceptance evidence gathered while executing step 6
|
|
56
|
+
> - permissions: read-only
|
|
57
|
+
> - inputs: diff, the General fallback preflight rationale, reviewer findings, recalled conventions
|
|
58
|
+
> - sensors: independent outcome-vs-request re-check; discrimination sensor per `references/discrimination-sensor.md`, mutating the fallback change's own logic in scratch state
|
|
59
|
+
> - output: PASS/FAIL verdict with per-check evidence recorded in `.specs/quick/NNN-slug/SUMMARY.md`
|
|
60
|
+
> - firewall: summarized findings only, never raw diff dumps
|
|
61
|
+
> - memory: suggest-only; main agent persists general-workflow verification outcomes
|
|
62
|
+
> - fallback: if the subagent is unavailable, run a standalone fresh-eyes re-check of the change against its acceptance evidence and record the skipped-delegation reason
|
|
63
|
+
> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
|
|
64
|
+
|
|
65
|
+
9. At Standard+ size, persist `.specs/quick/NNN-slug/TASK.md` and `SUMMARY.md` using the templates in `references/artifact-persistence.md`, then run `bun skills/massa-ai/scripts/check_specs_delivered.ts <slug> --kind quick` before the Evidence Gate — a non-zero exit blocks completion. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
|
|
66
|
+
10. Complete the Evidence Gate from `references/evidence-gate.md` and report verification, changed artifacts, memory outcome, and residual risk.
|
|
53
67
|
|
|
54
68
|
## Failure Handling
|
|
55
69
|
|
|
56
70
|
On any tool/index/MCP failure, follow `references/graceful-degradation.md` (also `SKILL.md` Graceful Degradation).
|
|
57
71
|
|
|
72
|
+
- `.specs/` directory missing or not writable: block quick-artifact and onboarding-doc writes per `references/artifact-persistence.md`'s unwritable-→-block rule; do not fall back to memory or chat.
|
|
73
|
+
- Verifier fix→re-verify loop reaches the cap in `references/verification-ladder.md`'s Bounded Fix→Re-verify Loop: stop with `Blocked`, preserve the evidence collected, and ask the user for direction.
|
|
74
|
+
|
|
75
|
+
**Disambiguation — two different counters:** the loop cap above counts *verification* iterations on the fallback change as a whole. It is separate from the two-consecutive-failed-fix trigger near the top of this workflow that loads `references/root-cause-scripts.md` — that one counts *edit attempts* on a single symptom inside one iteration. Neither counter resets or consumes the other.
|
|
76
|
+
|
|
58
77
|
## Output Contract
|
|
59
78
|
|
|
60
79
|
- Goal and selected fallback workflow
|
|
@@ -64,3 +83,6 @@ On any tool/index/MCP failure, follow `references/graceful-degradation.md` (also
|
|
|
64
83
|
- Verification performed and skipped checks
|
|
65
84
|
- Memory written or intentionally skipped, with reason
|
|
66
85
|
- Residual risk
|
|
86
|
+
|
|
87
|
+
<!-- validator anchors: massa-ai-verification-agent dispatch block; Independent Verification Mandate; risk-domain set named in step 3; check_specs_delivered.ts --kind quick; .specs/quick/NNN-slug/SUMMARY.md; Minimum Bar sweep; .specs/project/onboarding/; Bounded Fix→Re-verify Loop; Disambiguation — two different counters; Stage 3 delivery authorization -->
|
|
88
|
+
|