feat: enforce behavior-focused testing guidance

- steer audits, reconciliation, and implementers toward real production boundaries
- preserve legitimate text-contract tests and avoid duplicated production logic
- update project prompts and replace proxy tests with observable behavior checks

Author: iamdevlinph

AGENTS.md

@@ -97,6 +97,24 @@
   changed observable contracts, reported regressions, meaningful boundaries,
   and plausible costly failures, especially security, trust-boundary, or
   data-loss risks.
+- Test observable production behavior instead of inspecting implementation
+  text. Prefer the narrowest real executable boundary: use the public interface
+  when practical; otherwise call the actual production function or module and
+  assert inputs, outputs, state transitions, side effects, failures, or
+  persisted results. Use focused integration tests when behavior spans
+  components.
+- Do not use source-file reads, regex or literal presence, snapshots, symbol
+  counts, private-helper calls, or internal statement ordering as proxies for
+  functionality. Source-text assertions are appropriate only when the text is
+  itself the observable contract, including generated artifacts, CLI or prompt
+  output, externally consumed configuration, migration SQL, and installed
+  template, skill, or agent assets. Assert only the smallest meaningful textual
+  contract.
+- Do not recreate production decision logic inside tests. If no real executable
+  boundary exists, introduce the smallest localized test seam only when
+  justified. Otherwise preserve the existing regression coverage and report why
+  safe behavioral replacement would require disproportionate, risky, or
+  ambiguous restructuring.
 - Use one representative case per necessary observable contract or reported
   regression. Skip speculative edge cases, redundant permutations,
   implementation-detail assertions, and contrived or unreachable states.

RELEASE_NOTES.md

@@ -1,3 +1,3 @@
-- Add conservative context optimization to project audits and template reconciliation, with semantic ownership, selective routing, byte measurements, and idempotence reporting.
-- Make the canonical template and generated prompts maintain concise `AGENTS.md` routers and evidence-backed `PLANS.md` indexes without changing existing CLI or state contracts.
-- Add semantic preservation and routing fixtures for safeguards, feature dependencies, nested instructions, overrides, configured fallbacks, missing references, and no-op projects.
+- Add behavior-focused testing guidance for audits, reconciliation, and implementation agents, prioritizing real production boundaries while preserving genuine text-contract tests.
+- Update project sync and audit prompts to activate focused test-quality review without broad legacy cleanup.
+- Replace duplicated production logic and source-inspection proxies with observable output and behavior checks.

TEMPLATE_AGENTS.md

@@ -205,6 +205,24 @@ triggered skills and selectively read references.
   repository has an established test setup, cover changed observable contracts,
   reported regressions, meaningful boundaries, and plausible costly failures,
   especially security, trust-boundary, or data-loss risks.
+- Test observable production behavior instead of inspecting implementation
+  text. Prefer the narrowest real executable boundary: use the public interface
+  when practical; otherwise call the actual production function or module and
+  assert inputs, outputs, state transitions, side effects, failures, or
+  persisted results. Use a focused integration test when the contract spans
+  components.
+- Do not use source-file reads, regex or literal presence, snapshots, symbol
+  counts, private-helper calls, or internal statement ordering as proxies for
+  functionality. Source-text assertions are appropriate only when the text is
+  itself the observable contract, such as generated artifacts, CLI, help, or
+  prompt output, serialization or protocol formats, externally consumed
+  configuration, migration SQL, or required templates and instructions. Assert
+  only the smallest meaningful textual contract.
+- Do not recreate production decision logic inside tests. If no real executable
+  boundary exists, introduce the smallest localized test seam only when
+  justified. Otherwise preserve the existing regression coverage and report why
+  safe behavioral replacement would require disproportionate, risky, or
+  ambiguous restructuring.
 - Use one representative case per necessary observable contract or reported
   regression. Skip speculative edge cases, redundant permutations,
   implementation-detail assertions, and contrived or unreachable states.

assets/TEMPLATE_AGENTS.md

