@mrciphersmith/keryx 0.2.9

package/src/gdskills/bundled/rules/core/error-handling.mdc

@@ -0,0 +1,163 @@
+---
+description: "Error handling standards: Result pattern, explicit typed errors, no silent failures, no throw-everywhere anti-pattern. Use when implementing functions that can fail, calling external APIs, or handling async operations."
+alwaysApply: false
+---
+
+# Error Handling
+
+## Purpose
+Prevent silent failures, unhandled promise rejections, and throw-everywhere anti-patterns. Enforce the Result pattern for recoverable errors and explicit error types for domain failures.
+
+## When To Apply
+Apply whenever writing code that interacts with external systems, parses user input, performs I/O, or executes operations that can fail.
+
+---
+
+## Core Principle: Errors Are Values
+
+Recoverable errors are data, not exceptions. Use the **Result pattern** to make failure explicit in the type signature:
+
+```typescript
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+function err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+```
+
+---
+
+## Rules
+
+### Rule 1: Result Pattern for Recoverable Errors
+Any function that performs I/O, calls an external API, or parses external data MUST return `Result<T, E>` instead of throwing.
+
+```typescript
+// BAD — caller has no idea this can fail from the type alone
+async function fetchUser(id: string): Promise<User> {
+  const res = await http.get(`/users/${id}`);
+  return res.data; // throws if 404
+}
+
+// GOOD — failure is part of the contract
+async function fetchUser(id: string): Promise<Result<User, NotFoundError | NetworkError>> {
+  const res = await http.get(`/users/${id}`).catch(e => null);
+  if (!res) return err(new NetworkError('fetch failed'));
+  if (res.status === 404) return err(new NotFoundError(id));
+  return ok(res.data);
+}
+```
+
+### Rule 2: Typed Domain Errors
+Do not throw or return generic `Error`. Create typed error classes per domain:
+
+```typescript
+// BAD
+throw new Error('user not found');
+
+// GOOD
+export class NotFoundError extends Error {
+  readonly code = 'NOT_FOUND';
+  constructor(public readonly resource: string, public readonly id: string) {
+    super(`${resource} with id "${id}" not found`);
+  }
+}
+```
+
+Common typed errors to define per domain:
+- `NotFoundError(resource, id)`
+- `ValidationError(field, message)`
+- `UnauthorizedError(action)`
+- `ConflictError(resource, detail)`
+- `ExternalServiceError(service, cause)`
+
+### Rule 3: No Silent Failures
+Never swallow errors without action. Every `catch` block must either:
+- Re-throw (or return `err(...)`)
+- Log with full context AND take fallback action
+- Explicitly mark the result as degraded
+
+```typescript
+// BAD — silent failure
+try {
+  await sendNotification(user);
+} catch (_) {}
+
+// GOOD — explicit, logged, handled
+try {
+  await sendNotification(user);
+} catch (e) {
+  logger.warn('notification failed', { userId: user.id, error: e });
+  // explicit decision: continue without notification
+}
+```
+
+### Rule 4: No Unhandled Promise Rejections
+Every `async` call chain must end with error handling. `Promise.all` rejections must be caught. Fire-and-forget patterns must use `.catch(logger.error)`.
+
+```typescript
+// BAD
+Promise.all([fetchA(), fetchB()]); // unhandled rejection if either fails
+
+// GOOD
+const results = await Promise.allSettled([fetchA(), fetchB()]);
+const failures = results.filter(r => r.status === 'rejected');
+if (failures.length > 0) { /* handle */ }
+```
+
+### Rule 5: Propagate, Don't Wrap Blindly
+When catching and re-throwing, preserve the original error as `cause`:
+
+```typescript
+// BAD — original stack trace lost
+catch (e) { throw new Error('database failed'); }
+
+// GOOD — chain preserved
+catch (e) { throw new DatabaseError('write failed', { cause: e }); }
+```
+
+### Rule 6: No Assertions in Production Code
+`assert(condition, msg)` that throws in production is an anti-pattern for recoverable errors. Use guard clauses that return `Result` or throw typed errors.
+
+---
+
+## Error Boundary Hierarchy
+
+```
+External boundary (API, DB, filesystem)
+  └─ Return Result<T, DomainError>    ← convert to typed error here
+        └─ Domain / use-case layer
+              └─ Return Result<T, E> up the stack
+                    └─ Controller / handler
+                          └─ Map to HTTP status / user message here
+```
+
+**Only the outermost layer (controller/handler) maps errors to HTTP responses or user messages.** Business logic never formats error messages for the UI.
+
+---
+
+## Iron Laws
+
+**IRON LAW 1: A `catch (_) {}` block is forbidden. Every caught exception must be logged or returned as Result.**
+**IRON LAW 2: Generic `throw new Error('message')` in domain code is forbidden. Always use typed error classes.**
+**IRON LAW 3: Any function that can fail due to external conditions MUST reflect that in its return type.**
+
+---
+
+## Red Flags — Stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "I'll just throw here, the caller will handle it" | The caller often doesn't handle it — unhandled rejections crash processes silently |
+| "The error is unlikely, I'll skip the error case" | Unlikely errors are exactly the ones that cause production incidents |
+| "I'll add proper error handling in a follow-up" | Error handling added after-the-fact misses edge cases that were obvious during initial implementation |
+| "Using Result makes the code verbose" | Verbosity here is intentional: it forces the caller to acknowledge that failure is possible |
+| "I'll wrap everything in a try/catch at the top" | Top-level catch loses all type information and context — handle errors close to their source |
+| "I can just check if the value is null after" | Null is not an error type — it conveys nothing about why the operation failed |
+
+**IRON LAW: SILENCE IS NOT A VALID ERROR STRATEGY. EVERY FAILURE PATH MUST BE OBSERVABLE.**

