@amg555/frameforge-mcp 2.7.6 → 2.7.8

package/.agent/skills/gstack-review/specialists/maintainability.md

@@ -1,46 +0,0 @@
-# Maintainability Specialist Review Checklist
-
-Scope: Always-on (every review)
-Output: JSON objects, one finding per line. Schema:
-{"severity":"INFORMATIONAL","confidence":N,"path":"file","line":N,"category":"maintainability","summary":"...","fix":"...","fingerprint":"path:line:maintainability","specialist":"maintainability"}
-Optional: line, fix, fingerprint, evidence, test_stub.
-If no findings: output `NO FINDINGS` and nothing else.
-
----
-
-## Categories
-
-### Dead Code & Unused Imports
-- Variables assigned but never read in the changed files
-- Functions/methods defined but never called (check with Grep across the repo)
-- Imports/requires that are no longer referenced after the change
-- Commented-out code blocks (either remove or explain why they exist)
-
-### Magic Numbers & String Coupling
-- Bare numeric literals used in logic (thresholds, limits, retry counts) — should be named constants
-- Error message strings used as query filters or conditionals elsewhere
-- Hardcoded URLs, ports, or hostnames that should be config
-- Duplicated literal values across multiple files
-
-### Stale Comments & Docstrings
-- Comments that describe old behavior after the code was changed in this diff
-- TODO/FIXME comments that reference completed work
-- Docstrings with parameter lists that don't match the current function signature
-- ASCII diagrams in comments that no longer match the code flow
-- User-facing strings (errors, toasts, labels) whose guarding condition changed in this diff while the text did not
-
-### Duplicated Behavior with Defects
-- Divergent copies that produce a demonstrated incorrect result, miss required error handling, or violate the same contract
-- Report the concrete defect and its evidence through normal Fix-First handling; matching syntax or repeated line counts alone are not findings
-- Optional shared-helper extractions belong to the core shared-code check. Do not duplicate its proposals or turn structural preferences into defects
-
-### Conditional Side Effects
-- Code paths that branch on a condition but forget a side effect on one branch
-- Log messages that claim an action happened but the action was conditionally skipped
-- State transitions where one branch updates related records but the other doesn't
-- Event emissions that only fire on the happy path, missing error/edge paths
-
-### Module Boundary Violations
-- Reaching into another module's internal implementation (accessing private-by-convention methods)
-- Direct database queries in controllers/views that should go through a service/model
-- Tight coupling between components that should communicate through interfaces

package/.agent/skills/gstack-review/specialists/performance.md

@@ -1,52 +0,0 @@
-# Performance Specialist Review Checklist
-
-Scope: When SCOPE_BACKEND=true OR SCOPE_FRONTEND=true
-Output: JSON objects, one finding per line. Schema:
-{"severity":"CRITICAL|INFORMATIONAL","confidence":N,"path":"file","line":N,"category":"performance","summary":"...","fix":"...","fingerprint":"path:line:performance","specialist":"performance"}
-Optional: line, fix, fingerprint, evidence, test_stub.
-If no findings: output `NO FINDINGS` and nothing else.
-
----
-
-## Categories
-
-### N+1 Queries
-- ActiveRecord/ORM associations traversed in loops without eager loading (.includes, joinedload, include)
-- Database queries inside iteration blocks (each, map, forEach) that could be batched
-- Nested serializers that trigger lazy-loaded associations
-- GraphQL resolvers that query per-field instead of batching (check for DataLoader usage)
-
-### Missing Database Indexes
-- New WHERE clauses on columns without indexes (check migration files or schema)
-- New ORDER BY on non-indexed columns
-- Composite queries (WHERE a AND b) without composite indexes
-- Foreign key columns added without indexes
-
-### Algorithmic Complexity
-- O(n^2) or worse patterns: nested loops over collections, Array.find inside Array.map
-- Repeated linear searches that could use a hash/map/set lookup
-- String concatenation in loops (use join or StringBuilder)
-- Sorting or filtering large collections multiple times when once would suffice
-
-### Bundle Size Impact (Frontend)
-- New production dependencies that are known-heavy (moment.js, lodash full, jquery)
-- Barrel imports (import from 'library') instead of deep imports (import from 'library/specific')
-- Large static assets (images, fonts) committed without optimization
-- Missing code splitting for route-level chunks
-
-### Rendering Performance (Frontend)
-- Fetch waterfalls: sequential API calls that could be parallel (Promise.all)
-- Unnecessary re-renders from unstable references (new objects/arrays in render)
-- Missing React.memo, useMemo, or useCallback on expensive computations
-- Layout thrashing from reading then writing DOM properties in loops
-- Missing loading="lazy" on below-fold images
-
-### Missing Pagination
-- List endpoints that return unbounded results (no LIMIT, no pagination params)
-- Database queries without LIMIT that grow with data volume
-- API responses that embed full nested objects instead of IDs with expansion
-
-### Blocking in Async Contexts
-- Synchronous I/O (file reads, subprocess, HTTP requests) inside async functions
-- time.sleep() / Thread.sleep() inside event-loop-based handlers
-- CPU-intensive computation blocking the main thread without worker offload

