@loomfsm/bundle-code 0.1.0

package/knowledge/references/test-strategy.md

@@ -0,0 +1,175 @@
+---
+tags: [testing, strategy, coverage, mocks, flake, integration, tdd]
+stack_signals: []
+summary: |
+  Cross-stack test strategy — pin behavior not implementation; coverage % is
+  vanity; flaky tests are worse than no tests. Decisions for what to test,
+  how to mock, and when integration > unit.
+when_to_load: |
+  Plan review and acceptance steps; COMPLEX tasks reviewing test specs; or
+  any task where the test surface itself is being designed (TDD bootstrap,
+  test refactor, mock-strategy review).
+agent_hints: [test, logic-reviewer, acceptance, challenger-reviewer]
+---
+
+# Test Strategy — Senior Stance
+
+## When this applies
+Cross-stack reference loaded during plan review and at acceptance time. Complements `test-{stack}.md` (framework specifics) with strategy-level decisions: what to test, how to mock, when integration > unit, flake mitigation, test data management. Loaded by Test Agent on COMPLEX tasks and by logic-reviewer when reviewing test specs.
+
+## Default Stance
+Tests pin behavior, not implementation. A test that breaks when you refactor (without behavior change) is a bad test. Coverage % is a vanity metric — meaningful coverage is "every behavior an external caller depends on has a test that fails when that behavior breaks". Slow flaky tests are worse than no tests because people start ignoring them.
+
+## Patterns (use these)
+
+### Test pyramid — but adjusted for the stack
+- **Unit (many, fast)** — pure functions, business logic in isolation, ~ms per test.
+- **Integration (medium, slower)** — service + real DB / real Redis (test container), ~100ms per test. Where most bugs actually hide.
+- **E2E (few, slowest)** — full stack, user-facing flow, seconds per test.
+
+Classic 70/20/10 split is heuristic, not law. For data-heavy backend, 50/40/10 with more integration is often right. For UI-heavy frontend, integration tests at the component level (with React Testing Library / Vue Testing Library) replace many "unit" tests.
+
+### Test behavior, not implementation
+- BAD: assert internal method calls (`expect(spy).toHaveBeenCalledTimes(3)`) on private helpers.
+- GOOD: assert observable outcomes — return values, persisted state, side effects to mocked external systems.
+- Refactor freedom: if the behavior is unchanged, the test should pass.
+
+### Mock at boundaries, not inside the boundary
+- Mock external systems: HTTP APIs, databases, message queues, file system, time.
+- Don't mock things you own — use the real implementation. Mocking your own service layer just tests that mocks call mocks.
+- Mock the slowest layer, not every layer.
+
+### Contract tests for service boundaries
+For cross-service APIs (especially when teams diverge):
+- **Provider** publishes the schema.
+- **Consumer** runs tests against a contract derived from the schema (Pact, JSON Schema, OpenAPI).
+- A breaking change shows up in CI, not in prod.
+
+### Property-based testing where it pays
+For pure functions with constrained input space (parsers, validators, math):
+```ts
+fc.assert(fc.property(fc.string(), s => parse(format(s)) === s));
+```
+Generates inputs you'd never think to write. Catches edge cases (empty, unicode, max length) automatically. Use `fast-check` (JS) / `hypothesis` (Python).
+
+### Test data management
+- **Factories** > fixtures: `userFactory.build({ role: 'admin' })`. Easy to override one field, rest defaults.
+- **Seed deterministically** — same data every run. Use seeded random (`faker.seed(42)`).
+- **Per-test isolation** — each test creates its own data, transactions roll back, OR DB is wiped between tests.
+- **No shared global state** between tests. Order independence.
+
+### Fixed time
+Tests that involve dates/timeouts use a fake clock (`vi.useFakeTimers()` / `freezegun`). Real `Date.now()` in tests = flaky tests near midnight or on DST transitions.
+
+### Snapshot tests — sparingly
+- OK for: serialized output of pure functions (JSON shape), small UI component HTML.
+- NOT OK for: anything large, anything with non-deterministic content (timestamps, IDs), entire pages.
+- A snapshot you don't read when it changes is worse than no test.
+
+### Flake mitigation
+A flaky test = a real bug 80% of the time, not "just retry". Investigate before marking flaky.
+Common causes:
+- Time-based assertions without fake clock.
+- Test depending on previous test's state (order dependency).
+- Async race not awaited.
+- Network call to flaky external (mock it).
+- Database not cleaned between tests.
+
+If you must retry: limit to 2 attempts, alert on retry rate >5%.
+
+## Anti-Patterns (DO NOT)
+
+### Testing implementation details
+Asserting `private` method called N times, internal state values, exact call order of helpers.
+**Why it bites:** refactor breaks tests even when behavior is identical. Tests become chains forcing implementation, not verifying outcomes.
+**Rule:** test the public surface. If you need to verify private behavior, test it through public calls.
+
+### Mocking the thing under test
+`mockUserService.create.mockReturnValue({...})` and then "testing" `userService.create`. You tested the mock.
+**Rule:** never mock the subject under test. Mock its dependencies.
+
+### Mocking everything
+Mocked DB, mocked cache, mocked HTTP client, mocked logger, mocked filesystem. You're testing that mocks return what you told them to.
+**Rule:** integration tests run against real-ish dependencies (test containers, in-memory DB, msw for HTTP). Unit tests for pure logic only.
+
+### `expect(true).toBe(true)` / always-true tests
+Test passes regardless of implementation.
+**Rule:** every test should fail when the corresponding behavior breaks. Mutation testing surfaces tests that don't.
+
+### One mega-test per function
+```ts
+test('user service', async () => {
+  // 200 lines testing 15 different behaviors
+});
+```
+**Why it bites:** one assertion fails → can't tell which behavior broke. Debugging means rerunning entire setup.
+**Rule:** one behavior per test. Descriptive name reads as a spec: `it('rejects email without @ symbol')`.
+
+### `sleep(100)` for "letting things settle"
+**Why it bites:** flaky on slow CI; wasteful on fast CI; doesn't actually verify the thing finished.
+**Rule:** await the actual condition (`waitFor(() => ...)`, queue.drain, mock-clock advance).
+
+### Snapshot tests of huge HTML / JSON blobs
+Diff is unreadable; people approve without reading.
+**Rule:** only snapshot small specific outputs. For large output, write targeted assertions.
+
+### Tests that depend on prod data shape
+Pulling from prod DB at test time, asserting "user 42 exists".
+**Rule:** seeded test data. Tests are reproducible offline.
+
+### Coverage as a goal
+"We need 80% coverage." Team writes tests that touch lines without verifying behavior.
+**Rule:** coverage is a diagnostic, not a goal. 60% coverage with high-quality behavior tests > 95% coverage with implementation-detail tests.
+
+### Skipped/disabled tests with no plan to fix
+`test.skip`, `xit`, commented-out tests.
+**Rule:** delete or fix. Skipped tests rot, lose their ability to catch the bug they were meant to catch.
+
+### Generated tests as substitute for thought
+"Cursor wrote 50 tests for this function." 49 of them test the same happy path with slight variations. None test the edge case that actually matters.
+**Rule:** review every test for unique behavioral value before merging.
+
+## Decision Framework
+
+| Question | Answer |
+|---|---|
+| Pure function with bounded input? | Property-based test |
+| Service with DB, mocked DB? | Integration test with real test container |
+| External HTTP API? | Mock with msw / VCR / contract test |
+| Cross-service contract? | Pact or schema-based contract test |
+| User-facing flow? | E2E test for critical paths only |
+| Time-dependent code? | Fake clock; never real `Date.now()` |
+| Data parsing? | Property-based + edge-case suite |
+| Race condition? | Test concurrent invocations explicitly |
+| Setup-heavy code? | Factory pattern with sensible defaults |
+| Long-running async? | `waitFor` not `sleep`; advance fake timers |
+
+## Cost Model
+
+| Test type | Speed (typical) | Where most bugs found |
+|---|---|---|
+| Pure unit | < 5ms | Edge cases in algorithms, validation |
+| Integration (test container) | 50-500ms | Service contract bugs, query bugs, transaction issues |
+| E2E (real browser) | 2-30s | UX flow regressions, integration glue |
+| Property-based | varies by N | Inputs you didn't think of |
+
+| Anti-pattern | Cost |
+|---|---|
+| Mocked-everything unit tests | False confidence; bugs ship in integration paths |
+| Flaky tests retried | CI time wasted; team loses trust in suite |
+| Coverage-driven testing | Velocity drops; tests don't catch real bugs |
+| One mega-test | Debug time 10x when it fails |
+
+## Red Flags in Diff
+
+- New unit test that mocks the function being tested → flag (testing the mock).
+- New test asserting `private` method calls or internal state → flag (implementation-detail testing).
+- New `sleep`/`setTimeout` in test code without a real reason → flag (flake risk).
+- New `test.skip` / `xit` / `it.todo` without a tracking issue → flag (rot risk).
+- New snapshot test on output > 100 lines → flag (will be approved without reading).
+- New test using real `Date.now()` / `new Date()` for time-sensitive assertions → flag (use fake clock).
+- New mock for a service the test claims to integration-test → flag (it's now a unit test in disguise).
+- Test setup that copies data from prod / depends on existing data → flag (use factories).
+- Test asserting `toHaveBeenCalledTimes` on a mock 5+ times in a single test → flag (testing the mock orchestration).
+- New external HTTP call in a unit test (no mock) → flag (network in unit suite).
+- New test without arrange/act/assert structure (one giant block) → flag.

package/knowledge/references/ui-flutter.md

@@ -0,0 +1,56 @@
+---
+tags: [ui, flutter, dart, material, cupertino, responsive, mobile]
+stack_signals:
+  - language: [dart]
+  - project_type: [mobile, frontend-app]
+summary: |
+  Flutter UI consistency — Material/Cupertino choice, Theme.of usage over
+  hardcoded values, MediaQuery / LayoutBuilder responsive layouts, SafeArea,
+  text scaling, overflow handling.
+when_to_load: |
+  Task touches Flutter UI widgets, styling, layout, or design-system
+  adherence on a mobile/Flutter stack. Diff in *.dart with widget trees,
+  theme usage, or layout containers.
+agent_hints: [ui-consistency, logic-reviewer, style-reviewer]
+---
+
+# UI Consistency: Flutter
+
+## Material / Cupertino Consistency
+- Using correct design language for target platform (Material 3 vs Cupertino)?
+- Not mixing Material and Cupertino widgets in same screen?
+- Using `Theme.of(context)` for colors/text styles, not hardcoded values?
+- Custom widgets extend the theme, not override it?
+
+## Layout & Responsive
+- Using `MediaQuery` / `LayoutBuilder` for responsive layouts, not fixed sizes?
+- `SafeArea` applied where needed (notch, status bar, bottom bar)?
+- Handles landscape orientation if applicable?
+- Text scales with `MediaQuery.of(context).textScaler` (not the deprecated `textScaleFactor`)?
+- Text overflow handled (`TextOverflow.ellipsis`, `maxLines`) on dynamic content?
+
+## State Management
+- Consistent pattern across screens (all Riverpod, or all BLoC — not mixed)?
+- State scoped correctly (not global when local would suffice)?
+
+## Navigation
+- Consistent navigation pattern (GoRouter / auto_route / Navigator 2.0)?
+- Back button behavior correct on Android?
+- Deep linking supported if applicable?
+
+## Assets & Images
+- Using `CachedNetworkImage` for remote images (not raw `Image.network`)?
+- Placeholder and error builders on network images?
+- Consistent icon usage from single icon set?
+
+## Accessibility
+- `Semantics` widgets on custom components?
+- `excludeFromSemantics` on decorative images?
+- Sufficient color contrast?
+- Touch targets at least 48x48 dp?
+
+## Patterns
+- Loading/error/empty states use consistent shared widgets?
+- Form validation follows project patterns (`FormField`, validators)?
+- No hardcoded strings — using localization (`AppLocalizations` / `easy_localization`)?
+- Animation durations and curves consistent with project defaults?

package/knowledge/references/ui-web.md

@@ -0,0 +1,51 @@
+---
+tags: [ui, design-system, accessibility, react, nextjs, vue, frontend]
+stack_signals:
+  - language: [typescript, javascript]
+  - project_type: [frontend-app, monorepo]
+summary: |
+  Web UI consistency — design tokens over magic numbers, shared component
+  library use, theme adherence, accessibility checks, responsive layout.
+when_to_load: |
+  Task touches user-visible UI components (React/Next/Vue), styling,
+  spacing/typography/theme, or accessibility. Reviewer fan-out includes
+  ui-consistency on a web frontend stack. Diff in *.tsx/jsx/vue/svelte/css/scss.
+agent_hints: [ui-consistency, logic-reviewer, style-reviewer]
+---
+
+# UI Consistency: Web (React / Next.js / Vue)
+
+## Design System
+- Colors from CSS variables / design tokens, not hardcoded hex values?
+- Spacing from consistent scale (Tailwind classes, CSS vars), not magic numbers?
+- Typography using theme-defined sizes/weights, not arbitrary values?
+- Border radius, shadows consistent with design system?
+- Z-index using defined layers, not arbitrary large numbers?
+
+## Component Patterns
+- Using shared components from component library, not one-off implementations?
+- Form elements (inputs, selects, buttons) from shared form system?
+- Loading states using shared skeleton/spinner components?
+- Error states using shared error boundary/display components?
+- Empty states using shared empty state component?
+- Modal/dialog following established overlay patterns?
+- Icon usage from consistent icon library (Lucide, Heroicons, etc.)?
+
+## Accessibility
+- Semantic HTML used correctly (nav, main, section, article, button vs div)?
+- ARIA labels on interactive elements without visible text?
+- Keyboard navigation works (Tab order, Enter/Space activation, Escape to close)?
+- Focus management correct (focus trap in modals, focus restore on close)?
+- Color contrast meets WCAG AA (4.5:1 for text, 3:1 for large text)?
+- Images have descriptive alt text (or empty alt for decorative)?
+
+## Responsive
+- Same breakpoint patterns as rest of app?
+- Mobile behavior consistent (touch targets 44x44px minimum)?
+- No horizontal scroll on mobile viewports?
+- Text readable without zoom on all screen sizes?
+
+## Framework-Specific
+- **React:** key props on list items, React.Fragment vs unnecessary divs
+- **Next.js:** using `next/image`, `next/link`, `next/font` where applicable
+- **i18n:** all user-visible text via translation function, no hardcoded strings

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@loomfsm/bundle-code",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Code review / implementation bundle for loom — agents, reference knowledge, schemas, and stack candidates.",
+  "license": "Apache-2.0",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "agents",
+    "knowledge",
+    "schemas",
+    "stack-candidates.yaml"
+  ],
+  "dependencies": {
+    "@loomfsm/kernel": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "test": "tsc && node --experimental-sqlite --no-warnings --test dist/test/*.js"
+  }
+}

