agent-notes 2.26.0__tar.gz → 2.28.0__tar.gz

{agent_notes-2.26.0 → agent_notes-2.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-notes
-Version: 2.26.0
+Version: 2.28.0
 Summary: AI agent configuration manager for Claude Code, OpenCode, and Copilot
 Author-email: Eugene Naumov <min.verkligheten@gmail.com>
 License-Expression: MIT
@@ -24,6 +24,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: tomli>=1.1.0; python_version < "3.11"
+Requires-Dist: tomli-w>=1.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Dynamic: license-file

agent_notes-2.28.0/agent_notes/VERSION

@@ -0,0 +1 @@
+2.28.0

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/commands/doctor.py

@@ -2,6 +2,8 @@
 
 from pathlib import Path
 
+from ..registries.skill_registry import load_skill_registry
+
 # Re-export for backward compatibility. New code should import from agent_notes.domain.
 from ..domain.diagnostics import Issue, FixAction  # noqa: F401
 
@@ -42,6 +44,42 @@ from ..services.fs import (
     files_differ
 )
 
+# Canonical group vocabulary for skill frontmatter.
+# "process" and "domain" come from the base skills in data/skills/.
+# "rails", "docker", and "kamal" come from the sub-skills that are generated
+# during the release/packaging step and land in data/skills/ of the built
+# package (e.g. rails-models → group: rails, rails-kamal → group: kamal,
+# docker-compose → group: docker).  There is no single source-of-truth
+# constant elsewhere in the codebase, so the full vocabulary is listed here.
+_VALID_GROUPS = {"process", "domain", "rails", "docker", "kamal"}
+_VALID_MEMORY_BACKENDS = {"obsidian", "wiki", "local", "none"}
+
+
+def check_skill_frontmatter(scope: str, issues: list, fix_actions: list, profile_label: str = "") -> None:
+    """Warn (non-fatal) about skill frontmatter violations.
+
+    Checks every skill for:
+    - non-empty name and description
+    - group, if present, is in {"process", "domain"}
+    - requires_memory tokens, if present, are each in {"obsidian", "wiki", "local", "none"}
+
+    Violations are printed as advisories and do NOT affect issues/fix_actions or exit code.
+    """
+    registry = load_skill_registry()
+    for skill in registry.all():
+        if not skill.name:
+            print(f"  [skill-frontmatter] {skill.path.name}: 'name' is empty")
+        if not skill.description:
+            print(f"  [skill-frontmatter] {skill.path.name}: 'description' is empty")
+        if skill.group and skill.group not in _VALID_GROUPS:
+            print(f"  [skill-frontmatter] {skill.name}: 'group' value '{skill.group}' is not in {sorted(_VALID_GROUPS)}")
+        if skill.requires_memory:
+            for token in skill.requires_memory.split(","):
+                token = token.strip()
+                if token and token not in _VALID_MEMORY_BACKENDS:
+                    print(f"  [skill-frontmatter] {skill.name}: 'requires_memory' token '{token}' is not in {sorted(_VALID_MEMORY_BACKENDS)}")
+
+
 def _check_session_hook(scope: str, issues: list) -> None:
     """Check that the Claude Code SessionStart hook is registered in settings.json."""
     from ..services.settings_writer import has_hook
@@ -162,6 +200,9 @@ def diagnose(scope: str, fix: bool = False) -> bool:
     # SessionStart hook check (Claude Code only)
     _check_session_hook(scope, issues)
 
+    # Skill frontmatter advisory check (warn-only, non-fatal)
+    check_skill_frontmatter(scope, issues, fix_actions)
+
     # Print role→model assignments
     state = load_current_state()
     if state is not None:

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/commands/memory/reset.py

@@ -1,5 +1,6 @@
 """Destructive subcommand: reset."""
 
+import sys
 import shutil
 from typing import Optional
 
@@ -54,7 +55,7 @@ def do_reset(name: Optional[str] = None) -> None:
         agent_dir = path / name
         if not agent_dir.exists():
             print(f"No memory found for agent '{name}'")
-            exit(1)
+            sys.exit(1)
 
         print(f"{Color.YELLOW}This will delete all memory for agent '{name}'.{Color.NC}")
         confirm = input("Continue? [y/N] ")

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/commands/validate.py

@@ -163,7 +163,7 @@ def validate() -> None:
     codeblock_ok = True
     for md_file in ROOT.rglob("*.md"):
         # Skip .git and node_modules
-        if ".git" in str(md_file) or "node_modules" in str(md_file):
+        if any(part in {".git", "node_modules"} for part in md_file.parts):
             continue
 
         if not check_unclosed_code_blocks(md_file):

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/commands/wizard/execute.py

@@ -28,7 +28,7 @@ def install_agents_filtered(clis: Set[str], scope: str, copy_mode: bool = False,
                             folder_overrides: dict = None, global_home_override: str = "") -> None:
     """Install agents for selected CLIs (filtered by the wizard)."""
     from ...services import installer
-    from ...services.installer import _apply_overrides
+    from ...services.installer import _apply_overrides, _agent_glob
     from ...registries.cli_registry import load_registry
 
     registry = load_registry()
@@ -43,11 +43,12 @@ def install_agents_filtered(clis: Set[str], scope: str, copy_mode: bool = False,
         if dst is None:
             continue
 
-        files = list(src.glob("*.md"))
+        glob = _agent_glob(effective)
+        files = list(src.glob(glob))
         if not files:
             continue
 
-        place_dir_contents(src, dst, "*.md", copy_mode)
+        place_dir_contents(src, dst, glob, copy_mode)
 
 
 def install_config_filtered(clis: Set[str], scope: str, copy_mode: bool = False,
@@ -161,15 +162,16 @@ def _execute_install(
     if _cmd_names:
         print(f"  {Color.GREEN}✓{Color.NC} Commands   {', '.join(sorted(_cmd_names))}")
 
-    # SessionStart hook (Claude Code only)
+    # SessionStart hooks — for every backend with features.session_hook == true
     from ...services.installer import _install_session_hook
-    try:
-        _claude = _registry.get("claude")
-        if _claude.name in clis:
-            _claude_eff = _apply_overrides(_claude, folder_overrides, global_home_override or None)
-            _install_session_hook(_claude_eff, scope, memory_backend=memory_backend, memory_path=memory_path or "")
-    except (KeyError, Exception):
-        pass
+    for _hook_backend in _registry.with_feature("session_hook"):
+        if _hook_backend.name not in clis:
+            continue
+        try:
+            _hook_eff = _apply_overrides(_hook_backend, folder_overrides, global_home_override or None)
+            _install_session_hook(_hook_eff, scope, memory_backend=memory_backend, memory_path=memory_path or "")
+        except Exception:
+            pass
 
     _fs.silent_file_ops = False
 

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/agents/agents.yaml

@@ -9,6 +9,7 @@ agents:
     color: purple
     effort: high
     claude_exclude: true
+    codex_exclude: true
     claude:
       tools: "Agent(coder, reviewer, security-auditor, test-writer, test-runner, system-auditor, database-specialist, performance-profiler, api-reviewer, tech-writer, devops, explorer), Read, Grep, Glob, Bash"
       memory: user

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/agents/coder.md

@@ -15,6 +15,7 @@ You are an implementation specialist. You write, edit, and fix code.
 - No new abstractions, helpers, or utilities for one-time operations.
 - No comments or docs on code you didn't change.
 - Validate at system boundaries (user input, external APIs). Trust internal code.
+- Make tests pass by fixing the root cause, NEVER by gaming them — do not hardcode expected values, weaken or delete assertions, special-case the test's inputs, or overload equality to fake a pass. If a test appears wrong or the spec seems contradictory, surface it rather than bypassing it.
 
 ## Reporting
 

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/agents/refactorer.md

@@ -28,6 +28,7 @@ Golden rule: behavior must not change. If tests pass before, they must pass afte
 - Do NOT introduce new dependencies
 - Keep commits atomic — one refactoring per commit
 - If tests don't exist, create them before refactoring
+- Never make the suite green by weakening, skipping, or deleting tests — if a test breaks under a refactor, the refactor changed behavior; fix the refactor, not the test.
 
 ## Red-Green-Refactor
 

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/agents/reviewer.md

@@ -34,6 +34,7 @@ You are a code reviewer. You analyze code and provide actionable feedback.
 - Do not flag pre-existing issues outside the changed code.
 - Include specific file:line references for every finding.
 - Commit to a severity before writing the bullet. If you find yourself retracting a finding within the same entry ("actually this is not an issue…"), either downgrade it to a lower severity before posting, or drop it entirely. A bullet that flags-and-retracts is worse than no bullet — it wastes downstream attention. If uncertain whether something is a real issue, use Suggestion and state the uncertainty in plain terms, rather than marking Critical and walking it back.
+- **Bugfix-plus-test check.** When reviewing a bugfix accompanied by a test: verify the test would FAIL without the fix (it must genuinely falsify the bug). Flag tests that pass trivially or whose assertions cannot fail. Flag "fixes" that game tests — hardcoded expected values, weakened or deleted assertions, special-cased test inputs, or overloading equality to fake a pass — instead of fixing root cause. Flag silent behavior changes disguised as refactors.
 
 ## Reporting
 

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/agents/shared/cost_reporting.md

@@ -11,3 +11,7 @@ Render every column the `agent-notes cost-report` CLI emits — `agent(model)`,
 `Cost report skipped: <one-line reason>`
 
 If the command ran but produced an error message, print the error verbatim under the heading instead of a table. Fabricating a table when the CLI did not run is a violation.
+
+Cost table: once at end of response, never mid-response.
+
+Always include the cost report at the end of every response.

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/agents/shared/execution.md

@@ -86,7 +86,7 @@ Never spawn one agent per bullet point from the user's prompt. Combine related s
 
 Skip agents for: simple questions (answer directly), single-file edits (coder alone), or two-grep lookups (do it yourself).
 
-Give each agent a specific task with all context (paths, criteria). Always include the cost report at the end of every response.
+Give each agent a specific task with all context (paths, criteria).
 
 ### Permission pre-check (HARD RULE)
 

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/agents/shared/guardrails.md

@@ -9,10 +9,8 @@
 7. "Let me just verify this one thing" followed by 10 reads → if verification needs 10 reads, dispatch.
 8. Breaking tasks into steps so small they have no independent value → group into meaningful chunks.
 9. Writing a plan that only restates the user's words → a plan must include discovery findings, dependency order, and flagged risks.
-10. Skipping the cost report at the end of a response → always include it.
-11. Fabricating a cost-report table or placeholder rows when `agent-notes cost-report` did not run successfully → forbidden. Print "Cost report skipped: <reason>" on a single line instead.
-12. Reporting "done" before tests pass and plan items match → forbidden by Done Gate.
-13. Reporting "done" / "complete" / "shipped" without an `agent-notes memory add ... session lead` call covering this work → forbidden by the Done Gate.
+10. Reporting "done" before tests pass and plan items match → forbidden by Done Gate.
+11. Reporting "done" / "complete" / "shipped" without an `agent-notes memory add ... session lead` call covering this work → forbidden by the Done Gate.
 
 ## Done Gate (HARD RULE)
 

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/agents/shared/hard_limits.md

@@ -25,4 +25,3 @@ Exception: trivial requests (factual questions, conversational replies, single-l
 - Plans: structured bullet lists with file paths. No prose paragraphs.
 - Agent briefings: context + task + acceptance criteria. No commentary or justification.
 - Never narrate internal deliberation — report outcomes only.
-- Cost table: once at end of response, never mid-response.

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/agents/test-writer.md

@@ -26,6 +26,7 @@ You are a test writer. You create comprehensive, meaningful tests.
 - Never use Float for monetary values.
 - When asserting on error messages or structured output, match SEMANTIC CONTENT, not exact wording. Use substring checks, regex, or category matchers — never full-string equality. Example: to verify a validation error about a missing `description` field, assert that the error text contains `"description"` and indicates absence (e.g. "missing", "required", "empty"), NOT that it equals `"description: missing"`.
 - If the task gives you example error strings from a spec, treat them as ILLUSTRATIVE — the implementer is free to phrase equivalent messages differently. Your tests must pass against any reasonable phrasing that conveys the same meaning.
+- **Fail-first discipline.** A regression or characterization test MUST be demonstrated to FAIL against the current (unfixed) code, for the right reason, before it is considered to cover a bug. Never write tautological/always-green tests or assertions that cannot fail (e.g. asserting on a mock you fully control, or on a value you just hardcoded). The test's job is to falsify the bug — if it passes on the broken code, it is worthless.
 
 ## Reporting
 

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/cli/claude.yaml

@@ -10,6 +10,7 @@ layout:
   config: CLAUDE.md
   memory: agent-memory/
   settings: settings.json
+  agent_extension: md
 features:
   agents: true
   skills: true
@@ -20,7 +21,11 @@ features:
   config_style: inline
   settings_template: false
   supports_symlink: true
+  session_hook: true
+  stop_hook: true
+  allow_entries: true
 global_template: global-claude.md
 exclude_flag: claude_exclude
 accepted_providers: [anthropic, bedrock, vertex]
 use_model_class: true
+preferred_family: claude

agent_notes-2.28.0/agent_notes/data/cli/codex.yaml

@@ -0,0 +1,29 @@
+name: codex
+label: Codex CLI
+global_home: ~/.codex
+local_dir: .codex
+layout:
+  agents: agents/
+  skills: skills/
+  config: AGENTS.md
+  hooks: hooks.json
+  agent_extension: toml
+features:
+  agents: true
+  skills: true
+  rules: false
+  commands: false
+  memory: false
+  frontmatter: codex
+  config_style: inline
+  settings_template: false
+  supports_symlink: true
+  session_hook: true
+  stop_hook: false
+  allow_entries: false
+global_template: global-codex.md
+exclude_flag: codex_exclude
+strip_memory_section: true
+accepted_providers: [openai]
+use_model_class: false
+preferred_family: gpt

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/cli/opencode.yaml

@@ -6,6 +6,7 @@ layout:
   agents: agents/
   skills: skills/
   config: AGENTS.md
+  agent_extension: md
 features:
   agents: true
   skills: true
@@ -16,7 +17,11 @@ features:
   config_style: inline
   settings_template: false
   supports_symlink: true
+  session_hook: false
+  stop_hook: false
+  allow_entries: false
 global_template: global-opencode.md
 exclude_flag: opencode_exclude
 strip_memory_section: true
 accepted_providers: [github-copilot, anthropic, openrouter, openai, google, moonshot]
+preferred_family: claude

agent_notes-2.28.0/agent_notes/data/global-codex.md

@@ -0,0 +1,40 @@
+# Global Instructions
+
+## Coding philosophy
+
+- Read existing code before writing new code. Match project patterns.
+- Minimal changes: only what was requested. Do not refactor beyond scope.
+- Fix root causes, not symptoms.
+- One approach, commit to it. Course-correct only on new evidence.
+
+## Behavior
+
+- Investigate before answering. Never speculate about code you haven't read.
+- No over-engineering: no extra features, abstractions, or configs beyond scope.
+- No comments or docs on code you didn't change.
+- When the task is unclear, ask one clarifying question instead of guessing.
+
+## Safety
+
+- Confirm before: `git push --force`, `rm -rf`, `DROP TABLE`, branch deletion.
+- Never commit: `.env`, `*.pem`, credentials, API keys, secrets.
+- Never bypass: `--no-verify`, `--force` without explicit user request.
+- Never force-push to main/master.
+
+## Commits
+
+- Load the `git` skill when asked to commit and follow its workflow.
+- Analyze all changes, group into logical chunks, make small focused commits.
+- Format: `#<ticket> type(scope): short description` — title only, no body.
+- Extract ticket number from branch name when available.
+- Types: feat, fix, refactor, test, docs, chore, style, perf
+
+## Agent delegation
+
+- Use subagents when tasks can run in parallel or require isolated context.
+- For simple tasks, sequential operations, or single-file edits, work directly.
+- Use `explorer` for quick lookups to save context tokens.
+- Use `database-specialist` for schema, indexes, and query analysis.
+- Use `performance-profiler` for bottleneck identification.
+- Use `api-reviewer` for API design and consistency checks.
+- Use `lead` for complex multi-step tasks requiring coordination.

agent_notes-2.28.0/agent_notes/data/models/gpt-5-4-mini.yaml

@@ -0,0 +1,14 @@
+id: gpt-5-4-mini
+label: GPT-5.4 Mini
+family: gpt
+class: haiku
+aliases:
+  openai: gpt-5.4-mini
+pricing:
+  input: 0.15
+  output: 0.60
+  cache: 0.02
+capabilities:
+  vision: true
+  long_context: false
+  tool_use: true

agent_notes-2.28.0/agent_notes/data/models/gpt-5-4.yaml

@@ -0,0 +1,14 @@
+id: gpt-5-4
+label: GPT-5.4
+family: gpt
+class: sonnet
+aliases:
+  openai: gpt-5.4
+pricing:
+  input: 3.00
+  output: 15.00
+  cache: 0.30
+capabilities:
+  vision: true
+  long_context: true
+  tool_use: true

agent_notes-2.28.0/agent_notes/data/models/gpt-5-5.yaml

@@ -0,0 +1,14 @@
+id: gpt-5-5
+label: GPT-5.5
+family: gpt
+class: opus
+aliases:
+  openai: gpt-5.5
+pricing:
+  input: 10.00
+  output: 40.00
+  cache: 1.00
+capabilities:
+  vision: true
+  long_context: true
+  tool_use: true

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/skills/code-review/SKILL.md

@@ -47,18 +47,26 @@ Work through these five lenses in order. Report findings grouped by lens, ranked
 
 ## Output format
 
+Emit each finding as a record: `severity` (blocking | suggestion) · `file` · `line` · `finding` · `why` · `fix` (if applicable). When the output is consumed by another agent, emit JSON objects with exactly those keys. For a human summary, group by severity:
+
 ```
 BLOCKING
-- [file:line] [finding] — [why it matters]
+- [file:line] [finding] — [why it matters] → [fix]
 
 SUGGESTIONS
 - [file:line] [finding] — [alternative if applicable]
 
-APPROVED (if no blocking issues)
+APPROVED (state explicitly when there are no blocking findings)
 ```
 
 A BLOCKING finding must be resolved before merge. A SUGGESTION is optional.
 
+## Lens 6 — Test integrity / anti-gaming
+
+- Does each test actually falsify what it claims to cover — would it fail without the change?
+- Watch for gamed fixes: hardcoded expected values, weakened or deleted assertions, special-cased inputs that only work for the exact test data.
+- Watch for behavior changes disguised as refactors (suite stays green because the test was weakened, not because behavior was preserved).
+
 ## Scope discipline
 
 Do not flag cosmetic changes unless they create real ambiguity. A review that lists 20 nits trains authors to ignore reviews entirely.

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/skills/debugging-protocol/SKILL.md

@@ -59,7 +59,8 @@ Test with the smallest possible change — one that confirms or disproves the hy
 ## Phase 4 — Fix
 
 Apply the minimal fix for the root cause:
-- Fix the root cause, not the symptom.
+- Fix the root cause, not the symptom. Do not make the symptom disappear by swallowing or catching the error, loosening an assertion, adding a retry that hides a race, or special-casing the failing input. Those game the symptom check without fixing the bug.
+- Before touching the fix, confirm the reproduction actually fails on the current code. A repro that never truly failed proves nothing. After fixing, confirm it now passes AND would have failed without the change.
 - Remove all instrumentation from Phase 1.
 - Run the full test suite.
 - Confirm the original failure is gone and nothing else regressed.

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/skills/improve-codebase-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: improve-codebase-architecture
-description: "Find deepening opportunities — modules where the interface is nearly as complex as the implementation. Use when user wants to improve architecture, reduce coupling, make code more testable, or says 'clean up the design'."
+description: "Find deepening opportunities — modules where the interface is nearly as complex as the implementation. Use when user wants to improve architecture, reduce coupling, make code more testable, or says 'clean up the design'. For broad code-quality hardening use rsi; for a single safe refactor use refactoring-protocol."
 group: process
 ---
 

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/skills/migrate-memory/SKILL.md

@@ -2,7 +2,7 @@
 name: migrate-memory
 description: "Reconcile the Obsidian vault or Wiki knowledge base to the latest canonical format. Use after upgrading agent-notes or when vault structure looks outdated or inconsistent."
 group: process
-requires_memory: obsidian, wiki
+requires_memory: obsidian,wiki
 ---
 
 # Migrate Memory

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/skills/refactoring-protocol/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: refactoring-protocol
-description: "Safe refactoring: green tests first, one extraction at a time, structure OR behavior never both. Use when user wants to refactor code, reduce duplication, or says 'clean this up'."
+description: "Safe refactoring: green tests first, one extraction at a time, structure OR behavior never both. Use when user wants to refactor code, reduce duplication, or says 'clean this up'. For an iterative multi-dimensional cleanup loop use rsi; for module or interface redesign use improve-codebase-architecture."
 group: process
 ---
 
@@ -51,6 +51,7 @@ Return to Step 2 for the next extraction.
 ## Hard rules
 
 - **Structure OR behavior in one commit, never both.** If you find a bug while refactoring: stash the refactor, fix the bug in a separate commit, then resume. Mixing them makes the change impossible to review and risky to revert.
+- **Never achieve green by weakening the tests.** Do not weaken, skip, delete, or rewrite a test to make it pass after a refactor. If a test breaks, the refactor changed behavior by definition — fix or revert the refactor, not the test. The test suite is the invariant the refactor must preserve.
 - **Do not optimize during refactor.** Performance tuning is a separate session with its own measurement baseline.
 - **Do not add features during refactor.** If you notice a missing edge case: note it, address it in a separate commit after the refactor is complete.
 - **Stop when the smell is gone.** Over-refactoring is as harmful as under-refactoring.

agent_notes-2.28.0/agent_notes/data/skills/rsi/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: rsi
+description: "Recursive code-improvement loop: iteratively harden an existing codebase across bugs, performance, quality, consistency/homogeneity, pattern adherence, tests, atomicity, independence, and DRY — strictly without adding functionality. Use when the user wants to improve, clean up, or harden existing code, says 'rsi', or asks to raise code quality without new features. For a single one-shot refactor use refactoring-protocol; for module or interface redesign use improve-codebase-architecture."
+group: process
+argument-hint: "[path or scope, optional]"
+---
+
+# RSI — Recursive Self-Improvement (Code)
+
+Iteratively improve EXISTING code until it stops yielding improvements. The lead orchestrates; specialized agents do the work. This is a quality loop, not a feature loop.
+
+## Prime invariant
+
+- **Behavior-preserving.** NEVER add functionality, new features, new public API, or new config. Only improve what already exists.
+- **Tests green before a pass and after every change.** If the target has no test coverage, write a characterization test FIRST, then improve.
+- **One change = one concern.** Structure OR behavior, never both in the same change.
+
+## The loop (lead-orchestrated, loop-until-dry)
+
+1. **Scope.** Resolve the target (arg path, or whole project). Identify the test command and confirm the suite is green. If it is red, stop and report — fix the suite before improving. Do NOT run the loop on code that lacks meaningful test coverage — write characterization tests first: studies report that looping over weakly-tested code produces roughly 10x more false-positive "fixes" than with a strong suite (~16% vs ~1.4%).
+2. **Scan — one dimension at a time.** Dispatch read-only agents to produce a ranked list of concrete opportunities:
+   - `debugger` / `security-auditor` → bugs, correctness, vulnerabilities
+   - `performance-profiler` → hot paths, N+1, redundant work
+   - `system-auditor` → duplication, dead code, coupling, inconsistent implementations of one concept
+   - `reviewer` → readability, naming, pattern & consistency adherence
+   - `test-writer` (read-only pass) → coverage gaps
+
+   Each opportunity is a **finding record**: `file` · `line` · `dimension` · `severity` (blocker | major | minor) · `why` · `fix` (one-line proposed change). When a downstream agent consumes the scan, emit findings as JSON objects with exactly those keys; otherwise the dashed form `file:line — dimension/severity — why — fix` is fine.
+
+3. **Prioritize.** Order: correctness/safety > missing tests on touched code > DRY/duplication > consistency/homogeneity > pattern & convention fit > performance > clarity/naming. Drop anything that changes behavior or adds capability.
+4. **Apply ONE atomic, independent change.** Dispatch `coder` (bugfix) or `refactorer` (behavior-preserving cleanup). Smallest viable diff.
+5. **Verify.** Run affected tests — must stay green. `reviewer` confirms: no behavior change, fits conventions, genuinely improves the dimension. On regression → revert and re-plan. Note: research suggests genuine logic bugs repair poorly in an iterative loop (~45% vs ~77% for surface/name errors) — escalate real logic bugs to `debugger` rather than re-looping.
+6. **Commit (auto, atomic).** One concern per commit, independent and revertable. Use the `git` skill's message format. Then take the next opportunity.
+7. **Repeat passes.** Converge when TWO consecutive full passes surface no new actionable improvement. Then report.
+
+## Dimensions rubric
+
+Each dimension: what to **hunt**, what to **fix**, what to **leave alone**.
+
+- **Bugs & correctness** — off-by-one, nil/None, races, missing error handling, unhandled edge cases. Fix minimally + add a regression test. Don't redesign.
+- **Performance** — measured hot paths, N+1 queries, redundant work, bad complexity, unbounded growth. Don't micro-optimize cold paths or trade clarity for guesswork.
+- **Code quality** — long methods, deep nesting, unclear names, magic values. Extract, apply guard clauses, rename. Don't gold-plate.
+- **Consistency / homogeneity** — the same kind of thing implemented multiple different ways: mixed styles for one object type, divergent shapes for one concept, inconsistent signatures or return types. Converge on one canonical form and reduce needless variation. Distinct from DRY — this targets divergent *expression* of one concept, not duplicated *logic*. Don't force genuinely different things into a false-common shape.
+- **Pattern adherence** — match the project's dominant idioms, structure, and conventions. Align outliers. Don't invent new patterns.
+- **Tests** — cover changed or risky code, fix flaky/slow tests, add missing edge cases. Don't test trivial getters.
+- **Atomicity** — split god-functions and god-classes into single-responsibility units. Don't over-fragment.
+- **Independence** — reduce coupling, remove hidden global state, narrow interfaces. Don't add abstraction layers nobody needs.
+- **DRY** — collapse genuine duplication into one source of truth. Don't DRY accidental similarity (premature abstraction is worse than duplication).
+- **Dead code** — unused functions, variables, imports, branches. Delete after confirming no external use.
+
+## Gates (hard)
+
+- **Green-before / green-after.** A red suite halts the loop.
+- **No-feature gate.** If a change adds capability, it is out of scope — reject it.
+- **Atomic & independent commits.** Revert on regression with `git revert` — never `reset --hard` or force-push.
+- **Max 2 review rounds per change,** then accept or drop it. (empirically, ~2 rounds captures most attainable improvement — on the order of 76–95% — so further rounds are mostly wasted polish.)
+- **Fail-first, anti-gaming.** Every regression/characterization test must be shown to FAIL on the unfixed code (it must actually reproduce the bug) BEFORE the fix lands. Reject any "fix" that games the test rather than addressing root cause — hardcoded expected values, weakened/removed assertions, special-casing the asserted inputs, or operator/equality overloading. A test that passes regardless of the fix proves nothing. The reviewer confirms the test genuinely falsifies the bug.
+
+## Done
+
+Report: improvements grouped by dimension, commits made, tests added, deferrals (with reasons), and anything skipped as out-of-scope (new functionality).

{agent_notes-2.26.0 → agent_notes-2.28.0}/agent_notes/data/skills/tdd/SKILL.md

@@ -36,7 +36,8 @@ Because you just wrote the code, you know exactly what behavior matters and how
 
 ## GREEN — make it pass
 
-- Write the minimum code to pass the test. Hardcode values if that's all it takes — you'll triangulate with the next test.
+- Write the minimum code to pass the test. Hardcode values if that's all it takes — you'll triangulate with the next test. A hardcoded return is only valid as a transient step toward a general implementation; if it stays in permanently to satisfy the test, that is reward-hacking, not TDD.
+- Do not reach GREEN by gaming the test: no special-casing the test's specific inputs, no weakening the assertion, no deleting the assertion. The test must pass because the behavior is implemented, not because the check was neutered.
 - Run the test. Confirm green.
 - If still failing: read the failure output carefully before changing anything else.