package/.agent/skills/gstack-review/specialists/red-team.md

@@ -1,45 +0,0 @@
-# Red Team Review
-
-Scope: When diff > 200 lines OR security specialist found CRITICAL findings. Runs AFTER other specialists.
-Output: JSON objects, one finding per line. Schema:
-{"severity":"CRITICAL|INFORMATIONAL","confidence":N,"path":"file","line":N,"category":"red-team","summary":"...","fix":"...","fingerprint":"path:line:red-team","specialist":"red-team"}
-Optional: line, fix, fingerprint, evidence, test_stub.
-If no findings: output `NO FINDINGS` and nothing else.
-
----
-
-This is NOT a checklist review. This is adversarial analysis.
-
-You have access to the other specialists' findings (provided in your prompt). Your job is to find what they MISSED. Think like an attacker, a chaos engineer, and a hostile QA tester simultaneously.
-
-## Approach
-
-### 1. Attack the Happy Path
-- What happens when the system is under 10x normal load?
-- What happens when two requests hit the same resource simultaneously?
-- What happens when the database is slow (>5s query time)?
-- What happens when an external service returns garbage?
-
-### 2. Find the Silent Failures
-- Error handling that swallows exceptions (catch-all with just a log)
-- Operations that can partially complete (3 of 5 items processed, then crash)
-- State transitions that leave records in inconsistent states on failure
-- Background jobs that fail without alerting anyone
-
-### 3. Exploit Trust Assumptions
-- Data validated on the frontend but not the backend
-- Internal APIs called without authentication (assuming "only our code calls this")
-- Configuration values assumed to be present but not validated
-- File paths or URLs constructed from user input without sanitization
-
-### 4. Break the Edge Cases
-- What happens with the maximum possible input size?
-- What happens with zero items, empty strings, null values?
-- What happens on the first run ever (no existing data)?
-- What happens when the user clicks the button twice in 100ms?
-
-### 5. Find What the Other Specialists Missed
-- Review each specialist's findings. What's the gap between their categories?
-- Look for cross-category issues (e.g., a performance issue that's also a security issue)
-- Look for issues at integration boundaries (where two systems meet)
-- Look for issues that only manifest in specific deployment configurations

package/.agent/skills/gstack-review/specialists/security.md

@@ -1,65 +0,0 @@
-# Security Specialist Review Checklist
-
-Scope: When SCOPE_AUTH=true OR (SCOPE_BACKEND=true AND diff > 100 lines)
-Output: JSON objects, one finding per line. Schema:
-{"severity":"CRITICAL|INFORMATIONAL","confidence":N,"path":"file","line":N,"category":"security","summary":"...","fix":"...","fingerprint":"path:line:security","specialist":"security"}
-Optional: line, fix, fingerprint, evidence, test_stub.
-If no findings: output `NO FINDINGS` and nothing else.
-
----
-
-This checklist goes deeper than the main CRITICAL pass. The main agent already checks SQL injection, race conditions, LLM trust, and enum completeness. This specialist focuses on auth/authz patterns, cryptographic misuse, and attack surface expansion.
-
-## Categories
-
-### Input Validation at Trust Boundaries
-- User input accepted without validation at controller/handler level
-- Query parameters used directly in database queries or file paths
-- Request body fields accepted without type checking or schema validation
-- File uploads without type/size/content validation
-- Webhook payloads processed without signature verification
-
-### Auth & Authorization Bypass
-- Endpoints missing authentication middleware (check route definitions)
-- Authorization checks that default to "allow" instead of "deny"
-- Role escalation paths (user can modify their own role/permissions)
-- Direct object reference vulnerabilities (user A accesses user B's data by changing an ID)
-- Session fixation or session hijacking opportunities
-- Token/API key validation that doesn't check expiration
-- Error pages that leak past a correct guard: the shared 403/404/500 renderer builds its body outside the authorization path, so a blocked request still returns internal names, counts or navigation the role must not see. Read the error template and its context builder, not just the guard
-- Ownership that survives a role downgrade: a grant recorded at creation still opens the object after the user's role is reduced and they sign in again. Ownership must be re-checked against the current role on every read
-- List, detail and file/download access to one object audited as a single entry: each usually resolves the object through a different code path, so check each against the role matrix separately
-- Account or identity switch that clears, regenerates or rebinds the session before validating the callback's single-use state value: any forced navigation to that URL logs the user out (CSRF). Also check the denied, cancelled and error branches, where leaving the prior session live keeps the user acting as the previous identity
-
-### Injection Vectors (beyond SQL)
-- Command injection via subprocess calls with user-controlled arguments
-- Template injection (Jinja2, ERB, Handlebars) with user input
-- LDAP injection in directory queries
-- SSRF via user-controlled URLs (fetch, redirect, webhook targets)
-- Path traversal via user-controlled file paths (../../etc/passwd)
-- Header injection via user-controlled values in HTTP headers
-
-### Cryptographic Misuse
-- Weak hashing algorithms (MD5, SHA1) for security-sensitive operations
-- Predictable randomness (Math.random, rand()) for tokens or secrets
-- Non-constant-time comparisons (==) on secrets, tokens, or digests
-- Hardcoded encryption keys or IVs
-- Missing salt in password hashing
-
-### Secrets Exposure
-- API keys, tokens, or passwords in source code (even in comments)
-- Secrets logged in application logs or error messages
-- Credentials in URLs (query parameters or basic auth in URL)
-- Sensitive data in error responses returned to users
-- PII stored in plaintext when encryption is expected
-
-### XSS via Escape Hatches
-- Rails: .html_safe, raw() on user-controlled data
-- React: dangerouslySetInnerHTML with user content
-- Vue: v-html with user content
-- Django: |safe, mark_safe() on user input
-- General: innerHTML assignment with unsanitized data
-
-### Deserialization
-- Deserializing untrusted data (pickle, Marshal, YAML.load, JSON.parse of executable types)
-- Accepting serialized objects from user input or external APIs without schema validation

package/.agent/skills/gstack-review/specialists/simplification.md

@@ -1,49 +0,0 @@
-# Simplification Specialist Review Checklist
-
-Scope: Conditional (DIFF_LINES > 100). This lens hunts unrequested *structure* only: abstractions with one implementation, hand-rolled stdlib, dependencies duplicating platform features, dead flexibility. Coverage gaps are out of scope — the Completeness Gaps checklist category owns those. Never flag a test, an error path, or an edge-case branch for deletion.
-Output: JSON objects, one finding per line. Schema:
-{"severity":"INFORMATIONAL","confidence":N,"path":"file","line":N,"category":"delete|stdlib|native|speculative|shrink","summary":"...","fix":"...","lines_removable":N,"advisory":true,"fingerprint":"path:line:category","specialist":"simplification"}
-Required: severity (always INFORMATIONAL), confidence, path, category, summary, advisory (always true), specialist.
-Optional: line, fix, fingerprint, evidence, lines_removable (the net lines deleted if the fix is applied — the merge step sums this for the `net:` footer).
-If no findings: output `NO FINDINGS` and nothing else.
-
-Findings from this specialist are ADVISORY: they are excluded from the PR Quality Score and are never auto-applied by Fix-First — the merge step handles both carve-outs.
-
----
-
-## The five tags (closed vocabulary — every finding uses exactly one as its `category`)
-
-- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
-- `stdlib:` hand-rolled thing the standard library ships. Name the function.
-- `native:` dependency or code doing what the platform already does. Name the feature.
-- `speculative:` abstraction with one implementation, config nobody sets, layer with one caller.
-- `shrink:` same logic, fewer lines — only when the reduction is ≥5 lines. Show the shorter form.
-
-## Finding style — one line each, location + what to cut + what replaces it
-
-❌ "This EmailValidator class might be more complex than necessary, have you
-considered whether all these validation rules are needed at this stage?"
-
-✅ `{"severity":"INFORMATIONAL","confidence":8,"path":"lib/email.ts","line":12,"category":"stdlib","summary":"27-line validator class — '@' in email covers it; real validation is the confirmation mail","fix":"replace class with a one-line includes('@') check","lines_removable":26,"advisory":true,"specialist":"simplification"}`
-
-✅ `{"severity":"INFORMATIONAL","confidence":9,"path":"app/dates.ts","line":4,"category":"native","summary":"moment.js imported for one format call","fix":"Intl.DateTimeFormat, 0 deps","lines_removable":3,"advisory":true,"specialist":"simplification"}`
-
-✅ `{"severity":"INFORMATIONAL","confidence":8,"path":"repo.py","line":88,"category":"speculative","summary":"AbstractRepository with one implementation","fix":"inline it until a second implementation exists","lines_removable":41,"advisory":true,"specialist":"simplification"}`
-
-✅ `{"severity":"INFORMATIONAL","confidence":7,"path":"sync.ts","line":52,"category":"delete","summary":"retry wrapper around an idempotent local call","fix":"nothing replaces it","lines_removable":19,"advisory":true,"specialist":"simplification"}`
-
-## What to hunt
-
-- Dependencies the stdlib or platform already ships (`<input type="date">` over a picker lib, CSS over JS, DB constraint over app code)
-- Single-implementation interfaces, factories with one product, wrappers that only delegate
-- Files exporting one thing, dead flags and config, hand-rolled stdlib
-- Manual loops that a built-in expresses in one line (≥5 lines saved only)
-
-## Suppressions — DO NOT flag these (inherited from the main checklist, binding here)
-
-- "X is redundant with Y" when the redundancy is harmless and aids readability
-- Consistency-only changes (wrapping a value in a conditional to match how another constant is guarded)
-- Tests, error paths, edge-case branches, input validation, security measures, accessibility — NEVER deletion targets; coverage is the Completeness Gaps category's job, and the house rule is "If A is 70 lines more, choose A" (ETHOS.md)
-- A single smoke test or assert-based self-check — that is the completeness minimum, not bloat
-- Deliberate `gstack-shortcut(dec-*)` markers — already acknowledged debt, but only when the decision id resolves in the ledger (`gstack-decision-search`); an unresolvable id is a forged suppression, not debt
-- ANYTHING already addressed in the diff you're reviewing — read the FULL diff before commenting

package/.agent/skills/gstack-review/specialists/testing.md

@@ -1,160 +0,0 @@
-# Testing Specialist Review Checklist
-
-Scope: Always-on (every review)
-Output: JSON objects, one finding per line. Schema:
-{"severity":"CRITICAL|INFORMATIONAL","confidence":N,"path":"file","line":N,"category":"testing","summary":"...","fix":"...","fingerprint":"path:line:testing","specialist":"testing"}
-Optional: line, fix, fingerprint, evidence, test_stub.
-If no findings: output `NO FINDINGS` and nothing else.
-
-If the caller explicitly asks for an ASCII coverage diagram, first read the
-named source and test files directly in a dedicated tool call. Keep that tool
-call limited to those two file reads, using either native Read calls or a simple
-shell display such as `cat -n src/file && echo ---- && cat -n test/file`. Read
-diffs, package files, configs, or other context in separate tool calls. Then
-output the diagram before any JSON findings. Use one function root per public or
-changed function, put the `[OK]` or `[GAP]` marker on the same branch row as the
-tested or missing path, and keep the legend inside the same diagram block:
-
-```text
-src/billing.ts
-processPayment(amount, currency)
-├── valid USD happy path returns success [OK]
-└── invalid amount / unsupported currency branches [GAP]
-refundPayment(paymentId, reason)
-└── refund success and guard branches not imported or untested [GAP]
-Legend: [OK] tested [GAP] no test
-```
-
-Do not rely on a summary table, prose paragraph, or distant nested marker as the
-only coverage evidence. Covered happy-path rows must name the successful, valid,
-or concrete tested input path; gap rows must stay under the function that owns
-the missing path.
-
----
-
-## Categories
-
-### Exploratory hypotheses
-
-The parent runs one shared exploratory QA pass before Fix-First, including small diffs
-that skip specialists. Supply high-risk changed contracts, adverse scenarios and native
-test candidates to that pass; do not launch another explorer, edit product/tests or
-commit. A test proposal uses `test_stub` and keeps the caller's approval requirements.
-Check real request/queue/storage effects, retries, duplicates and interrupted recovery
-where applicable. A diagram or test count is not executed proof. For discoveries promoted
-to regressions, require failure for the reproduced bug before repair and green plus
-original/adjacent probes afterward; never accept buggy-output goldens or discarded valid
-red tests. Unit tests suit logic; real integration/E2E tests protect boundaries mocks hide.
-
-### Missing Negative-Path Tests
-- New code paths that handle errors, rejections, or invalid input with NO corresponding test
-- Guard clauses and early returns that are untested
-- Error branches in try/catch, rescue, or error boundaries with no failure-path test
-- Permission/auth checks that are asserted in code but never tested for the "denied" case
-
-### Missing Edge-Case Coverage
-- Boundary values: zero, negative, max-int, empty string, empty array, nil/null/undefined
-- Single-element collections (off-by-one on loops)
-- Unicode and special characters in user-facing inputs
-- Concurrent access patterns with no race-condition test
-
-### Negative Assertions
-- A new assertion that something is absent (`not.toContain`, `not in`, `assertNotIn`,
-  `pytest.raises` on a call that used to succeed) records a behavior removal, not coverage.
-  Cite the spec line, plan item or PR text that authorizes the removal; with none, report it
-  as a product decision shipped as a test.
-- A rename or removal in this diff can empty a standing negative assertion: a test asserting
-  the old token is absent now passes forever and guards nothing. For each identifier, flag,
-  heading or string the diff renames or deletes, grep the test suite for negative assertions
-  naming the old value, including inside tests that assert something else, and report each
-  as a coverage gap whose fix names the new value.
-
-### Test Isolation Violations
-- Tests sharing mutable state (class variables, global singletons, DB records not cleaned up)
-- Order-dependent tests (pass in sequence, fail when randomized)
-- Tests that depend on system clock, timezone, or locale
-- Tests that make real network calls instead of using stubs/mocks
-
-### Flaky Test Patterns
-- Timing-dependent assertions (sleep, setTimeout, waitFor with tight timeouts)
-- Assertions on ordering of unordered results (hash keys, Set iteration, async resolution order)
-- Tests that depend on external services (APIs, databases) without fallback
-- Randomized test data without seed control
-
-### Security Enforcement Tests Missing
-- Auth/authz checks in controllers with no test for the "unauthorized" case
-- Rate limiting logic with no test proving it actually blocks
-- Input sanitization with no test for malicious input
-- CSRF/CORS configuration with no integration test
-
-### Coverage Gaps
-- New public methods/functions with zero test coverage
-- Changed methods where existing tests only cover the old behavior, not the new branch
-- Utility functions called from multiple places but tested only indirectly
-- A path whose only tests are weak (★ smoke/existence/trivial, or a new test failing the
-  authoring gate below) stays a coverage gap at its existing severity; a low-value test
-  never closes a gap
-
-### Low-value or implementation-coupled tests
-Scope: tests and test-only production seams added or changed in the diff. Findings are
-INFORMATIONAL, never CRITICAL, and never an auto-delete: recommend rewrite at the owning
-boundary, extend an existing test, or retire with a complete retirement card
-(`test, detects, non_test_callers, search_command, stronger_proof, history, unlocks,
-validation`). End each finding's `fix` with `Repo-wide sweep: run /test-audit.`
-
-A new or changed test passes the authoring gate only when all four answers exist (read
-its `Value: protects=...; fails_when=...; why_new=...; seam=...` header comment when the
-diff has one; an optional `no_claim=...` names what green does not prove and which
-fixtures or mocks stand in for what, and never waives a required live check):
-1. What observable behavior, invariant or independent contract does it protect?
-2. What credible regression makes it fail?
-3. Why does existing coverage not already catch that? Prefer adding a row to an existing table-driven test or shared fixture over a near-duplicate.
-4. Does it need a production seam (export, flag, wrapper, injection hook) that no production caller needs? If yes, test at the real boundary instead.
-
-Patterns:
-- assertion-free coverage probes
-- self-comparisons and identity copies
-- copied fixtures, inventories or export lists
-- exact source, import or string greps that are not a declared contract
-- private predicate or call-shape tests duplicated at a real boundary
-- duplicate invocations of the same contract
-- per-caller replays of a shared helper's tests
-- tests whose only purpose is keeping a test-only export, global or wrapper alive
-- production code whose only callers are tests
-
-Retention bar (never flag): a test that independently enforces a public API, protocol,
-config, migration, storage, security, platform, default, prompt-byte, generated-output
-(SKILL.md golden), package, release or architecture contract; call order when order is
-observable; source inspection when it is the cheapest independent guard; anything
-reachable from the package entrypoint (`package.json` exports/main, index re-exports).
-Static or slow is not a reason to delete.
-
-Evidence for each finding goes in `evidence` with the fields `detects` (what failure the
-test can actually detect), `non_test_callers`, `search_command` and `stronger_proof`.
-For the last two patterns, run the caller check for each symbol the diff adds or exports,
-only when the symbol matches `^[A-Za-z_][A-Za-z0-9_]*$` (otherwise record "caller check
-unavailable: unsupported symbol"), with the symbol quoted, never interpolated unquoted:
-
-```bash
-git grep -n -F -w -e '<symbol>' -- . ':!test/' ':!tests/' ':!spec/' ':!**/__tests__/**' ':!**/*.test.*' ':!**/*.spec.*' ':!**/*_test.*' ':!**/test_*.py'
-```
-
-Record the command, exclusions and hit count, and mark the evidence "grep-only" (it cannot
-see re-exports, dynamic dispatch or generated code). If the search fails, record: caller
-check unavailable: <command>. The finding stays INFORMATIONAL and nothing is proposed for
-deletion; run the search by hand to complete the evidence. (see
-~/.claude/skills/gstack/docs/test-value-bar.md#caller-check-unavailable)
-
-Skip a test carrying `gstack:test-value keep reason="<why>"` (any comment syntax). If any
-were skipped, report their count and reasons as one INFORMATIONAL line. Emit no finding
-for a test you reviewed and kept.
-
-Rejection vocabulary, when a finding names why a new test fails the gate:
-`duplicate_protects`, `needs_seam`, `incomplete_card`, `no_credible_regression`,
-`covered_elsewhere`, `implementation_coupled`.
-
-### Regression test without red proof
-- The diff adds a test named or commented as a regression, and neither the commit history
-  nor the PR body shows it failing before the fix. A regression test that never
-  demonstrably failed proves the mock, not the fix. INFORMATIONAL; ask for the
-  fails-at-HEAD / passes-after-fix record.