package/schemas/agent-feedback.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agent-feedback.schema.json",
+  "title": "Agent Feedback Entry",
+  "description": "One row in metrics/agent-feedback.jsonl. Logged when an agent missed an issue that was caught later. Drives past-misses injection and category vocab evolution.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "feedback_id",
+    "date",
+    "agent",
+    "category",
+    "pattern_to_look_for",
+    "severity",
+    "found_by",
+    "human_confirmed"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0" },
+    "feedback_id": {
+      "type": "string",
+      "pattern": "^fb-\\d{4}-\\d{2}-\\d{2}-[a-z0-9]{4,}$",
+      "description": "fb-<YYYY-MM-DD>-<short>"
+    },
+    "date": { "type": "string", "format": "date" },
+    "task_id": {
+      "type": ["string", "null"],
+      "description": "Optional: link back to the pipeline.jsonl row that ran this agent. Triggers reviewer_misses_post_merge++ on that row when set."
+    },
+    "agent": {
+      "type": "string",
+      "enum": [
+        "logic-reviewer",
+        "challenger-reviewer",
+        "style-reviewer",
+        "security",
+        "performance",
+        "acceptance",
+        "plan-conformance",
+        "plan-grounding-check",
+        "context-doc-verifier",
+        "ui-consistency",
+        "api-contract",
+        "playwright",
+        "test",
+        "implementer"
+      ]
+    },
+    "category": {
+      "type": "string",
+      "description": "MUST be a value from category-vocab.json under vocab[<agent>]. If a new pattern, set 'other' and populate proposed_new_category."
+    },
+    "proposed_new_category": {
+      "type": ["string", "null"],
+      "maxLength": 60,
+      "description": "When category='other'. Reviewed by /learn for vocab promotion (≥3 confirmed instances → permanent)."
+    },
+    "pattern_to_look_for": {
+      "type": "string",
+      "maxLength": 200,
+      "description": "Short, grep-friendly pattern. The string injected into reviewer prompts on future runs as past-miss data."
+    },
+    "missed_issue_summary": { "type": "string", "maxLength": 300 },
+    "severity": { "type": "string", "enum": ["high", "medium", "low"] },
+    "found_by": {
+      "type": "string",
+      "enum": ["prod-incident", "human-review", "another-agent", "test", "other"]
+    },
+    "example_file_line": { "type": ["string", "null"] },
+    "human_confirmed": {
+      "type": "boolean",
+      "description": "True iff a human reviewed and accepted that this is a real miss. Only confirmed entries count toward vocab promotion and pattern auto-promotion."
+    },
+    "action_taken": {
+      "type": ["string", "null"],
+      "enum": [null, "vocab-added", "agent-prompt-updated", "logged-only"]
+    }
+  }
+}