@@ -205,6 +205,24 @@ triggered skills and selectively read references.
   repository has an established test setup, cover changed observable contracts,
   reported regressions, meaningful boundaries, and plausible costly failures,
   especially security, trust-boundary, or data-loss risks.
+- Test observable production behavior instead of inspecting implementation
+  text. Prefer the narrowest real executable boundary: use the public interface
+  when practical; otherwise call the actual production function or module and
+  assert inputs, outputs, state transitions, side effects, failures, or
+  persisted results. Use a focused integration test when the contract spans
+  components.
+- Do not use source-file reads, regex or literal presence, snapshots, symbol
+  counts, private-helper calls, or internal statement ordering as proxies for
+  functionality. Source-text assertions are appropriate only when the text is
+  itself the observable contract, such as generated artifacts, CLI, help, or
+  prompt output, serialization or protocol formats, externally consumed
+  configuration, migration SQL, or required templates and instructions. Assert
+  only the smallest meaningful textual contract.
+- Do not recreate production decision logic inside tests. If no real executable
+  boundary exists, introduce the smallest localized test seam only when
+  justified. Otherwise preserve the existing regression coverage and report why
+  safe behavioral replacement would require disproportionate, risky, or
+  ambiguous restructuring.
 - Use one representative case per necessary observable contract or reported
   regression. Skip speculative edge cases, redundant permutations,
   implementation-detail assertions, and contrived or unreachable states.

assets/agents/implementer.toml

@@ -13,7 +13,7 @@ You write the actual code and run the smallest relevant validation that proves t
 1. Understand — Read the relevant files and the assigned slice before editing. Don't guess at contracts.
 2. UI/style preflight — When UI appearance or interaction changes, inspect the closest same-purpose shipped features (especially tables, filters, search, forms, dialogs, and page layouts), then record the applicable components, tokens, layout, responsive behavior, interactions, states, and accessibility conventions. Data, content, event, or backend-only changes do not trigger this step unless they change that UI contract. Reuse applicable patterns. If no written standard exists but trustworthy repeated precedent does, derive concise always-on guidance in `AGENTS.md` and feature-specific decisions or exceptions in `PLANS.md`. Pause and ask the user whether to keep, update, or override before divergence, changing a guideline, resolving conflicts, or proceeding without a trustworthy analogue. Use browser or screenshot tooling for rendered comparison when available; otherwise report unavailable.
 3. Implement — Make the smallest change that satisfies the slice; follow the discovered UI and code patterns, naming, and idioms. Use secure-by-default patterns: never hardcode secrets — read from env vars / a secrets vault, and leave a `// TODO: load from env or secrets vault` marker where a credential belongs.
-4. Unit test — Add or update one representative test for each necessary observable contract or reported regression. Keep boundary coverage only for an explicit requirement, past defect, or plausible security, trust-boundary, or data-loss failure; skip speculative edge cases and redundant permutations.
+4. Unit test — Add or update one representative test for each necessary observable contract or reported regression. Exercise the narrowest real production boundary when practical; otherwise call the actual production function or module, or use a focused integration test when behavior spans components. Never read production source, match implementation text, count symbols, snapshot code, or assert private helper calls as a proxy for functionality, and never recreate a production decision algorithm in test-local code. Source-text assertions are appropriate only when text is itself the observable contract, such as generated artifacts, CLI or prompt output, protocols, externally consumed configuration, migration SQL, or required templates and instructions. Introduce only the smallest localized test seam when justified. If safe behavioral coverage would require disproportionate, risky, or ambiguous restructuring, preserve the regression coverage and report the limitation. Keep boundary coverage only for an explicit requirement, past defect, or plausible security, trust-boundary, or data-loss failure; skip speculative edge cases and redundant permutations.
 5. Semantic decomposition — Map each responsibility to its final file, then extract independently understandable concerns before validation. Pages, routes, controllers, commands, and entrypoints orchestrate only; page files do not define child components, substantial UI sections, or domain logic. Put independently changeable UI in descriptive feature-local files, and move independently testable hooks, schemas, data access, transformations, and domain logic out of presentation. Avoid generic dumping grounds; keep components feature-local unless shared/global by evidence. Tiny inseparable helpers or markup may remain inline. An unrelated small fix need not trigger broad refactoring. Name any concrete framework/tooling exception in the handoff.
 6. Validate — Run the smallest existing check that proves the changed observable behavior. Run broader tests, lint, formatting, or builds only when affected shared behavior, a failure, the changed files, or an explicit release requirement justifies them. Paste the actual result. If validation fails, fix and re-run — never report success on red.
 7. Hand off — Send every completed feature to `code-reviewer` for structural and UI consistency review. Report the responsibility map, extracted files, applicable precedent/standard, tests, rendered comparison or its unavailability, and output. State plainly if anything is unverified.

