@tamsensedev/runner 0.0.0-stage → 0.1.0

package/library/skills/false-positive-check/references/deep-verification.md

@@ -0,0 +1,113 @@
+# Deep Verification
+
+Full verification for complex bugs. Use when routing in SKILL.md selects the deep path, or when standard verification escalates.
+
+## If Escalated from Standard
+
+1. Review all evidence gathered during the standard pass; do not repeat completed work.
+2. Identify which phases below are already satisfied by existing evidence.
+3. Continue from where standard verification left off.
+4. Keep and reference all prior findings.
+
+## Phases
+
+Work through the phases in order for each bug (Bug #N). Keep a checklist in your notes and mark a phase done only when you have concrete evidence for it. Sub-steps within a phase are independent; do them in any order, but never start a phase before the one it depends on is complete. If the bug path is large, you may hand a phase's data-flow tracing to the `code-explorer` agent, with the bug description and prior evidence in the prompt; you still judge the result.
+
+```
+Phase 1: Data flow analysis
+  1.1 Map trust boundaries and trace data flow
+  1.2 Research API contracts and safety guarantees
+  1.3 Environment protection analysis
+  1.4 Cross-reference analysis
+Phase 2: Exploitability verification (after phase 1)
+  2.1 Confirm attacker controls input data
+  2.2 Mathematical bounds verification (or N/A)
+  2.3 Race condition feasibility proof (or N/A)
+  2.4 Adversarial analysis (after 2.1 to 2.3)
+Phase 3: Impact assessment (after phase 2)
+  3.1 Demonstrate real security impact
+  3.2 Primary control vs defense in depth
+Phase 4: PoC creation (after phase 3)
+  4.1 Pseudocode PoC with data flow diagram
+  4.2 Executable PoC if feasible
+  4.3 Unit test PoC if feasible
+  4.4 Negative PoC: exploit preconditions
+  4.5 Verify the PoC demonstrates the vulnerability
+Phase 5: Devil's advocate review (after phase 4)
+Gate review (after phase 5)
+```
+
+Apply all 13 checklist items from [false-positive-patterns.md](false-positive-patterns.md) to each bug.
+
+## Phase Requirements
+
+The list above names every phase. Below are the key pitfalls and decision criteria for each: focus on what you might get wrong.
+
+### Phase 1: Data Flow Analysis
+
+**1.1**: Map trust boundaries (internal/trusted vs external/untrusted) and trace data from source to the alleged vulnerability. Apply class-specific verification from [bug-class-verification.md](bug-class-verification.md). **Key pitfall**: analyzing code in isolation without tracing the full validation chain. Conditional logic upstream may make the vulnerable code mathematically unreachable (see [false-positive-patterns.md](false-positive-patterns.md) items 1 and 1a).
+
+**1.2**: Check API contracts before claiming overflows or injections: many APIs have built-in protection (bounds checks, parameter binding, escaping) that prevents the alleged issue regardless of inputs.
+
+**1.3**: Before concluding vulnerability, verify that no compiler, runtime, OS, or framework protection prevents exploitation. Mitigations like ASLR and stack canaries raise the bar but do not eliminate the vulnerability itself. Distinguish "prevents exploitation entirely" (Rust's safe type system, parameterized queries, framework auto-escaping) from "makes exploitation harder" (ASLR, a WAF).
+
+**1.4**: Check whether similar code patterns exist elsewhere and are handled safely. Review test coverage, code review history (`git log -p`), and design documentation for this area.
+
+### Phase 2: Exploitability Verification
+
+**2.1**: Prove the attacker controls the data reaching the vulnerability. **Key pitfall**: assuming external data reaches the operation without tracing the actual path. Internal storage set by trusted components is not attacker-controlled.
+
+**2.2**: Create explicit algebraic proofs for bounds-related issues. Use the template in [evidence-templates.md](evidence-templates.md). Verify: IF validation_check_passes THEN bounds_guarantee_holds. Mark N/A when the bug is not about bounds or arithmetic.
+
+**2.3**: For race conditions, prove concurrent access is actually possible (two requests, two workers, two processes). **Key pitfall**: assuming races in single-threaded initialization or in code already serialized by a lock, transaction or unique constraint. Mark N/A when no concurrency is involved.
+
+**2.4**: Assess the full attack surface: input control, validation bypass paths, timing dependencies, and state manipulation.
+
+### Phase 3: Impact Assessment
+
+**3.1**: Distinguish real security impact (code execution, privilege escalation, information disclosure, unauthorized data changes, money loss) from operational robustness issues.
+
+**3.2**: Distinguish primary security controls from defense in depth. Failure of a defense-in-depth measure is not a vulnerability if primary protections remain intact.
+
+### Phase 4: PoC Creation
+
+**Always create a pseudocode PoC.** Create executable and/or unit test PoCs when feasible and allowed:
+
+1. **Pseudocode with data flow diagram** showing the attack path (always).
+2. **Executable PoC** in the target language (if feasible). In review and test steps it runs only from a temp directory outside the repository, never against live services or production data, and is deleted afterwards.
+3. **Unit test PoC** exercising the vulnerable path with crafted inputs (if feasible). Same rule: never add it to the repository under review. In a code or bugfix step it may become the regression test.
+
+See [evidence-templates.md](evidence-templates.md) for templates.
+
+**Negative PoC (4.4)**: show the gap between normal operation and the exploit path: which preconditions must hold for the vulnerability to trigger, and why they do not hold under normal conditions.
+
+### Phase 5: Devil's Advocate Review
+
+Before the verdict, challenge the claim systematically. Assume you are biased toward finding bugs and rating them as critical, and work against that bias.
+
+**Challenges arguing AGAINST the vulnerability:**
+
+1. What non-vulnerability explanations exist for this code pattern?
+2. How would the original developers justify this implementation?
+3. What crucial system architecture context might be missing?
+4. Am I seeing a vulnerability because the pattern "looks dangerous" rather than because it actually is?
+5. Even if validation looks insufficient, does it actually prevent the claimed condition?
+6. Am I incorrectly assuming attacker control over trusted data?
+7. Have I rigorously proven the mathematical condition for vulnerability can occur?
+8. Beyond theoretical possibility, is this practically exploitable?
+9. Am I confusing defense-in-depth failure with a primary security vulnerability?
+10. What compiler, runtime, OS or framework protections might prevent exploitation?
+11. Am I hallucinating this vulnerability? LLMs are biased toward seeing bugs everywhere and rating every finding as critical. Is this a real, exploitable issue, or am I pattern-matching on scary-looking code?
+
+**Challenges arguing FOR the vulnerability (false-negative protection):**
+
+12. Am I dismissing a real vulnerability because the exploit seems complex or unlikely?
+13. Am I inventing mitigations or validation logic that I have not verified in the actual source code? Re-read the code after reaching a conclusion.
+
+See [evidence-templates.md](evidence-templates.md) for the documentation template.
+
+## Gate Review
+
+Apply the six gates from [gate-reviews.md](gate-reviews.md) to reach a verdict.
+
+Part of the `false-positive-check` skill, adapted from https://github.com/trailofbits/skills/tree/main/plugins/fp-check (commit 5c99c03fb8a9ea568432ecbcba5d86e9f4ac2bf0), CC BY-SA 4.0. Changed: task tracking and plugin agents replaced by an in-order checklist (optionally the `code-explorer` agent), read-only rules for proofs of concept, N/A rules for 2.2 and 2.3, web examples of environment protections and impact.

package/library/skills/false-positive-check/references/evidence-templates.md

@@ -0,0 +1,93 @@
+# Evidence Templates
+
+Use these templates when documenting verification evidence for each bug.
+
+## Data Flow Documentation
+
+```
+Bug #N Data Flow Analysis
+Source: [exact location] - Trust Level: [trusted/untrusted]
+Path: Source → Validation1[file:line] → Transform[file:line] → Vulnerability[file:line]
+Validation Points:
+  - Check1: [condition] at [file:line] - [passes/fails/bypassed]
+  - Check2: [condition] at [file:line] - [passes/fails/bypassed]
+```
+
+## Mathematical Bounds Proof
+
+```
+Bug #N Mathematical Analysis
+Claim: Operation X is vulnerable to [overflow/underflow/bounds violation]
+Given Constraints: [list all validation conditions]
+
+Algebraic Proof:
+1. [first constraint from validation]
+2. [constant or known value]
+3. [derived inequality]
+...
+N. Therefore: [vulnerability confirmed/debunked] (Q.E.D.)
+
+Conclusion: [vulnerability is/is not mathematically possible]
+```
+
+**Example:**
+
+```
+Given: validation ensures (input_size >= MIN_SIZE)
+Given: MIN_SIZE = 16, header_size = 8
+Prove: (input_size - header_size) cannot underflow
+
+1. input_size >= MIN_SIZE             (from validation)
+2. MIN_SIZE = 16                      (constant)
+3. header_size = 8                    (constant)
+4. input_size >= 16                   (substitution of 1,2)
+5. input_size - 8 >= 16 - 8          (subtract header_size from both sides)
+6. input_size - header_size >= 8     (simplification)
+7. Therefore: underflow impossible    (Q.E.D.)
+```
+
+## Attacker Control Analysis
+
+```
+Bug #N Attacker Control Analysis
+Input Vector: [how attacker provides input]
+Control Level: [full/partial/none]
+Constraints: [what limits exist on attacker input]
+Reachability: [can attacker-controlled data reach vulnerable operation?]
+```
+
+## PoC - Pseudocode with Data Flow Diagram
+
+```
+PoC for Bug #N: [Brief Description]
+
+Data Flow Diagram:
+
+[External Input] → [Validation Point] → [Processing] → [Vulnerable Operation]
+     |                    |                   |                    |
+  Attacker           (May be bypassed)    (Transforms data)   (Unsafe operation)
+  Controlled              |                   |                    |
+     |                    v                   v                    v
+  [Malicious Data] → [Insufficient Check] → [Processed Data] → [Impact]
+
+PSEUDOCODE:
+function vulnerable_operation(user_data):
+    validation_result = weak_validation(user_data)  // Explain why this fails
+    processed_data = transform_data(user_data)      // Show transformation
+    unsafe_operation(processed_data)               // Show vulnerability trigger
+```
+
+## Devil's Advocate Review
+
+```
+Bug #N Devil's Advocate Review
+Vulnerability Claim: [brief description]
+
+For each devil's advocate question (7 in standard verification, 13 in deep verification), document your answer:
+Questions against the vulnerability: [answers]
+Questions for the vulnerability (false-negative protection): [answers]
+
+Final Assessment: [Vulnerability confirmed/debunked with reasoning]
+```
+
+Part of the `false-positive-check` skill, adapted from https://github.com/trailofbits/skills/tree/main/plugins/fp-check (commit 5c99c03fb8a9ea568432ecbcba5d86e9f4ac2bf0), CC BY-SA 4.0. Changed: punctuation and small wording changes for read-only runs.

package/library/skills/false-positive-check/references/false-positive-patterns.md

@@ -0,0 +1,122 @@
+# False Positive Patterns: Lessons Learned
+
+Apply ALL items in this checklist to EACH potential bug during verification.
+
+Contents:
+
+- [Checklist](#checklist): 13 items to apply to every bug (trace validation, confirm data paths, bounds logic, TOCTOU, trust boundaries, real vs theoretical impact, defense-in-depth)
+- [Red Flags for False Positives](#red-flags-for-false-positives): recurring failure patterns (pattern-based, context-blind, math/bounds, API-contract)
+
+## Checklist
+
+### 1. Trace Full Validation Chain
+
+Don't analyze isolated code snippets. Trace backwards to find ALL validation that precedes potentially dangerous operations. Network packet size operations may look dangerous but often have bounds validation earlier in the function.
+
+### 1a. Map Complete Conditional Logic Flow
+
+Vulnerable-looking code may be unreachable due to conditional logic that creates mathematical guarantees. Example: array access `buffer[length-4]` appears unsafe when `length < 4`, but if the code is only reachable when `length > 12` due to earlier validation, the vulnerability is impossible.
+
+**Verify:**
+
+- What conditions must be met for execution to reach the alleged vulnerability?
+- Do those conditions mathematically prevent the vulnerability scenario?
+- Are there minimum size/length requirements that guarantee safe access?
+- Does the conditional flow create impossible-to-violate bounds?
+
+### 2. Identify Defensive Programming Patterns
+
+Distinguish between actual vulnerabilities and defensive assertions/validations. `ASSERT(size == expected_size)` followed by size-controlled operations is defensive, not vulnerable. Verify that checks actually prevent the alleged vulnerability.
+
+### 3. Confirm Exploitable Data Paths
+
+Only report vulnerabilities with CONFIRMED exploitable data flow paths. Don't assume network-controlled data reaches dangerous functions without tracing the actual path step by step.
+
+### 4. Understand Data Source Context
+
+Distinguish between data sources and their trust levels. API return values, compile-time constants, and network data have different risk profiles. Determine the actual source and whether it is attacker-controlled.
+
+### 5. Analyze Bounds Validation Logic
+
+Look for mathematical relationships between validation checks and subsequent operations. If `packet_size >= MIN_SIZE` is checked and `MIN_SIZE >= sizeof(header)`, then `packet_size - sizeof(header)` cannot underflow.
+
+### 6. Verify TOCTOU Claims
+
+Time-of-check-time-of-use issues require proof that the checked value can change between check and use. If a size is checked and immediately used in the same function with no external modification possible, there is no TOCTOU.
+
+### 7. Understand API Contract and Trust Boundaries
+
+Always understand API contracts before claiming buffer overflows. Some APIs have built-in bounds protection and cannot write beyond the buffer regardless of input parameters.
+
+### 8. Distinguish Internal Storage from External Input
+
+Internal storage systems (configuration stores, registries) are controlled by trusted components, not attackers. Values set during installation by trusted components are not attacker-controlled.
+
+### 9. Don't Confuse Pattern Recognition with Vulnerability Analysis
+
+Code patterns that "look vulnerable" may be safely implemented due to context and API contracts. Size parameters being modified doesn't mean buffer overflow if the API prevents writing beyond bounds.
+
+### 10. Verify Concurrent Access is Actually Possible
+
+Don't assume race conditions exist without proving concurrent access patterns. Single-threaded initialization contexts cannot have race conditions. Verify the threading model and synchronization mechanisms.
+
+### 11. Assess Real vs Theoretical Security Impact
+
+Focus on vulnerabilities with actual security impact. Storage failure for non-critical data is an operational issue, not a security vulnerability. Ask: would this lead to code execution, privilege escalation, or information disclosure?
+
+### 12. Understand Defense-in-Depth vs Primary Controls
+
+Failure of defense-in-depth mechanisms is not always a vulnerability if primary protections exist. Token cleanup failure is not critical if tokens are single-use by design at the server.
+
+### 13. Apply the Checklist Rigorously, Not Superficially
+
+Having a checklist doesn't prevent false positives if it isn't applied systematically. For EVERY potential vulnerability, work through ALL checklist items before concluding.
+
+---
+
+## Red Flags for False Positives
+
+### Pattern-Based False Positives
+
+- Reporting vulnerabilities in validation/bounds-checking code itself
+- Claiming TOCTOU without proving the value can change
+- Ignoring preceding validation logic
+- Assuming network data reaches operations without tracing the path
+- Confusing defensive programming (assertions/checks) with vulnerabilities
+- Analyzing vulnerable-looking patterns without tracing conditional logic that controls reachability
+- Reporting "vulnerabilities" in error handling or cleanup code
+- Flagging size calculations without understanding mathematical constraints
+- Identifying "dangerous" functions without checking if inputs are bounded
+- Claiming buffer overflows in fixed-size operations with compile-time bounds
+- Reporting race conditions in single-threaded or synchronized contexts
+
+### Context-Blind Analysis False Positives
+
+- Analyzing code snippets without understanding broader system design
+- Ignoring architectural guarantees (single-writer, trusted input sources)
+- Missing that "vulnerable" code is unreachable due to earlier validation
+- Confusing debug/development code paths with production paths
+- Reporting issues in code that only runs during trusted installation/setup
+- Flagging theoretical issues that cannot occur due to system architecture
+- Missing that alleged vulnerabilities are prevented by framework or language guarantees
+- Reporting issues in test-only or debug-only code paths as production vulnerabilities
+
+### Mathematical/Bounds Analysis False Positives
+
+- Reporting integer underflow without proving the mathematical condition can occur
+- Claiming buffer overflow when bounds are mathematically guaranteed by validation
+- Missing that conditional logic creates mathematical impossibility of vulnerable conditions
+- Reporting off-by-one errors without checking if loop bounds prevent the condition
+- Claiming memory corruption when allocation sizes are verified sufficient
+- Reporting arithmetic overflow without checking if input ranges prevent the condition
+
+### API Contract Misunderstanding False Positives
+
+- Claiming buffer overflows when APIs have built-in bounds checking
+- Reporting memory corruption for APIs that manage their own memory safely
+- Missing that return values are already validated by the API contract
+- Confusing API parameter modification with vulnerability when API prevents unsafe modification
+- Reporting issues explicitly handled by the API's safety guarantees
+- Missing that seemingly dangerous operations are safe due to API implementation details
+
+Part of the `false-positive-check` skill, adapted from https://github.com/trailofbits/skills/tree/main/plugins/fp-check (commit 5c99c03fb8a9ea568432ecbcba5d86e9f4ac2bf0), CC BY-SA 4.0. Changed: punctuation and small wording changes for read-only runs.

package/library/skills/false-positive-check/references/gate-reviews.md

@@ -0,0 +1,36 @@
+# Gate Reviews and Verdicts
+
+Before reporting ANY bug as a vulnerability, all six gate reviews must pass. Evaluate them at the end, after all phases are complete:
+
+| Gate | Criterion | Pass | Fail |
+|------|-----------|------|------|
+| **1. Process** | All phases completed with documented evidence | Evidence exists for every phase | Phases lack concrete evidence |
+| **2. Reachability** | Attacker can reach and control data at the vulnerability | Clear evidence of attacker-controlled path + PoC confirms | Cannot demonstrate attacker control or reachability |
+| **3. Real Impact** | Exploitation leads to code execution, privilege escalation, information disclosure, unauthorized changes to data, or loss of money | Direct impact with concrete scenarios | Only operational robustness issue |
+| **4. PoC Validation** | PoC (pseudocode, executable, or unit test) demonstrates the attack path | Shows attacker control, trigger, and impact | PoC fails to show attack path or impact |
+| **5. Math Bounds** | Mathematical analysis confirms vulnerable condition is possible (N/A, counted as pass, when the bug is not about bounds or arithmetic) | Algebraic proof shows condition is possible | Math proves validation prevents it |
+| **6. Environment** | No environmental protections entirely prevent exploitation | Protections do not eliminate vulnerability | Environmental protections block it entirely |
+
+For a suspected correctness bug rather than a vulnerability: gate 2 asks whether a realistic input or state reaches the faulty code, and gate 3 whether the outcome is a wrong result, lost or corrupted data, or a crash that users hit.
+
+## Verdict Format
+
+- **TRUE POSITIVE**: All gate reviews pass → `BUG #N TRUE POSITIVE - [brief vulnerability description]`
+- **FALSE POSITIVE**: Any gate review fails → `BUG #N FALSE POSITIVE - [brief reason for rejection]`
+- **INCONCLUSIVE**: A gate cannot be decided from the code available (the caller is in another repository, the configuration is not in the repo) → `BUG #N NEEDS VERIFICATION - [the exact open question]`. Reported as a note, never as blocking.
+
+If any phase fails verification, document the failure with evidence and continue all remaining phases. Issue the FALSE POSITIVE verdict only after all phases are complete.
+
+## Example Verdict
+
+```
+BUG #3 FALSE POSITIVE - Integer underflow in packet_handler.c:142
+  Gate 5 (Math Bounds) FAIL: validation at line 98 ensures packet_size >= 16,
+  making (packet_size - header_size) >= 8. Underflow is mathematically impossible.
+
+BUG #5 FALSE POSITIVE - IDOR in src/api/files.ts:19
+  Gate 2 (Reachability) FAIL: the route is mounted under accountRouter (src/app.ts:52),
+  whose middleware loads the file with the session's account id; other accounts' files return 404.
+```
+
+Part of the `false-positive-check` skill, adapted from https://github.com/trailofbits/skills/tree/main/plugins/fp-check (commit 5c99c03fb8a9ea568432ecbcba5d86e9f4ac2bf0), CC BY-SA 4.0. Changed: wider impact list for web applications, N/A rule for gate 5, correctness-bug reading of gates 2 and 3, inconclusive verdict, second example.

package/library/skills/false-positive-check/references/standard-verification.md

@@ -0,0 +1,80 @@
+# Standard Verification
+
+Linear single-pass checklist for straightforward bugs. No task tracking: work through each step sequentially and document findings inline.
+
+## Escalation Checkpoints
+
+Two points in this checklist may trigger escalation to [deep-verification.md](deep-verification.md):
+
+1. **After Step 1 (Data Flow)**: Escalate if 3+ trust boundaries, callbacks/async control flow, or ambiguous validation chain
+2. **After Step 5 (Devil's Advocate)**: Escalate if any question produces genuine uncertainty you cannot resolve
+
+When escalating, hand off all evidence gathered so far: deep verification will continue from where you left off.
+
+## Checklist
+
+### Step 1: Data Flow
+
+Trace data from source to the alleged vulnerability sink.
+
+- Map trust boundaries crossed (internal/trusted vs external/untrusted)
+- Identify all validation and sanitization between source and sink
+- Check API contracts: many APIs have built-in bounds protection that prevents the alleged issue
+- Check for environmental protections (compiler, runtime, OS, framework) that prevent exploitation entirely (not just raise the bar)
+- Apply class-specific checks from [bug-class-verification.md](bug-class-verification.md)
+
+**Key pitfall**: Analyzing the vulnerable code in isolation. Conditional logic upstream may make the vulnerability mathematically unreachable. Trace the full validation chain.
+
+**Escalation check**: If you found 3+ trust boundaries, callbacks or async control flow in the path, or an ambiguous validation chain: escalate to deep verification.
+
+### Step 2: Exploitability
+
+Prove the attacker can trigger the vulnerability.
+
+- **Attacker control**: Prove the attacker controls data reaching the vulnerable operation. Internal storage set by trusted components is not attacker-controlled.
+- **Bounds proof**: For integer/bounds issues, create an explicit algebraic proof using the template in [evidence-templates.md](evidence-templates.md). Verify: IF validation_check_passes THEN bounds_guarantee_holds.
+- **Race feasibility**: For race conditions, prove concurrent access is actually possible. Single-threaded initialization and synchronized contexts cannot have races.
+
+### Step 3: Impact
+
+Determine whether exploitation has real security consequences.
+
+- Distinguish real security impact (RCE, privesc, info disclosure) from operational robustness issues (crash recovery, cleanup failure)
+- Distinguish primary security controls from defense-in-depth. Failure of a defense-in-depth measure is not a vulnerability if primary protections remain intact.
+
+### Step 4: PoC Sketch
+
+Create a pseudocode PoC showing the attack path. Executable and unit test PoCs are optional for standard verification; in review and test steps they run only from a temp directory outside the repository and never against live services (see the ground rules in SKILL.md).
+
+```
+Data Flow: [Source] → [Validation?] → [Transform?] → [Vulnerable Op] → [Impact]
+Attacker controls: [what input, how]
+Trigger: [pseudocode showing the exploit path]
+```
+
+See [evidence-templates.md](evidence-templates.md) for the full PoC template.
+
+### Step 5: Devil's Advocate Spot-Check
+
+Answer these 7 questions. If any produces genuine uncertainty, escalate to deep verification.
+
+**Against the vulnerability:**
+
+1. Am I seeing a vulnerability because the pattern "looks dangerous" rather than because it actually is? (pattern-matching bias)
+2. Am I incorrectly assuming attacker control over trusted data? (trust boundary confusion)
+3. Have I rigorously proven the mathematical condition for vulnerability can occur? (proof rigor)
+4. Am I confusing defense-in-depth failure with a primary security vulnerability? (defense-in-depth confusion)
+5. Am I hallucinating this vulnerability? LLMs are biased toward seeing bugs everywhere: is this actually real or am I pattern-matching on scary-looking code? (LLM self-check)
+
+**For the vulnerability (always ask: false-negative protection):**
+
+6. Am I dismissing a real vulnerability because the exploit seems complex or unlikely?
+7. Am I inventing mitigations or validation logic that I haven't verified in the actual source code? Re-read the code after reaching a conclusion.
+
+**Escalation check**: If any question above produces genuine uncertainty you cannot resolve with the evidence at hand: escalate to deep verification.
+
+### Step 6: Gate Review
+
+Apply all six gates from [gate-reviews.md](gate-reviews.md) and all 13 items from [false-positive-patterns.md](false-positive-patterns.md) to reach a verdict.
+
+Part of the `false-positive-check` skill, adapted from https://github.com/trailofbits/skills/tree/main/plugins/fp-check (commit 5c99c03fb8a9ea568432ecbcba5d86e9f4ac2bf0), CC BY-SA 4.0. Changed: read-only rule for proofs of concept, punctuation.

package/library/skills/focused-implementation/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: focused-implementation
+description: Use when implementing a feature, change or fix in the code step, especially one that touches several files: turn the task into checkable goals, build it in small working slices, keep every changed line tied to the task, and record assumptions and side findings for the report instead of asking.
+---
+
+# Focused implementation
+
+The reviewer should be able to read your diff and see the task in every line. Nobody answers questions during the run, so you decide, write the decision down, and keep going.
+
+Start with `project-orientation` if you have not done it in this run. When the spec has several changes, write the plan first with `implementation-plan`.
+
+## 1. Turn the task into goals you can check
+
+Before writing code, write a short list:
+
+```
+Goal: invoices show the VAT amount per line
+Checks:
+- [ ] unit test: 3 lines at 20% VAT give per-line VAT 2.00, 4.00, 0.50
+- [ ] invoice page renders a VAT column (component test or screenshot)
+- [ ] existing invoice tests still pass
+Assumptions:
+- Rounding per line, half up, as in src/money/round.ts (spec does not say)
+```
+
+- Take the acceptance criteria from the spec as they are. Each one becomes at least one check.
+- A vague goal ("make it work", "improve") becomes a concrete check you can run.
+- Where the task or spec is ambiguous, pick the reading that best matches the spec, the existing code and the smallest change. Write it under Assumptions. Do not stop to ask; `task-interview` says which open points deserve a question in the report.
+- If the task as written is impossible or contradicts the code (an API that does not exist, a field that is not stored), do the closest useful thing that stays inside the task, and explain the gap in the report.
+
+## 2. Choose the simplest design that meets the goals
+
+- Prefer the plain, obvious solution: a function call over an event bus, two similar components over a configurable framework for two cases. Three similar lines beat a premature abstraction.
+- No speculative features, options, flags or extension points that the task does not need.
+- Reuse what the project already has (helpers, components, error types, query builders) before writing new ones.
+- For a change that spans many modules or needs a real design decision, ask the `code-architect` agent for one concrete blueprint, then follow it unless you find a reason not to (and say why).
+
+## 3. Build in thin slices
+
+Work in slices that each leave the project working:
+
+1. Implement the smallest complete piece (vertical: from storage to API to UI for one case, rather than all of the storage first).
+2. Test it: write the test first where the project has tests (`test-driven-development`), then run the tests near the change.
+3. Check it builds and type-checks.
+4. Move to the next slice.
+
+Rules:
+- Do not write more than roughly 100 lines without running something.
+- Put the riskiest or least certain piece first, so a dead end shows up early.
+- Never leave the build broken between slices.
+- Commit a slice when it is green if that makes the history clearer (`clean-commits`); one commit at the end is also fine.
+- New behaviour defaults to the safe, conservative option (off, opt-in, read-only) unless the task says otherwise.
+
+## 4. Keep changes surgical
+
+Every changed line should trace back to the task.
+
+- Do not reformat, rename, reorder imports or "modernise" code you are not otherwise changing.
+- Do not delete comments, code or tests you do not fully understand.
+- Match the surrounding style even if you would write it differently.
+- Clean up what your own change made unused (imports, helpers, variables). Leave older dead code alone.
+- When you notice something wrong outside the task, do not fix it. Add it to a "Noticed, not changed" list for the report:
+
+```
+Noticed, not changed:
+- src/utils/format.ts: unused import of `dayjs` (unrelated)
+- Login form shows the raw server error text (separate task)
+```
+
+Exception: if the task cannot be done correctly without touching it (the bug you are fixing lives there), change it and say why.
+
+## 5. Flag these in the report
+
+Do them only when the task needs them, choose the smaller option, and list them in the report so the reviewer looks closely:
+
+- New dependencies, or upgrades of existing ones.
+- Database schema changes or migrations (follow `safe-database-changes`).
+- Changes to authentication, authorisation, sessions, CORS, uploads, rate limits, roles or permissions.
+- New external services or new kinds of stored sensitive data.
+- Changes to a public API, a shared contract, CI config or build config.
+- Deleting files, features or tests.
+- Changes in a repository that the task did not obviously involve.
+
+Never: commit secrets, edit vendored or generated files by hand (regenerate them the way the project does), weaken or delete a failing test to get green, or disable lint rules to silence your own code.
+
+## 6. Finish
+
+1. Tidy your own diff: remove debug output, leftover TODOs you created, commented-out code. For a large change, the `code-simplifier` agent can do a behaviour-preserving pass over the changed files.
+2. Run `verification-before-completion`.
+3. Commit with `clean-commits`.
+4. Write the report: what changed, how it was checked (commands and results), assumptions, flagged items, noticed-not-changed list, anything left open.
+
+## Common mistakes
+
+| Thought | What to do instead |
+|---|---|
+| "While I'm here I'll clean this up" | Note it under "Noticed, not changed". |
+| "I'll test it all at the end" | Test each slice; a bug in slice 1 makes slices 2 to 5 wrong. |
+| "Let me make it configurable, just in case" | Build what the task needs; add options when a second case exists. |
+| "The spec is unclear, I'll wait" | Pick the most reasonable reading, write it under Assumptions, continue. |
+| "This refactor is small enough to include" | Keep refactors out of feature changes unless the task needs them. |
+| "Lint fails on my line, I'll add an ignore comment" | Fix the code; ignore comments only where the project already uses them for the same case, with a reason. |
+
+Sources: addyosmani/agent-skills (MIT, commit aeac41d) incremental-implementation, plus ideas restated from the Karpathy coding guidelines. Changed: rewritten for unattended runs.

package/library/skills/implementation-plan/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: implementation-plan
+description: Use at the start of a code step when the spec or task touches more than one file or more than one repository: turn it into an ordered plan of small tasks with exact files, the interfaces passed between them, the checks that prove each one, and a review focus of the inputs no test covers yet.
+---
+
+# Implementation plan
+
+A plan is the set of decisions an implementer cannot make alone: which files, which names and signatures, which values from the spec, which tests prove each step. Write those down, nothing more. A plan longer than the code it describes has written the code instead.
+
+Start with `project-orientation` if you have not done it in this run. Keep the plan in your working notes; it does not go into the repository unless the project asks for plans there.
+
+## 1. Read the spec as the contract
+
+- The acceptance criteria (AC-1, AC-2 and so on) are the finish line. Each one must end up proven by a test or a check.
+- Out of scope is a hard limit: nothing from it goes into the plan.
+- Decisions, assumptions and the code map are settled: follow them. If the code contradicts one, note it for the report and pick the reading closest to the spec.
+- Values the spec pins (texts, limits, names, status codes) are copied verbatim into a "Constraints" list at the top of the plan.
+
+## 2. Map the files
+
+List every file you will create or change, with one line on its responsibility. Files that change together live together; follow the project's existing layout.
+
+## 3. Order the tasks
+
+Each task is the smallest unit with its own test cycle that a reviewer could accept or reject on its own:
+
+```
+Task 2: CSV export endpoint
+Files: create server/api/boards/[id]/export.get.ts; test test/boardExport.test.ts
+Consumes: canSeeBoard(userId, boardId) from server/utils/boardAccess.ts
+Produces: GET /api/boards/:id/export -> text/csv, header "Title,Status,Owner"
+Proves: AC-1, AC-2
+Steps:
+  1. Test: 3 tasks give 4 lines; no access gives 404 (fails first)
+  2. Implement exportCsv(boardId: number): string and the route
+  3. Run: pnpm test test/boardExport.test.ts -> 2 passed
+```
+
+- Order by dependency: a task uses only what earlier tasks or the existing code provide. Put the riskiest or least certain task as early as its dependencies allow.
+- **Interfaces:** write Consumes and Produces with exact names, parameters, return types and data shapes. This is how the next task learns the names; check that every name used later is produced earlier.
+- **Steps:** each step is one action with a checkable result, and lets you write exactly one reasonable thing. Lines that decide nothing ("handle edge cases", "add validation", "write tests") are gaps: replace them with the case, the rule or the test name.
+- **Tests at the highest seam** that covers the behaviour: an endpoint, a page or a public function, not private helpers. Follow `test-driven-development`.
+
+## 4. Verification
+
+Split it in two:
+
+- **Automated:** the exact commands (tests, type check, lint, build) and what passing looks like. Take them from the spec's test plan and from `project-orientation`.
+- **Manual:** what a person does and sees, naming the page or command. For interface work, the screens to render with `ui-testing` or `design-review`.
+
+Map every acceptance criterion to the task and the check that proves it. A criterion without a check is a gap: add the test.
+
+## 5. Review focus
+
+Write up to five input classes or failure modes the spec implies but no planned test exercises, most likely to bite a person first: an empty list, a very long name, a second click, an expired session, a slow network. The spec's silence on an input is not permission for that input to break the program. For each line, add the test to the task that owns the code, or say in the report why it is left.
+
+## 6. Self-check before coding
+
+1. **Coverage:** every criterion has a task and a check; every task proves a criterion.
+2. **Names:** names and signatures match between Produces and Consumes.
+3. **Scope:** nothing from out of scope, nothing the spec did not ask for.
+4. **Proportion:** the plan is shorter than the code it describes.
+
+Then build it with `focused-implementation`, one task at a time, and finish with `verification-before-completion`. Put the plan's Review Focus and any deviations from the spec in the report.
+
+Sources: adapted from obra/superpowers writing-plans (MIT, commit b739a8a), the plan template and ready-for-development rules of bmad-code-org/BMAD-METHOD (MIT, commit 61e01f8), humanlayer/humanlayer create_plan (Apache-2.0, commit 99abe67) and mattpocock/skills to-spec testing seams (MIT, commit 5beb35b). Changed: condensed into one process for unattended code steps, the plan stays in working notes, execution choices removed.