package/schemas/category-vocab.json

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "category-vocab.json",
+  "title": "Finding Category Controlled Vocabulary",
+  "description": "Per-agent allowlist of finding categories. The 'category' field on each Finding MUST match a value in this file for that agent. New patterns enter via /agent-feedback (proposed_new_category) and are promoted here after human review.",
+  "schema_version": "1.0",
+  "vocab": {
+    "logic-reviewer": [
+      "race-condition",
+      "off-by-one",
+      "error-swallowed",
+      "missing-edge-case",
+      "leak-or-cleanup-missing",
+      "ordering-assumption",
+      "type-confusion",
+      "over-engineering",
+      "duplicate-logic",
+      "regression-risk",
+      "unhandled-async",
+      "unbounded-recursion-or-loop",
+      "spec-deviation",
+      "scope-creep",
+      "coverage-gap",
+      "other"
+    ],
+    "challenger-reviewer": [
+      "concurrency-failure",
+      "hostile-input",
+      "downstream-failure-not-handled",
+      "ordering-violation",
+      "atomicity-gap",
+      "state-leak-across-requests",
+      "empty-or-null-input-failure",
+      "retry-or-replay-issue",
+      "boundary-mismatch",
+      "other"
+    ],
+    "style-reviewer": [
+      "naming-violation",
+      "duplication",
+      "anti-pattern-from-claude-md",
+      "dead-code",
+      "wrong-directory-or-layer",
+      "import-rule-violation",
+      "missing-export-pattern",
+      "loose-typing",
+      "inconsistent-with-context-doc",
+      "other"
+    ],
+    "security": [
+      "injection-sql-or-nosql",
+      "xss",
+      "auth-bypass",
+      "authorization-missing",
+      "jwt-pitfall",
+      "secret-in-log-or-bundle",
+      "csrf",
+      "cors-misconfig",
+      "sensitive-data-overreturn",
+      "rate-limit-missing",
+      "ssrf",
+      "path-traversal",
+      "dependency-vuln",
+      "public-cache-on-private-data",
+      "other"
+    ],
+    "performance": [
+      "n-plus-one",
+      "missing-index",
+      "full-table-scan",
+      "offset-pagination-on-large-table",
+      "hot-key-redis",
+      "cache-stampede-risk",
+      "unbounded-loop-or-collection",
+      "sync-call-in-async-path",
+      "missing-timeout",
+      "missing-pagination",
+      "memory-leak",
+      "react-rerender-storm",
+      "client-bundle-bloat",
+      "other"
+    ],
+    "acceptance": [
+      "lint-fail",
+      "typecheck-fail",
+      "test-fail",
+      "build-fail",
+      "missing-test-coverage",
+      "file-too-large",
+      "debug-statement-left",
+      "loose-typing-introduced",
+      "todo-or-hack-comment",
+      "ac-not-met",
+      "other"
+    ],
+    "plan-conformance": [
+      "drift-file-touched-outside-plan",
+      "drift-in-file-overreach",
+      "drift-not-in-scope-violation",
+      "partial-step-not-done",
+      "ac-not-satisfied-by-diff",
+      "auxiliary-touch",
+      "missing-test-coverage",
+      "ac-not-met",
+      "test-file-modified-by-implementer",
+      "other"
+    ],
+    "plan-grounding-check": [
+      "citation-file-not-found",
+      "citation-range-out-of-bounds",
+      "citation-claim-mismatch",
+      "unverified-marker",
+      "context-doc-cross-mismatch",
+      "missing-aaa-block",
+      "ac-not-met",
+      "other"
+    ],
+    "context-doc-verifier": [
+      "claim-not-found",
+      "claim-mismatch",
+      "naming-convention-mismatch",
+      "other"
+    ],
+    "ui-consistency": [
+      "spacing-violation",
+      "color-token-violation",
+      "typography-token-violation",
+      "component-not-from-system",
+      "responsive-breakpoint-issue",
+      "a11y-violation",
+      "other"
+    ],
+    "api-contract": [
+      "type-mismatch",
+      "missing-field",
+      "extra-field",
+      "breaking-change",
+      "version-skew",
+      "other"
+    ],
+    "playwright": [
+      "selector-flaky",
+      "missing-step-from-plan",
+      "timing-or-race",
+      "test-data-leak",
+      "other"
+    ],
+    "test": [
+      "skeleton-compile-error",
+      "test-unexpectedly-passes",
+      "missing-aaa-block",
+      "mock-misconfigured",
+      "framework-detection-failed",
+      "non-aaa-spec",
+      "test-spec-count-mismatch",
+      "other"
+    ],
+    "implementer": [
+      "test-modification-needed",
+      "plan-step-ambiguous",
+      "plan-references-nonexistent-code",
+      "checkpoint-regression",
+      "other"
+    ]
+  },
+  "promotion_rules": {
+    "to_promote_other_into_vocab": "When a finding has category='other' with proposed_new_category set and the same proposed_new_category appears in /agent-feedback for the same agent ≥3 times confirmed by human, add it to vocab[<agent>].",
+    "to_retire_unused": "Categories with zero matches across the last 100 tasks for an agent are candidates for removal — surfaced by /learn but not auto-removed."
+  }
+}