assets/agents/quick-implementer.toml

@@ -17,7 +17,7 @@ Proceed only when the requested change is well specified, localized to one or tw
 1. Read the target file, its immediate caller or consumer, and the nearest relevant test.
 2. UI/style preflight — When UI appearance or interaction changes, inspect the closest same-purpose shipped UI and reuse its components, tokens, layout, responsive behavior, interactions, states, and accessibility conventions. Data, content, event, or backend-only changes do not trigger this step unless they change that UI contract. If no written standard exists but trustworthy repeated precedent does, record always-on guidance in `AGENTS.md` and feature-specific decisions or exceptions in `PLANS.md`. Pause and ask the user whether to keep, update, or override before divergence, changing a guideline, resolving conflicts, or proceeding without a trustworthy analogue. Use browser or screenshot comparison when available; otherwise report unavailable. Escalate visual-direction work beyond this role's scope to `implementer`.
 3. Make the smallest in-scope edit. Preserve unrelated user changes.
-4. Add or update one focused test only for a necessary observable contract or reported regression when a test harness exists. Keep boundary coverage only for an explicit requirement, past defect, or plausible security, trust-boundary, or data-loss failure.
+4. Add or update one focused test only for a necessary observable contract or reported regression when a test harness exists. Exercise the narrowest real production boundary when practical; otherwise call the actual production function or module, or use a focused integration test when behavior spans components. Never inspect implementation text as a proxy for functionality or recreate a production decision algorithm in test-local code. Source-text assertions are appropriate only when text is itself the observable contract, such as generated artifacts, CLI or prompt output, protocols, externally consumed configuration, migration SQL, or required templates and instructions. Introduce only the smallest localized test seam when justified; preserve the regression coverage and report when safe behavioral replacement would require disproportionate, risky, or ambiguous restructuring. Keep boundary coverage only for an explicit requirement, past defect, or plausible security, trust-boundary, or data-loss failure.
 5. Semantic decomposition — Map responsibilities to final files and extract independently understandable concerns before validation. Pages, routes, controllers, commands, and entrypoints orchestrate only; child UI, substantial sections, and domain logic belong in descriptive feature-local files. Avoid generic dumping grounds; keep components feature-local unless shared/global by evidence. Tiny inseparable helpers or markup may remain inline. Name any concrete framework/tooling exception.
 6. Validate the decomposed implementation with the smallest existing check that proves the changed observable behavior. Run formatting, lint, build, or broader tests only when the changed files or an explicit release requirement make them relevant.
 7. Hand off — Route every completed feature to `code-reviewer` for structural and UI consistency review. Report changed files, responsibility map, extracted files, applicable precedent/standard, rendered comparison or its unavailability, validation result, and any unverified point in at most eight bullets.

assets/skills/codex-kit-audit-agents/SKILL.md

@@ -74,11 +74,28 @@ as static rather than claiming observed context selection.
 
 Review relevant tests, package scripts, workflows, skill triggers, and
 validation commands. Require the smallest existing check that proves changed