package/src/gdskills/bundled/rules/core/execution-metrics.md

@@ -0,0 +1,99 @@
+---
+type: rule
+id: execution-metrics
+priority: reference
+generated_by: keryx
+---
+
+# Execution Metrics (opt-in efficiency report)
+
+A uniform, honest end-of-run report so different runs of the same skill can be
+compared. Observational only — it never changes the task.
+
+## When it applies
+
+ONLY when a skill is run **directly by a user** (not dispatched as a subagent by
+an orchestrator) — this includes when the user runs an orchestrator itself.
+
+At the START of such a run, ask exactly one yes/no question and wait:
+
+> Collect execution statistics for this run? (yes / no)
+
+- Skip the question if the user already answered it (in the prompt or a prior
+  turn), or if you are a dispatched subagent (never ask; never emit the report —
+  the top-level orchestrator owns it).
+- If **no** → proceed normally, add nothing.
+- If **yes** → do the task as usual, then append the `## Execution Metrics`
+  section (below) as the LAST thing in your final response.
+
+Do NOT alter, slow, or reshape the main task to gather metrics. If gathering a
+metric would require extra work, mark it `unknown` instead.
+
+## Persistence (artifact-producing skills)
+
+Skills that create artifacts (flow-*, autodoc-*, job-*, docpack-*, documenters,
+gdwiki enrichment, or anything that writes files) MUST also save the report:
+
+- Flows → `<flow-dir>/metrics/run-<ISO-timestamp>.md`
+- Otherwise → `.metaproject/data/<primary-module>/metrics/run-<ISO-timestamp>.md`
+
+Create the directory. Use a filesystem-safe timestamp (colons → `-`). Print the
+saved path under the table. This lets the post-commit hook and future runs find
+past reports.
+
+## Honesty rules (do not fabricate)
+
+- Never invent an exact value. If a metric is not exposed by the CLI/runtime,
+  write `unknown` or `estimated` and name the source in the `Source` column.
+- If the CLI/runtime exposes real usage/tokens/cost/duration, use those exact
+  numbers and mark `Source = cli`.
+- Tokens/cost: exact ONLY if the runtime surfaces them. Otherwise `estimated`
+  with a one-line basis (e.g. "≈ files_read × avg size"), or `unknown`. Never a
+  precise-looking guess.
+- Counts you can observe from your own tool calls (shell commands, files
+  read/modified, subagents) are `counted`; git-derived numbers are `git`.
+
+## `## Execution Metrics` section (required — emit even if many values are `unknown`)
+
+| Metric | Value | Source | Notes |
+|---|---:|---|---|
+| run_mode | user-direct / orchestrator | self | how this skill was invoked |
+| skill | ... | self | skill name + version |
+| model_used | ... | self/cli | model id if known |
+| started_at | ... | system/self | ISO timestamp if known |
+| finished_at | ... | system/self | ISO timestamp if known |
+| wall_time_minutes | ... | measured/estimated | total elapsed time |
+| total_tool_calls | ... | counted | number of shell/tool calls made |
+| shell_commands_run | ... | counted | count only terminal/shell commands |
+| files_read | ... | counted/estimated | unique files inspected |
+| files_modified | ... | counted | unique files changed |
+| lines_changed | ... | git | added + removed (`git diff --stat`) if available |
+| tests_or_checks_run | ... | counted | list commands separately below |
+| tests_or_checks_passed | ... | counted | pass/fail/unknown |
+| subagents_used | ... | counted | 0 if none |
+| subagent_names | ... | counted | comma-separated or none |
+| tokens_total | ... | cli/unknown/estimated | exact only if runtime exposes it |
+| tokens_input | ... | cli/unknown/estimated | exact only if runtime exposes it |
+| tokens_output | ... | cli/unknown/estimated | exact only if runtime exposes it |
+| tokens_per_subagent | ... | cli/unknown/estimated | map subagent -> tokens if available |
+| context_sources_used | ... | counted | e.g. AGENTS, CLAUDE, keryx index, wiki, graph |
+| keryx_used | yes/no | observed | whether keryx commands/files were used |
+| keryx_commands_run | ... | counted | exact commands if any |
+| graph_used | yes/no | observed | gdgraph / graphify / keryx graph usage |
+| wiki_used | yes/no | observed | .metaproject/wiki or keryx wiki usage |
+| health_used | yes/no | observed | keryx health usage |
+| artifacts_written | ... | counted | files/pages this run created or updated |
+| blockers_or_retries | ... | counted | failed commands, retries, missing deps |
+| final_status | done / partial / blocked | self | final outcome |
+
+After the table, add:
+
+1. **Commands Run** — every command actually executed (verbatim, in order).
+2. **Artifacts Changed** — every file created/modified (paths).
+3. **Comparison Notes** — 3–5 bullets on what likely affected speed / quality /
+   amount of context (e.g. graph freshness, batch size, model tier, cache).
+4. **Metric Reliability** — which metrics are exact (`counted`/`git`/`cli`),
+   which are `estimated` (and why), which are `unknown` (and why unavailable).
+
+The `## Execution Metrics` section is MANDATORY when stats were opted in, even if
+several values are `unknown`.