package/schemas/classifier-output.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "classifier-output.schema.json",
+  "title": "Classifier-agent output (v2.2.5 Item 9 + v2.2.6 C4 stack/change_kind extension)",
+  "description": "Structured JSON the classifier-agent emits in the context phase. Consumed by the classifier step which writes the fields into state.decisions + state.task_short. v2.2.6 extends the schema with `stack` and `change_kind` fields — the auto-spawn activation lands in v2.2.7 Item 1; this commit ships the schema substrate only.",
+  "type": "object",
+  "required": ["schema_version", "agent", "task_short", "refs_to_load", "security_needed", "antipattern_rules_applicable"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "type": "string", "enum": ["1.0", "1.1"] },
+    "agent": { "type": "string", "const": "classifier" },
+    "task_id": { "type": ["string", "null"] },
+    "task_short": {
+      "type": ["string", "null"],
+      "description": "Short kebab-case slug summarising the task — used for filenames, branch names, commit subjects.",
+      "maxLength": 60
+    },
+    "refs_to_load": {
+      "type": "array",
+      "items": { "type": "string" },
+      "maxItems": 5,
+      "description": "Senior-pattern references (filenames from agents/references/) to inject into agent prompts."
+    },
+    "security_needed": {
+      "type": "boolean",
+      "description": "Whether the security reviewer agent should run for this task."
+    },
+    "antipattern_rules_applicable": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Anti-pattern rule identifiers from CLAUDE.md that the implementer should respect."
+    },
+    "stack": {
+      "type": ["object", "null"],
+      "description": "LLM-picked stack identification. v2.2.6 substrate — populated by classifier in v2.2.7 Item 1. When present, classifier's picks override the deterministic resolveStack() defaults; when null, the table-driven detector is the source of truth.",
+      "required": ["language", "package_manager"],
+      "additionalProperties": true,
+      "properties": {
+        "language": { "type": "string", "description": "Picked from templates/stack-candidates.yaml.languages[*].name." },
+        "package_manager": { "type": ["string", "null"], "description": "Picked from stack-candidates.yaml.package_managers[*].name for the chosen language, or null when no PM applies." },
+        "test_command": { "type": ["string", "null"] },
+        "lint_command": { "type": ["string", "null"] },
+        "build_command": { "type": ["string", "null"] },
+        "project_type": { "type": ["string", "null"], "enum": [null, "frontend-app", "backend", "library", "monorepo"] }
+      }
+    },
+    "change_kind": {
+      "type": ["string", "null"],
+      "enum": [null, "type-only", "logic", "ui", "perf-sensitive", "security-sensitive", "config-only", "docs-only"],
+      "description": "Classification of the task's diff shape. v2.2.7 Item 2 consumes this for reviewer selectivity (skip style/performance on type-only diffs). v2.2.6 substrate — emit but no downstream consumer yet."
+    }
+  }
+}