-observable behavior. Remove tests only when they are demonstrably duplicate,
-obsolete, or speculative; preserve explicit regression and plausible security,
-trust-boundary, or data-loss coverage. Repair stale commands or paths only from
-repository evidence, narrow overly broad skill triggers, and validate every
-created or modified project skill with an available skill validator.
+observable behavior. In relevant test audits, identify source-inspection tests
+used as proxies for runtime behavior and production decision logic recreated in
+test-local code. Determine the legitimate regression or observable contract
+each test protects, then prefer the narrowest existing production boundary: the
+public interface when practical, otherwise the actual production function or
+module, or a focused integration test when behavior spans components. Introduce
+only the smallest localized test seam when justified. Remove an old
+source-inspection or duplicated-logic test only after its legitimate contract is
+covered.
+
+Preserve focused source-text assertions when text is itself the observable
+contract, including generated artifacts, CLI, help, or prompt output,
+serialization or protocol formats, externally consumed configuration, migration
+SQL, and required templates or instructions. Do not delete tests merely because
+they assert strings. When behavioral replacement would require disproportionate,
+risky, or ambiguous restructuring, preserve the regression coverage and report
+the limitation instead of substituting fake behavioral coverage. Otherwise
+remove tests only when demonstrably duplicate, obsolete, or speculative;
+preserve explicit regression and plausible security, trust-boundary, or
+data-loss coverage. Repair stale commands or paths only from repository
+evidence, narrow overly broad skill triggers, and validate every created or
+modified project skill with an available skill validator.
 
 If validation fails, restore only audit-attributable edits where safely
 possible, preserve pre-existing work, and report any partial state. The final
@@ -89,6 +106,8 @@ report must include:
 - routing scenarios and checks performed;
 - justified large always-loaded sections;
 - unresolved conflicts, ambiguities, missing references, and unavailable checks;
+- source-inspection or duplicated-logic tests replaced, preserved as genuine
+  text contracts, or reported as unsafe to restructure;
 - preservation, reference-integrity, and idempotence results.
 
 This audit is independent of template synchronization. Never run `project sync`,

assets/skills/codex-kit-reconcile-agents/SKILL.md

@@ -65,10 +65,22 @@ description: Reconcile a refreshed TEMPLATE_AGENTS.md with project guidance, opt
    Information already read in the current conversation need not be removed
    from its history.
 10. Review relevant tests, scripts, workflows, skill triggers, and validation
-    commands. Require the smallest existing check that proves changed observable
-    behavior. Remove tests only when demonstrably duplicate, obsolete, or
-    speculative while preserving regression and plausible security,
-    trust-boundary, or data-loss coverage.
+    commands. Classify incoming and existing testing guidance by whether it
+    exercises observable production behavior through the narrowest real
+    executable boundary. Never promote source inspection, implementation-text
+    matching, or test-local copies of production decision logic as functional
+    verification. Preserve focused source-text assertions when text is itself
+    the observable contract, including generated artifacts, CLI or prompt
+    output, protocols, externally consumed configuration, migration SQL, and
+    required templates or instructions. Introduce only the smallest justified
+    test seam, preserve regression and plausible security, trust-boundary, or
+    data-loss coverage, and report cases that cannot be improved without
+    disproportionate, risky, or ambiguous restructuring. Repair tests only when
+    they are directly relevant to changed guidance or required validation;
+    otherwise report low-value source-inspection or duplicated-logic tests as
+    audit candidates rather than broadening reconciliation into unrelated test
+    rewrites. Remove tests only when demonstrably duplicate, obsolete, or
+    speculative.
 11. Validate reference integrity, preserved semantic ownership, always-on
     safeguards, representative routing, project skills, and expected second-run
     idempotence. Validate every created or modified project skill with an

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iamdevlinph/codex-kit",
-	"version": "1.6.0",
+	"version": "1.6.1",
 	"description": "Portable Codex subagents and project AGENTS.md defaults.",
 	"type": "module",
 	"bin": {