package/src/gdskills/bundled/rules/core/frontend-assistant.mdc

@@ -0,0 +1,40 @@
+---
+description: "Frontend delivery guidelines for TypeScript, React, MobX, Ant Design, and Tailwind CSS."
+alwaysApply: false
+globs:
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+---
+
+# Frontend Assistant Guidelines
+
+## Purpose
+Produce clean, maintainable, production-ready frontend code aligned with project architecture.
+
+## When To Apply
+Apply when implementing features in the frontend project (TypeScript/React/MobX/Ant Design/Tailwind CSS).
+
+## Stack
+- TypeScript
+- React
+- MobX
+- Ant Design
+- Tailwind CSS
+- Axios
+
+## Core Principles
+- Keep scope minimal and pragmatic.
+- Follow DRY and KISS.
+- Prefer explicit typing.
+- Keep business logic in stores/services, not in view components.
+
+## Technical Rules
+- Use strict TypeScript types; avoid `any`.
+- Follow `core/mobx-store-template.mdc` for MobX store patterns.
+- Use Ant Design for components and Tailwind for layout/utilities.
+- Avoid unnecessary third-party dependencies.
+
+## Output Contract
+- Final solutions must be Markdown.
+- Code must be in fenced code blocks with language labels.
+- Response language must match user query language.

package/src/gdskills/bundled/rules/core/git-rules.mdc

@@ -0,0 +1,37 @@
+---
+description: "Git safety rules for protected paths and controlled apply-changes flow."
+alwaysApply: false
+---
+
+# Git Commit Rules
+
+## Purpose
+Prevent accidental commits and enforce controlled publishing flow.
+
+## When To Apply
+Apply before any git operation: commit, branch creation, or PR creation. Always loaded alongside commit-message-formatting.mdc.
+
+## Protected Paths
+- `.cursor/`: never commit.
+- `<DOCS_ROOT>/`: do not commit by default unless explicitly approved by the user.
+- `.metaproject/jobs/` (or `$GDMETAPRO_JOBS_ROOT`): do not commit by default unless explicitly approved by the user. Job documentation — never force-delete; contains orchestrator run artifacts.
+
+## Mandatory Behavior
+1. Ensure protected paths are covered in `.gitignore`.
+2. After rule/doc updates, ask user whether to apply changes.
+3. If approved: create branch from `main`, commit, and open PR to `main`.
+4. If declined: do not create branch/commit/PR.
+
+## Commit Message Rules
+Follow `core/commit-message-formatting.mdc`.
+
+## Red Flags — Stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "This is a quick fix, I'll commit directly to main" | Branch protection rules exist precisely for quick fixes that turn into incidents |
+| "The protected path isn't really sensitive here, I'll include it" | Protected paths are protected unconditionally — context does not create exceptions |
+| "The user said to commit everything, so I'll skip the .gitignore check" | User instructions override workflow steps, not safety invariants |
+| "I'll ask about the PR later — let me commit first to save the work" | Committing before confirming intent conflates saving work with publishing it |
+
+**IRON LAW: NEVER COMMIT TO A PROTECTED PATH OR BRANCH WITHOUT EXPLICIT USER APPROVAL, REGARDLESS OF HOW URGENT THE CHANGE APPEARS.**

package/src/gdskills/bundled/rules/core/gproject-contracts.mdc

@@ -0,0 +1,198 @@
+---
+description: >
+  Dispatch and return contracts for gproject subagents. Extends
+  subagent-context-construction.md with gproject-specific fields.
+  Loaded by: gproject-orchestrator, all gproject-* subagents.
+globs: skills/gproject-*/**
+alwaysApply: false
+---
+
+# gproject Subagent Contracts
+
+## Extends
+
+This rule extends `rules/core/subagent-context-construction.md` and
+`rules/core/subagent-status-protocol.md`. All base rules apply.
+gproject adds domain-specific fields.
+
+---
+
+## Language Rule
+
+All gproject subagents MUST respond in the same language the user used in their
+original request. If the user wrote in Russian — respond in Russian. If in English — in English.
+This applies to artifact content, summaries, questions, and all user-facing output.
+The decisions registry keys (D_mode, D_frontend, etc.) remain in English regardless of language.
+
+---
+
+## Dispatch Contract (Orchestrator → Subagent)
+
+Every dispatch from gproject-orchestrator MUST include:
+
+```yaml
+# Required (from base protocol)
+description: "<phase>: <task>"
+subagent_type: "general"
+prompt: "<structured prompt — see template below>"
+
+# gproject-specific (inside prompt)
+phase: "<phase number and name>"
+mode: "new_project | task_in_project"
+user_language: "<language of the original user request>"
+input_artifacts: [<ONLY files this subagent needs>]
+decisions_so_far: <ONLY decisions relevant to this phase>
+constraints: [<from previous phases>]
+output_contract:
+  artifact_path: "<where to write full output>"
+  summary_max_tokens: 150
+  decisions_format: "key: value"
+```
+
+### Minimality Principle (Enhanced)
+
+Base rule says: "Subagents must not infer context from conversation history."
+gproject strengthens this:
+
+1. **Artifact minimality**: subagent receives ONLY artifacts listed in
+   `input_artifacts` — never all artifacts in the job directory
+2. **Decision minimality**: subagent receives ONLY decisions relevant to
+   its phase — not the full decisions.md
+3. **No cross-phase leakage**: Phase 4 agent cannot see Phase 0 raw data
+   unless explicitly passed (which it shouldn't be — use Phase 1 summary instead)
+
+### What each phase receives:
+
+| Phase | Input Artifacts | Decisions Subset |
+|-------|----------------|-----------------|
+| 0: Discovery | user input, uploaded docs, repo path | none (first phase) |
+| 1: Problem | discovery-brief.md | D_mode, D_domain, D_audience, D_scale |
+| 2: Stack | problem-statement.md | D_core_problems, D_goals, D_non_goals |
+| 3: Patterns | stack-decision.md, problem-statement.md | D_level, D_frontend..D_infra |
+| 4: PRD | problem-statement.md, architecture.md, tech-bestpractices.md | ALL decisions |
+| 5: Review | ALL artifacts, decisions.md | ALL decisions |
+| 6: Planning | prd.md, architecture.md | ALL decisions |
+
+---
+
+## Return Contract (Subagent → Orchestrator)
+
+Every subagent response MUST begin with STATUS prefix (per base protocol)
+and include gproject-specific fields:
+
+### STATUS: DONE
+
+```yaml
+STATUS: DONE
+summary: |
+  <3-5 sentences. What was produced, key decisions made, confidence level.>
+  <Max 150 tokens.>
+new_decisions:
+  D_<name>: "<value>"
+artifact_path: ".metaproject/jobs/<job>/artifacts/<name>.md"
+next_phase_needs:
+  - "<hint for orchestrator about what next phase will need>"
+```
+
+### STATUS: DONE_WITH_CONCERNS
+
+```yaml
+STATUS: DONE_WITH_CONCERNS
+summary: |
+  <3-5 sentences. Same as DONE but includes concern summary.>
+new_decisions:
+  D_<name>: "<value>"
+concerns:
+  - severity: "high | medium"
+    description: "<what's wrong>"
+    suggestion: "<how to address>"
+artifact_path: ".metaproject/jobs/<job>/artifacts/<name>.md"
+```
+
+### STATUS: NEEDS_CONTEXT
+
+```yaml
+STATUS: NEEDS_CONTEXT
+questions:
+  - id: "Q1"
+    text: "<clear question>"
+    options:
+      A: "<option — most common / recommended>"
+      B: "<option>"
+      C: "<option>"
+      D: "<option — 'not sure' or 'other' is acceptable>"
+    why: "<1 sentence: why this matters for this phase>"
+    can_be_resolved_by_agent: false | "<agent name if yes>"
+  - id: "Q2"
+    ...
+partial_artifact_path: ".metaproject/jobs/<job>/artifacts/<name>.partial.md"
+# Subagent MAY save partial work for resume
+```
+
+### STATUS: BLOCKED
+
+```yaml
+STATUS: BLOCKED
+blocker: "<clear description of what's blocking>"
+required_to_unblock: "<what the orchestrator or user must provide>"
+rollback_suggestion: "<if applicable, which phase to go back to>"
+```
+
+---
+
+## Orchestrator Context Budget
+
+The orchestrator MUST stay within these limits:
+
+| Item | Max Tokens | Notes |
+|------|-----------|-------|
+| state.json | 200 | Pipeline state only |
+| decisions.md (in memory) | 500 | Compact: ID + value only |
+| Phase summaries (all) | 800 | Max 120 per phase |
+| Current dispatch overhead | 400 | Template + routing logic |
+| **Total** | **~1900** | If exceeded, compress decisions |
+
+### Compression triggers:
+- decisions.md > 800 tokens → create decisions-compact.md (ID: value only, no rationale)
+- phase_summaries total > 800 → keep only last 3 phases in memory, rest on disk
+
+---
+
+## NEEDS_CONTEXT Resolution Protocol
+
+When a subagent returns NEEDS_CONTEXT:
+
+```
+1. Parse questions array
+2. For each question:
+   IF can_be_resolved_by_agent is truthy:
+     → Dispatch named agent with the question as task
+     → Collect answer
+     → Add to answers dict
+   ELSE:
+     → Add to user_questions list
+
+3. IF user_questions is not empty:
+     → Present to user as questionnaire
+     → Format: numbered questions with A/B/C/D options
+     → Collect answers
+
+4. Compose context supplement:
+   {
+     "answers": {
+       "Q1": {"choice": "B", "detail": "<if user added detail>"},
+       "Q2": {"choice": "A"}
+     },
+     "agent_research": {
+       "Q3": "<findings from dispatched agent>"
+     }
+   }
+
+5. Re-dispatch original subagent with:
+   - Original task + input_artifacts
+   - PLUS: context_supplement (above)
+   - PLUS: partial_artifact_path (if subagent saved partial work)
+
+6. Max 2 NEEDS_CONTEXT loops per phase
+   → After 2, escalate to user with full context
+```

package/src/gdskills/bundled/rules/core/implementation-doc-mandate.mdc

@@ -0,0 +1,149 @@
+---
+description: "Documentation mandate for all implementing agents: spec document at start, change report at end. Use when any agent is about to perform multi-step code implementation, feature development, or orchestrated task execution."
+alwaysApply: false
+---
+
+# Implementation Documentation Mandate
+
+## Purpose
+Every non-trivial implementation job must produce two documents: a **spec** at the start (what will be done and why) and a **change report** at the end (what was done, what changed, test results). This makes AI-generated work auditable, resumable, and understandable to humans without reading the code.
+
+## When To Apply
+Apply to any agent that:
+- Implements more than one file change
+- Runs for more than one phase / step
+- Involves tests, review, or PR creation
+
+Applies to: `job-orchestrator`, `feature-dev`, `task-implementer` (for multi-task jobs), any custom orchestration.
+Does NOT apply to: single-file quick fixes, standalone read-only analysis, ad-hoc one-liners.
+
+---
+
+## Document 1: Implementation Spec (create BEFORE writing any code)
+
+**Purpose:** Documents what the agent is about to do so the user can verify the plan and future agents can understand the intent.
+
+**Must include:**
+```markdown
+# Implementation Spec — <feature/issue name>
+Date: <ISO date>
+Agent: <skill name + version>
+
+## What
+<2-3 sentence description of what will be implemented>
+
+## Why
+<reason: issue link, user request, business value>
+
+## Scope
+**In scope:**
+- <item>
+
+**Out of scope:**
+- <item>
+
+## Acceptance Criteria
+- [ ] <testable criterion 1>
+- [ ] <testable criterion 2>
+
+## Approach
+<brief description of implementation approach: files to change, key design decisions>
+
+## Test Strategy
+<how tests will be written: framework, which scenarios will be covered>
+```
+
+**Storage:**
+- In `job-orchestrator` jobs: saved via `job-documenter` to `.metaproject/jobs/<job-name>/man/spec.md`
+- In `feature-dev`: saved to `<project_root>/.feature-spec.md` (gitignored) or printed and confirmed by user
+- In any agent: at minimum, the spec is presented to the user and confirmed before code is written
+
+**Timing:** Spec is created after requirements are gathered but BEFORE any branch is created or code is written.
+
+---
+
+## Document 2: Change Report (create AFTER all work is complete)
+
+**Purpose:** Auditable record of what the agent actually did — for the user, for review, and for the changelog.
+
+**Must include:**
+```markdown
+# Change Report — <feature/issue name>
+Date: <ISO date>
+Agent: <skill name + version>
+Branch: <branch name>
+PR: <PR URL or "not created">
+
+## Summary
+<2-3 sentence summary of what was implemented>
+
+## Files Changed
+| File | Action | Description |
+|------|--------|-------------|
+| src/services/UserService.ts | created | New user validation service |
+| src/services/UserService.test.ts | created | 8 tests, all passing |
+| src/components/Form.tsx | modified | Added validation UI |
+
+## Tests
+- Tests written: <N>
+- Tests passing: <N>
+- Tests failing: 0
+- Frameworks: <vitest/jest/etc>
+
+## Verification Gate
+- Lint: <pass / N errors>
+- Type-check: <pass / N errors>
+- Tests: <pass / N failed>
+
+## Acceptance Criteria Met
+- [x] <criterion 1> — verified by <test name>
+- [x] <criterion 2> — verified by <test name>
+- [ ] <criterion 3> — NOT met (reason)
+
+## Commits
+- <hash> <message>
+
+## Notes
+<anything unexpected, deferred, or worth knowing>
+```
+
+**Storage:**
+- In `job-orchestrator` jobs: saved via `job-documenter` to `.metaproject/jobs/<job-name>/man/change-report.md`
+- In `feature-dev`: appended to PR description + printed to user
+- In any agent: at minimum, printed as the final message
+
+**Timing:** Created as the very last step before reporting done to the user or orchestrator.
+
+---
+
+## Agent Compliance Checklist
+
+Before marking any implementation task as complete, verify:
+
+- [ ] Spec was created and confirmed before code was written
+- [ ] tests-creator ran before task-implementer (TDD pipeline)
+- [ ] code-verifier ran after implementation (gate: PASS or PASS_WITH_WARNINGS)
+- [ ] Change report was produced at the end
+- [ ] All acceptance criteria are checked off (or explicitly noted as not met)
+
+---
+
+## Iron Laws
+
+**IRON LAW 1: NO implementation starts without a confirmed spec. Code written without a spec has no verifiable definition of done.**
+**IRON LAW 2: NO implementation is complete without a change report. "It works" is not auditable.**
+**IRON LAW 3: The change report must reference actual test results from code-verifier — not self-assessment.**
+
+---
+
+## Red Flags — Stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "The task is simple, a spec is overkill" | Simple tasks that skip specs are where scope creep silently happens |
+| "I'll document it after the PR is merged" | Post-merge docs are never written — and are useless for PR review |
+| "The user confirmed verbally, no need to write it down" | Verbal confirmation is invisible to reviewers, future agents, and the changelog |
+| "The code is self-documenting, a change report adds nothing" | The change report is for the user and the audit trail, not for the code reader |
+| "I'll skip the spec to save time" | The spec takes 2 minutes and saves hours of "wait, what was this supposed to do?" |
+
+**IRON LAW: AN UNDOCUMENTED IMPLEMENTATION IS AN UNVERIFIABLE IMPLEMENTATION.**