Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
docs: add project skills for scoped PR improvement checks
tt-a1id254f2d477be
diff --git a/.agents/skills/README.md b/.agents/skills/README.mdnew file mode 100644index 00000000..6e99e81b--- /dev/null+++ b/.agents/skills/README.md@@ -0,0 +1,24 @@+# Project review Skills++These Skills support the scoped [PR improvement check](../../CONTRIBUTING.md#pr-improvement-check).+They are repository files, usable without a global installation or personal filesystem paths.++| Skill | Upstream | Pinned commit | Included files |+| --- | --- | --- | --- |+| simplify-codebase | [tt-a1i/simplify-codebase](https://github.com/tt-a1i/simplify-codebase) | `f8f7084801272f46e35531dcca29bff20f1935f6` | SKILL.md, references/, agents/, LICENSE |+| test-value | [tt-a1i/test-value](https://github.com/tt-a1i/test-value) | `e111931defac959ad11ddc67b8eb2f3743d08129` | SKILL.md, references/, agents/, LICENSE |++Included files are byte-for-byte copies at the recorded commits, with their MIT+licenses and attribution retained. simplify-codebase uses the text-only release+before the optional Cleanup Map renderer was introduced; PR preparation needs+its consumer/contract proof workflow. Its included references are complete for+this revision. Runtime diagram sources and the distributed Archify Skill remain+separate from these maintainer tools.++## Updating a source++Use a dedicated PR to select and record the new upstream commit, inspect changed+instructions and any newly introduced dependencies, and copy the complete referenced+files from that revision. Verify local links, source equality, licenses, and scope+against repository instructions. Keep these files independent of user installations;+ordinary application PRs use them as read-only guidance.diff --git a/.agents/skills/simplify-codebase/LICENSE b/.agents/skills/simplify-codebase/LICENSEnew file mode 100644index 00000000..d2042c20--- /dev/null+++ b/.agents/skills/simplify-codebase/LICENSE@@ -0,0 +1,21 @@+MIT License++Copyright (c) 2026 simplify-codebase contributors++Permission is hereby granted, free of charge, to any person obtaining a copy+of this software and associated documentation files (the "Software"), to deal+in the Software without restriction, including without limitation the rights+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell+copies of the Software, and to permit persons to whom the Software is+furnished to do so, subject to the following conditions:++The above copyright notice and this permission notice shall be included in all+copies or substantial portions of the Software.++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE+SOFTWARE.diff --git a/.agents/skills/simplify-codebase/SKILL.md b/.agents/skills/simplify-codebase/SKILL.mdnew file mode 100644index 00000000..5e3139ab--- /dev/null+++ b/.agents/skills/simplify-codebase/SKILL.md@@ -0,0 +1,81 @@+---+name: simplify-codebase+description: Simplification audit or authorized codebase simplification whose stated objective is to remove accidental complexity. Use for evidence-backed deletion or consolidation of dead code, duplicate state, redundant APIs or layers, ownerless abstractions, obsolete compatibility or design records, and over-engineering in any language; also use for 代码简化 or 熵回收. Do not use for general code review, onboarding, style-only refactoring, or performance tuning.+---++# Simplify Codebase++Reduce the number of concepts and obligations a codebase must keep coherent. Line-count reduction is supporting evidence, not the objective. A successful run may conclude that the inspected surface is already justified.++## Select mode and scope++First choose the authority mode:++- **Survey** for simplification audit, investigation, or candidate-finding requests. Remain read-only and return ranked evidence.+- **Change** for explicit simplify, remove, consolidate, refactor, or repository-documentation edit requests. Prove each cut, implement it within the authorized scope, and validate the surviving contract.++Then choose the coverage scope:++- **Focused** when the user names a subsystem, symbol, state machine, dependency, or suspected duplication. Cover that boundary thoroughly before expanding outward.+- **Broad** when the request spans the repository or asks for multiple candidates. Partition the system and account for every in-scope domain.++Deleting a reachable capability, supported interface, stored representation, or compatibility path is a product decision. Describe the consequence and obtain direction unless the user has already chosen it.++## Establish the contract++1. Read the repository's instructions, architecture and decision records, manifests, test guidance, and generated-file conventions.+2. Inspect version-control state and preserve unrelated work. Identify vendored, generated, migration, fixture, and public-package surfaces before classifying them.+3. Trace the runtime path from entrypoints through configuration, registration, dispatch, persistence, processes, and wire boundaries. Record public, dynamic, persisted, generated, and compatibility-sensitive contracts.+4. In Change mode, discover the repository's real verification commands and capture a proportional baseline when feasible. A failing baseline narrows what the final checks can prove.++Preserve authorization, trust-boundary validation, security isolation, accessibility essentials, data-loss prevention, stored-format compatibility, and cleanup that establishes quiescence. Treat changes to these protections as their own explicitly authorized objective, not an incidental simplification.++The contract map is complete when all in-scope entrypoints and authority boundaries are enumerated, each is traced far enough to name its owner and observable contract, and every uninspected or externally unknowable surface is recorded as a blind spot.++## Cover the relevant surface++For every Broad engagement, and for Focused work involving dynamic architecture or dependency substitution, read [investigation.md](references/investigation.md). Build a coverage map before ranking findings; the first plausible deletion must not end the survey.++For concurrency, cancellation, readiness, cleanup, defensive copies, validation, authorization, security isolation, accessibility, data-loss prevention, or cross-process data, also read [boundaries-and-lifecycle.md](references/boundaries-and-lifecycle.md).++Use repository-native search, compiler and linter output, dependency metadata, and history as discovery instruments. Treat their findings as leads until runtime consumers and contracts have been examined.++## Build a proof record++For every in-scope lead that reaches consumer-map evidence or could retire a meaningful contract, record:++```text+Candidate: the exact contract, representation, or layer to remove or merge+Burden: the concepts, synchronization, publication, or testing cost it creates+Reachability: production, non-production, dynamic, external, and persisted consumers+Rationale: why it exists and whether that reason remains current+Cut: declarations, implementations, branches, artifacts, docs, and dependencies affected+Consequence: observable capability or compatibility behavior surrendered+Confidence / risk: evidence strength, uncertainty, blast radius, and reversibility+Proof: the smallest check that would expose an incorrect cut+Net effect: maintenance concepts removed minus replacement or migration machinery added+```++Prove cut boundaries below file granularity when the candidate shares an artifact with surviving consumers. Account for candidate-exclusive selectors, members, fields, keys, registry entries, generated fragments, and fixtures without disturbing the surviving owners.++Keep or downgrade the candidate when a real consumer exists, dynamic reachability remains unresolved, a current decision still owns the design, the change merely relocates complexity, the result is outside scope or retires no meaningful obligation, or the available check cannot distinguish success from accidental breakage.++Rank confidence separately from benefit. A high-value guess does not outrank a smaller proved cut.++Candidate proof is complete when every qualifying lead is classified as ranked, rejected, or unresolved, and every unresolved lead names the fact required to decide it.++## Decide and act++In Survey mode, stop after reporting the ranked evidence. Include important rejected candidates when the rejection teaches something or identifies a concrete missing fact.++In Change mode, read [execution-and-recovery.md](references/execution-and-recovery.md) and select the strongest authorized cut. One ownership boundary is the default batch size, not a run limit: for an explicitly requested set of cuts, finish and validate each boundary before starting the next.++If the user requests a simplification proposal, local cleanup annotation, or design-record consolidation, or if a selected change invalidates an ADR, RFC, design note, or architectural inventory, read [decision-records.md](references/decision-records.md). Do not turn an ordinary code audit into a repository-wide documentation purge.++If the user asks to combine findings from another branch, pull request, task, or agent run, read [integrating-findings.md](references/integrating-findings.md). Preserve evidence, not finding counts.++## Deliver the result++For a survey, report coverage, ranked proof records, rejected or unresolved high-value leads, and the next fact needed for each uncertainty.++For a change, complete the validation and operation receipt defined in [execution-and-recovery.md](references/execution-and-recovery.md). Report each validation layer separately; a narrow green check does not establish broader runtime, deployment, or user acceptance.diff --git a/.agents/skills/simplify-codebase/agents/openai.yaml b/.agents/skills/simplify-codebase/agents/openai.yamlnew file mode 100644index 00000000..48833adb--- /dev/null+++ b/.agents/skills/simplify-codebase/agents/openai.yaml@@ -0,0 +1,8 @@+interface:+ display_name: "Simplify Codebase"+ short_description: "Prove and remove accidental codebase complexity"+ default_prompt: "Use $simplify-codebase to audit this repository and rank the safest high-impact simplifications without editing files."++policy:+ allow_implicit_invocation: true+diff --git a/.agents/skills/simplify-codebase/references/boundaries-and-lifecycle.md b/.agents/skills/simplify-codebase/references/boundaries-and-lifecycle.mdnew file mode 100644index 00000000..d9e9b6ea--- /dev/null+++ b/.agents/skills/simplify-codebase/references/boundaries-and-lifecycle.md@@ -0,0 +1,45 @@+# Boundaries and Lifecycle++Purpose: prove which boundary or lifecycle mechanisms protect distinct owners and transitions. Finish with every mechanism in the selected candidate mapped to a guarantee or classified as redundant.++## Locate the real boundary++For every validator, copy, freeze, capture, retry, rollback, or containment layer, identify the value's origin, current owner, next owner, mutation rights, lifetime, and failure domain.++Typical borrowed handoffs include private, same-process calls whose types and ownership conventions are enforced by one component boundary. Typical owned boundaries include untrusted input, configuration parsing, model or tool JSON, queues, storage, network protocols, plugins, workers, subprocesses, and data crossing asynchronous lifetime boundaries.++Defense on an owned boundary is part of the contract until evidence proves otherwise. Defense on a borrowed handoff may be removable when it protects only impossible or owner-violating behavior. Tests built from hostile getters, fake typed values, post-handoff mutation, or callback replacement reveal an assumed contract; determine whether production actually promises that contract before treating the test as authoritative.++Never trade away authorization, input trust validation, data-loss prevention, accessibility essentials, durable-format compatibility, or security isolation as an incidental cleanup.++## Draw the lifecycle graph++List the actors that can create, publish, start, settle, cancel, stop, flush, and dispose the resource. Then map every flag, promise, queue, sentinel, callback, controller, and terminal result to:++- the owner that writes it;+- readers that make decisions from it;+- the transition it represents;+- the race or failure it prevents;+- the cleanup or quiescence guarantee it completes.++Two mechanisms are redundant only when they represent the same transition for the same owner and protect the same failure window. Similar names are not enough. The lifecycle analysis is complete when every mechanism in scope is mapped to an owner, transition, failure window, and terminal guarantee, with unknowns made explicit.++Preserve distinct mechanisms when they separately guarantee atomic publication and rollback, isolate callback failures, arbitrate competing terminal outcomes, own a worker or process, bridge different durability levels, or make disposal wait until no work can escape.++When several mechanisms truly mirror one fact, choose the representation already observed at the strongest boundary. Route other readers to that owner and remove synchronization glue rather than creating another coordinator that leaves both truths alive.++## Prove quiescence++For cleanup changes, completion means more than returning from `dispose` or setting a stopped flag. Establish that no owned task can publish, mutate durable state, retain resources, or invoke callbacks after the terminal boundary.++Inspect timers, event listeners, streams, child processes, workers, pending promises, queues, retries, abort handlers, file descriptors, and deferred writes. Name the check that would reveal a late effect.++## Model races before deletion++For asynchronous candidates, write a small event table when ordering matters:++```text+Event or transition | owner | allowed predecessors | terminal effect | late-event behavior+```++Exercise at least the normal path, cancellation before start, cancellation during work, competing terminal outcomes, partial publication failure, and repeated cleanup when those states are reachable. Remove a branch only after its ordering guarantee is represented elsewhere or proven unnecessary.diff --git a/.agents/skills/simplify-codebase/references/decision-records.md b/.agents/skills/simplify-codebase/references/decision-records.mdnew file mode 100644index 00000000..797da388--- /dev/null+++ b/.agents/skills/simplify-codebase/references/decision-records.md@@ -0,0 +1,33 @@+# Decision Record Cleanup++Purpose: keep the repository's current design owner accurate without erasing historical rationale that still prevents mistakes.++Follow the repository's native lifecycle, naming, pairing, and archival conventions. Historical records may be intentionally immutable; update their current owner and links instead of rewriting frozen history.++## Find the current owner++Trace shipped code, configuration, schemas, generated catalogs, package documentation, newer decisions, and inbound links. Titles and dates help discovery but do not prove ownership.++Classify the older record:++- **Current** when it still owns a live contract, compatibility rule, durable representation, or independently useful rejected alternative.+- **Partly displaced** when some of its behavior survives under a newer owner.+- **Fully displaced** when no production, configuration, schema, persisted, wire, migration, compatibility, or documented capability remains and a current record can carry all durable rationale.++## Consolidate without erasing lessons++Before retiring a fully displaced record, transfer unique rationale, alternatives, consequences, shipped evidence, known gaps, capability surrendered, conditions for reintroduction, and the reason the original motivation no longer wins. Implementation inventories and tests that described only deleted behavior need not survive as design rationale.++Repair inbound links, indexes, generated catalogs, paired translations, and consistency metadata as required by the repository. Search exact filenames, symbols, configuration keys, protocol strings, and record titles afterward.++Keep records separate when the underlying feature survives through another delivery route or implementation, when stored or compatibility behavior remains, or when consolidation would hide a still-useful warning against reintroducing a failed design.++Report the old and current owners, evidence for the classification, rationale transferred, links repaired, validation performed, and any record deliberately retained.++## Match the artifact to the decision++Use the repository's existing decision mechanism. A durable proposal should identify the present contract and consumer evidence, the exact removal or consolidation, the strongest reason to keep the design, the capability surrendered, acceptance criteria, risks, and verification boundary. Consolidate overlapping proposals under the record that already owns the decision instead of creating competing sources of truth.++Use a short local TODO, FIXME, issue, or equivalent only for a small actionable cleanup that does not need a durable architectural decision. Give it a stable searchable topic tag when repository conventions allow, then name the concrete burden and the condition that would make the change safe. Keep uncertain or product-level questions in the evidence report rather than depositing speculative annotations throughout the codebase.++Respect the selected authority mode: Survey mode reports the appropriate artifact without creating it unless the user requested repository edits.diff --git a/.agents/skills/simplify-codebase/references/execution-and-recovery.md b/.agents/skills/simplify-codebase/references/execution-and-recovery.mdnew file mode 100644index 00000000..2974d996--- /dev/null+++ b/.agents/skills/simplify-codebase/references/execution-and-recovery.md@@ -0,0 +1,64 @@+# Execution and Recovery++Purpose: retire each proved obligation completely, validate the surviving system in widening rings, and leave a recovery path proportional to every side effect.++## Choose a reviewable cut++Prefer one high-confidence ownership boundary over a mixed cleanup batch. The selected change should retire a complete obligation and have a decisive check. If investigation reveals a larger product choice or broader migration than the user authorized, present the ranked plan and obtain one scope confirmation before applying it.++Pause application when dynamic or external consumers remain unknown, stored data lacks a migration story, baseline failures erase the intended signal, the cut crosses unrelated ownership boundaries, or rollback would be impractical. Convert the result into an evidence report with the exact missing decision or fact.++## Remove the obligation vertically++Follow the contract from outside inward and back out. Account for:++- public declaration, schema, route, command, option, or manifest;+- registration, dispatch, parsing, and compatibility paths;+- implementations, adapters, state, caches, events, and cleanup;+- imports, exports, packages, build and generated inventories;+- migrations, fixtures, examples, documentation, and operational configuration;+- tests dedicated to the retired behavior and tests protecting the surviving contract;+- dependencies and scripts that become unnecessary.++Delete compatibility glue when no compatibility obligation exists. When one does exist, preserve it or provide an explicit migration with an end condition. Do not replace two representations with a new synchronization layer.++Keep unrelated working-tree changes intact. Do not commit, push, publish, deploy, or alter protected environments unless the user separately authorizes that action.++The cut is structurally complete when every affected declaration, consumer, artifact, owner, and compatibility obligation is either changed, deliberately retained with a reason, or explicitly excluded as outside scope.++## Verify in widening rings++1. **Residue check**: search removed names, strings, paths, formats, flags, and docs.+2. **Decisive check**: run the smallest test or probe that would fail if the cut were incorrect.+3. **Lead check**: re-run any analyzer or query that produced the original candidate.+4. **Local gates**: run the affected package's type, lint, unit, integration, build, generation, or smoke commands.+5. **Repository gates**: run the broader relevant suite when cost and scope justify it.+6. **Boundary comparison**: compare public output, persisted representation, wire behavior, operational lifecycle, and user-visible behavior.+7. **Diff audit**: inspect every changed file, whitespace integrity, generated artifacts, and dependency lock changes.++When the simplification claims a latency, throughput, memory, startup, or other performance effect, add a controlled before-and-after measurement whose workload and environment make that claim meaningful.++Report each gate separately. Passing a narrow unit test does not establish build, integration, runtime, deployment, or user acceptance.++If a post-change check fails, compare it with the baseline and decide whether the failure was pre-existing, the implementation is incomplete, or the candidate was load-bearing. Repair the current batch or undo it using the recorded recovery path. Preserve the meaningful check and revise the proof instead of weakening the gate to make the deletion pass.++## Produce an operation receipt++Record:++```text+Scope: ownership boundary changed+Baseline: commands and pre-existing failures+Retired obligation: contract, state, layer, or dependency removed+Artifacts: files and generated outputs changed+Realized net effect: concepts, artifacts, lines, and dependencies removed minus replacement or migration machinery added, where measurable+Behavior: preserved and intentionally changed observations+Verification: exact commands, probes, and results+Residual risk: untested boundaries or external uncertainty+Retained candidates: high-value items kept and why+Undo: files or commit range to reverse and any data/config restoration required+```++The undo path must match the side effects. Source-only changes may be reversible from the diff; migrations, published packages, deployments, and durable data require explicit restoration steps and separate authorization.++The batch is complete only when the structural cut criterion, every applicable verification ring, the complete diff audit, and the operation receipt are all satisfied or reported as unavailable with the resulting evidence limitation.diff --git a/.agents/skills/simplify-codebase/references/integrating-findings.md b/.agents/skills/simplify-codebase/references/integrating-findings.mdnew file mode 100644index 00000000..1ce91246--- /dev/null+++ b/.agents/skills/simplify-codebase/references/integrating-findings.md@@ -0,0 +1,24 @@+# Integrating Findings++Purpose: map every imported finding to retained, consolidated, rejected, superseded, or unresolved against the destination's current contracts.++## Establish independent contribution++Compare each source with its own merge base or authoritative default branch, not only with the current working branch. Identify which code changes, proof records, design records, annotations, and validation results belong uniquely to that source. Treat stale findings as hypotheses against the current tree.++For every imported candidate:++- re-check symbols, consumers, dynamic entrypoints, history, and compatibility in the destination state;+- retain non-overlapping evidence that meets the current confidence bar;+- merge overlapping rationale into the record that owns the contract;+- discard duplicates, weaker restatements, and findings invalidated by newer code;+- preserve the strongest counterargument, tradeoff, verification boundary, and unresolved uncertainty;+- distinguish a ported proposal from a change already implemented and validated.++The integrated result is complete when every source finding is mapped to retained, consolidated, rejected, superseded, or unresolved, with a reason. Raw candidate count is not a preservation requirement.++## Integrate changes safely++Apply only the code or documentation the user authorized. Resolve overlaps according to current ownership and behavior rather than source order. Re-run residue searches and validation on the combined state; results from an isolated branch do not prove the integrated tree.++When updating a pull request, report the true retained scope, sources surveyed, consolidations and rejections, intentional exclusions, current-head validation, and remaining review gaps. Keep work draft or otherwise marked incomplete while the candidate set or verification is still changing. Close, supersede, comment on, or otherwise mutate external reviews only with the user's authority.diff --git a/.agents/skills/simplify-codebase/references/investigation.md b/.agents/skills/simplify-codebase/references/investigation.mdnew file mode 100644index 00000000..68e43674--- /dev/null+++ b/.agents/skills/simplify-codebase/references/investigation.md@@ -0,0 +1,92 @@+# Investigation Playbook++Purpose: produce a bounded coverage map in which every in-scope domain is inspected or explicitly excluded, then rank only candidates supported by contract evidence.++## Build a coverage map++Start with the largest or most central production surfaces, then partition the relevant system by responsibility rather than file type. Typical domains are:++- entrypoints, orchestration, and runtime control;+- public APIs, commands, configuration, and feature selection;+- domain state, caches, events, and lifecycle transitions;+- persistence, schemas, migrations, replay, and compatibility;+- protocols, plugins, dependency injection, reflection, and code generation;+- foreground and background execution, workers, processes, and resource ownership;+- packages, adapters, examples, scripts, tests, snapshots, and documentation.++Adapt the domains to the repository. For each domain, name the entrypoints inspected, central production paths read, searches run, history or decision records consulted, and unresolved blind spots. The coverage pass is complete when every in-scope domain is inspected or explicitly excluded with a reason.++When breadth warrants parallel investigation and the user has authorized it, give each worker a non-overlapping domain and require the same proof record. Aggregate by confidence and ownership boundary rather than arrival order or raw finding count.++## Hunt for maintenance burdens++Use these lenses to generate leads:++- **Dormant contract**: an export, hook, event, option, package, protocol field, or command has no current production consumer.+- **Split truth**: multiple states, summaries, caches, formats, or event families encode one fact and must remain synchronized.+- **Ownerless flexibility**: an abstraction, fallback, strategy, flag, or extension point promises possibilities no current product path owns.+- **Relay layer**: a wrapper, package, service, or route forwards behavior without reducing coupling or establishing a boundary.+- **Parallel state machine**: flags, promises, queues, sentinels, controllers, or callbacks describe the same transition.+- **Boundary theater**: validation, copying, rollback, or hostile-object defense sits on a trusted handoff rather than a real trust or ownership boundary.+- **Local infrastructure**: custom parsing, retry, framing, matching, diffing, scheduling, or collection code duplicates a suitable platform feature or dependency.+- **Support drag**: tests, examples, snapshots, generated expectations, or documentation are the only reason an otherwise unused surface remains.+- **Feature fossil**: implementation was abandoned or removed while schema, configuration, tests, compatibility logic, or design records still preserve its outline.++Do not equate visual similarity with duplication. Independent implementations may test an interface, isolate failure domains, protect different owners, or support distinct compatibility contracts.++## Climb the evidence ladder++Classify each lead by the strongest evidence reached:++1. **Smell**: complexity, duplication, or awkwardness is visible.+2. **Static lead**: a search or analyzer reports no or limited use.+3. **Consumer map**: every repository hit is classified and relevant callers and callees have been read.+4. **Contract proof**: dynamic loading, external use, persistence, compatibility, ownership, and design history have been resolved.+5. **Behavior proof**: a decisive check and recovery path demonstrate what would reveal a wrong change.++Smells and static leads are not deletion authority. High-confidence application normally requires contract proof and behavior proof.++## Classify consumers++Classify every hit instead of counting it:++- **Runtime**: shipped code, operational configuration, migrations, loaders, deployment scripts, and real entrypoints.+- **Support**: tests, documentation, comments, snapshots, examples proved to be illustrative only, and generated expectations.+- **Uncertain**: fixtures, public exports, examples that may double as smoke paths, plugin registrations, reflection, lazy imports, string dispatch, manifests, generated code, and external package consumers.++Search exact symbols and their alternate call forms, file and package names, configuration and environment keys, event and protocol strings, serialized field names, registry identifiers, and documentation examples. Read the surrounding control flow; search counts do not establish semantics.++Resolve uncertain consumers by inspecting registration and loading code, package publication boundaries, downstream repositories when in scope, persisted data, compatibility policy, and release history. If external consumption cannot be bounded, state the uncertainty and lower confidence.++## Read history as design evidence++Use blame, log, pull requests, issues, ADRs, RFCs, and comments to answer:++- What failure, requirement, or future plan introduced this surface?+- Does that condition still exist?+- Which current artifact owns the decision?+- What new evidence outweighs the original reason?+- What capability would become expensive to restore?++An old date or quiet file is only a discovery hint. A rejected historical alternative may still be valuable if it prevents a recurring mistake.++## Evaluate replacement dependencies++A standard-library feature or maintained dependency can reduce local responsibility, but only when it removes more obligation than it adds.++Compare exact semantics, unsupported residual behavior, maintenance and adoption, release cadence, security posture, transitive footprint, platform compatibility, migration cost, wrapper size, dedicated tests retired, and supply-chain exposure. Prefer platform facilities, then already-present dependencies, then a new dependency when the net ownership reduction is clear.++A wrapper that preserves most local policy while delegating a small primitive is not a simplification. Record the residual contract explicitly.++## Rank without gaming the result++Score independently:++- confidence in reachability and contract evidence;+- blast radius and reversibility;+- maintenance concepts retired;+- observable behavior or optionality surrendered;+- validation strength;+- implementation and migration cost.++Do not reward raw deleted lines, candidate count, or dramatic scope. No safe candidate is a valid evidence-backed result.diff --git a/.agents/skills/test-value/LICENSE b/.agents/skills/test-value/LICENSEnew file mode 100644index 00000000..5461740a--- /dev/null+++ b/.agents/skills/test-value/LICENSE@@ -0,0 +1,21 @@+MIT License++Copyright (c) 2026 tt-a1i++Permission is hereby granted, free of charge, to any person obtaining a copy+of this software and associated documentation files (the "Software"), to deal+in the Software without restriction, including without limitation the rights+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell+copies of the Software, and to permit persons to whom the Software is+furnished to do so, subject to the following conditions:++The above copyright notice and this permission notice shall be included in all+copies or substantial portions of the Software.++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE+SOFTWARE.diff --git a/.agents/skills/test-value/SKILL.md b/.agents/skills/test-value/SKILL.mdnew file mode 100644index 00000000..309b172b--- /dev/null+++ b/.agents/skills/test-value/SKILL.md@@ -0,0 +1,90 @@+---+name: test-value+description: Improve test value and feedback cost when auditing slow, flaky, redundant or brittle tests; choosing tests during implementation; or reviewing test changes before a commit or PR. Keep ordinary implementation and pre-commit use scoped to the affected behavior, not a repository-wide audit.+---++# Test Value++Protect outcomes worth preserving at a cost proportionate to their risk. Test counts, coverage percentages and green runs are evidence, not substitutes for product judgment. When an AI writes both implementation and tests, check whether they share the same mistaken assumption.++## Choose the scope++Preserve the user's existing authorization and operational boundaries.++- **Audit existing tests:** investigate cost, false alarms and protection within the requested scope. An audit request is read-only; an optimization request permits scoped changes. Read [audit.md](references/audit.md).+- **Implementation or pre-commit review:** examine the behavior being changed and its affected tests. Decide whether to add, adapt, reuse or remove tests. Reviewing before a commit does not itself authorize committing or pushing.+- **Diagnose a failure:** identify the outcome the failing check protects, then distinguish a product regression, obsolete assertion, environment failure or unstable test. Keep a narrowly requested fix narrow.++Read [decision-examples.md](references/decision-examples.md) when dealing with automatic-layout snapshots, shared matrices, source assertions, asynchronous waits, test doubles, benchmarks or coverage gaps.++## Establish an independent basis for correctness++Explain what must remain true using user requirements, public contracts, compatibility commitments or a real failure. The current implementation and its own generated output cannot, by themselves, establish the correct expectation.++For tests being added or changed, answer three questions in the reasoning or a short change explanation:++1. Which concrete mistake would fail this test, and what loss would it cause a user or maintainer?+2. Would an equivalent refactor or a better valid result also fail? Which restrictions are actually contractual?+3. Which existing test, type check or other check already catches this mistake? Does the additional protection justify its execution and maintenance cost?++Prefer observable output, state, data integrity and failure behavior. Private-function tests, snapshots and static checks can also protect real boundaries; their form alone does not determine their value.++## Make the smallest effective testing decision++| Evidence | Decision |+| --- | --- |+| A worthwhile failure boundary is uncovered | Add a regression at the cheapest layer that exposes it; retain a real integration path where needed |+| An existing test already fails for the mistake | Reuse or extend it instead of building a parallel fixture family |+| A test freezes noncontractual implementation or automatic output | Assert outcome properties, justified tolerances or boundaries while preserving explicit constraints |+| Several tests protect the same failure through the same implementation path | Consolidate or remove duplicates and identify the surviving protection |+| A shared rule table is repeated across entrypoints | Cover the rule set through shared logic and verify each entrypoint's integration; retain combinations with interactions or independent implementations |+| A costly test protects a distinct risk | Preserve coverage; improve fixtures or select execution by risk |+| A historical contract has explicitly ended or a capability was removed | Retire obsolete tests after checking for remaining consumers |+| Ownership of protection or the correct expectation is unclear | Retain the test and identify missing evidence rather than guessing to reduce failures |++Adding a test for every edit is not the objective. Pure copy changes, mechanical edits and changes already covered effectively may need no new test. When the user authorizes removing a product restriction, update the tests too; an old assertion does not veto an approved product change.++Preserve effective protection against data loss or corruption, permission and trust-boundary failures, promised compatibility, essential accessibility failures, resource leaks and broken recovery. Simplifying these checks still requires evidence of surviving protection. Bulk skips, retries, wider tolerances or refreshed snapshots must not conceal regressions. Changes to product commitments or mandatory release-platform gates must be within the user's authorized scope.++## Check the test's ability to discriminate++Use evidence proportionate to the risk instead of creating another test suite for every test:++- **Bug fix:** where practical, reproduce the original failure with the regression and verify the fix passes. State the gap if reproduction is unavailable.+- **Relaxed assertion:** try a valid alternative and the original bad result; the former should pass and the latter fail. Temporary fault injection can help for consequential errors; a mutation score is not an end in itself.+- **Consolidation or deletion:** trace actual call paths and establish that surviving tests detect the same mistake. Similar names, a shared helper or overlapping line coverage do not prove duplication.+- **Shared fixtures:** reset mutable state and retain isolation and cleanup assertions between failure attempts. Gains must not depend on test order or accidental cache hits.++Run destructive probes in temporary copies or controlled fixtures, preserving existing user changes. An unavailable environment is a validation gap; simulated evidence cannot stand in for a real browser, operating system or distribution package.++## Control feedback cost++Read the project's actual test commands, CI selection rules and current changes before selecting the smallest set of checks that covers the risk. Affected behavior determines whether integration, browser, platform or complete verification is needed.++Confirm that the intended tests actually executed, including filters, collection and skips. A successful command with no relevant tests is not evidence that the behavior passed. Zero selection can be appropriate for changes with no affected tests, but establish that reason instead of inferring it from a green exit code.++Reuse results whose revision identity, inputs, environment and coverage remain applicable, and disclose what was reused. Expand or repeat verification when a new change, failure or unresolved risk invalidates evidence. Narrow failures for diagnosis instead of repeatedly launching the complete suite.++Claim speedups only from measurements. Distinguish case time, file time, a parallel pipeline's critical path and total compute. Attribute nested log timings correctly: a parent suite's duration is not its final child's duration. Control runtime, platform, inputs, cache state and competing work when comparing measurements.++## Learn from use++When real use reveals a valuable new testing principle or a flaw in this guidance, you may refine this skill in place, within the active environment's permissions and the user's instructions. This is optional maintenance, not a required step in every task; keep it proportionate and preserve the original task's priority.++Before changing the skill, establish:++- **Evidence:** an observed outcome, failure or well-supported counterexample, rather than a plausible slogan. One decisive example can justify a narrow correction; broader claims need broader support.+- **Decision value:** what an agent would decide differently, and why existing guidance does not already cover it.+- **Applicability:** when the principle holds, and a meaningful exception or counterexample. Keep project-specific conventions in project guidance rather than making them universal here.++Prefer revising or consolidating an existing principle to appending another rule. Put cross-cutting principles in this entrypoint and conditional examples in the relevant reference. Keep additions in English, omit private incident details and transient measurements, and preserve authorization and protection boundaries. A lesson does not authorize broader repository changes, publication or synchronization to other installations.++Review the resulting guidance for contradictions and unnecessary obligations; check links and metadata if affected. Exercise a realistic decision scenario when the change alters behavior. If the skill is unavailable or read-only, propose the exact improvement and explain that it was not saved.++Whenever you update the skill, tell the user in the final response: link the changed file, summarize the principle added or revised, and explain the evidence or reason. Distinguish a saved change from a proposal. No update is needed when the existing guidance already explains the lesson.++## Report and stop++Briefly report the protected behavior, test changes and rationale, executed or reused evidence, skips and intentional coverage tradeoffs. Report timing changes only with comparable measurements. Ordinary development does not need an additional governance report, scoring system or CI policy.++For audits, account for investigated candidates as changed, retained or awaiting evidence. A round can end when its high-value candidates are addressed and remaining candidates lack evidence or cost more than they save. The objective is neither endless deletion nor growing process. Keep focused, complete-suite, visual, platform and release acceptance claims distinct.diff --git a/.agents/skills/test-value/agents/openai.yaml b/.agents/skills/test-value/agents/openai.yamlnew file mode 100644index 00000000..7835abcc--- /dev/null+++ b/.agents/skills/test-value/agents/openai.yaml@@ -0,0 +1,6 @@+interface:+ display_name: "Test Value"+ short_description: "Improve test protection, feedback speed and maintenance cost"+ default_prompt: "Use $test-value to assess tests relevant to this task, improve them within the authorized scope, and verify the behavior they retain."+policy:+ allow_implicit_invocation: truediff --git a/.agents/skills/test-value/references/audit.md b/.agents/skills/test-value/references/audit.mdnew file mode 100644index 00000000..0a21b6b8--- /dev/null+++ b/.agents/skills/test-value/references/audit.md@@ -0,0 +1,44 @@+# Auditing Existing Tests++## Map the cost++Confirm the workspace, comparison baseline and uncommitted changes; read test entrypoints and CI configuration. Reuse current logs before collecting measurements that are genuinely missing.++For broad work, group tests by responsibility: core product behavior, shared algorithms, entrypoint integration, browser/platform behavior, filesystem and process safety, distribution/installation, generated artifacts and CI selection. Identify uninspected areas; one successful cut does not establish that the whole project is optimal.++Cost includes execution time, false-alarm investigation, fixture maintenance, blocked refactors, flaky reruns and resource contention. A lack of historical failures does not establish low value: rare data corruption can justify expensive protection.++Choose candidates from measured bottlenecks, frequent false alarms or current development friction. Avoid predetermined deletion ratios, coverage targets or universal time limits. An expensive test outside the daily loop may cost less than hundreds of small duplicates in every feedback cycle.++## Prove the boundary of a cut++For substantial reductions, keep a short, reviewable record:++- **Burden:** measured execution or maintenance cost, or a concrete false alarm.+- **Existing protection:** the actual mistake, entrypoints and implementation paths.+- **Change:** deletion, consolidation, rewritten assertion, fixture reuse or changed execution timing.+- **Surviving evidence:** how remaining tests detect the mistake; combinations intentionally no longer exercised.+- **Verification:** commands and outcomes, comparable timing, baseline failures and untested environments.++Prefer low-cost changes to a new test framework, dynamic dependency graph or layered runner. Selection machinery also creates maintenance obligations; introduce it only when existing tools cannot meet an evidenced need.++## Select execution by risk++Use the repository's risk distribution, not another project's command names or runtime versions.++- **Daily feedback:** core public behavior and affected regressions.+- **Expanded checks:** relevant integration and consumers of shared changes.+- **Platform and delivery checks:** distinct risks in real browsers, operating systems, installation, packaging and release identity.+- **Complete verification:** infrastructure changes, uncertain impact or the project's release requirements.++Before reducing platform matrices, distinguish runtime-compatibility smoke from platform-specific faults. Preserve actual evidence for platform differences. A mock or runner command list demonstrates dispatch, not native path behavior.++When changing affected-test selection, check new files, renames, deletions, shared dependencies and unknown paths. Classification failures must not silently become successful skips. Respect required checks; a request for faster feedback does not authorize changing branch protection or release policy.++## Work in batches++Complete a change and verification for one responsibility boundary before moving to the next. Stabilize unreliable measurements before claiming speedups. Track live process handles; an observation timeout does not justify starting another full run.++Reuse verification unaffected by later changes. When only proven redundant assertions are removed, run surviving behavior checks or reuse applicable results. Reducing test cost should not produce an ever-growing verification ritual.++At the end, identify retained protections, intentionally removed combinations and deferred candidates. Use an existing evidence location when useful rather than automatically creating a new body of governance documentation.diff --git a/.agents/skills/test-value/references/decision-examples.md b/.agents/skills/test-value/references/decision-examples.mdnew file mode 100644index 00000000..f7874293--- /dev/null+++ b/.agents/skills/test-value/references/decision-examples.md@@ -0,0 +1,63 @@+# Decision Examples and Common Traps++These examples generalize observed maintenance problems. They are not mandatory solutions or universal thresholds.++## Automatic output and snapshots++**Situation:** a test demands an exact sequence of automatically chosen route coordinates. A shorter valid route fails it.++Separate user-authored ports, positions and paths from algorithm-selected bends. Automatic choices can usually be checked through connectivity, port direction, obstacle avoidance, readability or bounded work; preserve explicit constraints. Verify the assertion against a valid alternative and the original bad route.++Some snapshots remain valuable. Public serialization, protocol bytes, generated-source consistency and promised deterministic output can require exact comparison. Regenerating golden files establishes consistency, not visual quality.++## Shared rule matrices++**Situation:** 22 icons are each rendered through five entrypoints.++If the entrypoints actually share the drawing function and rules, exercise the complete catalog through one real path and retain default, override, hiding and local special cases at each entrypoint. Check schema, preprocessing and layout branches; retain combinations with distinct handling. Identical parameter names do not justify cutting a cross-product.++The same reasoning applies to locales, providers, codecs and runtime versions: distinguish shared rules from real interactions. Disclose combinations no longer traversed rather than claiming identical coverage.++## Source assertions and architecture rules++**Situation:** a test meant to prevent missing release files only searches source code for filenames.++A stronger check untracks or removes required inputs in a temporary repository and observes explicit rejection without output creation. If behavior protection already exists, remove the source assertion without adding a replacement merely to preserve test count.++Static checks can enforce real architectural or safety constraints, such as preventing database imports in a restricted layer or excluding files from a release package. Check dependency relationships or artifact facts rather than import formatting, private names or incidental call counts.++## Failures and shared mistakes++**Situation:** AI-generated implementation and tests agree, but the business result is wrong.++Establish expectations from user examples, compatibility fixtures or an independent calculation. Copying the production algorithm into expected-value generation does not provide an independent oracle. Identify the observable mistake the regression must catch.++**Situation:** a historical test fails.++Compare with the baseline in the same environment to separate existing failures from regressions. Changed requirements call for updated contracts and assertions; product regressions call for implementation fixes; environment failures call for environment repair and visible reporting. A cumbersome test is not, by itself, a reason to ignore its failure.++## Unstable waits and performance++**Situation:** an asynchronous test fails intermittently and turns green on retry.++Prefer real readiness signals and inspect ownership and cleanup. Distinguish a product race from a test timing assumption. Timeouts should reflect the protected deadline and execution environment: an unreasonable test timeout can be widened, while a contractual product deadline still needs coverage. Quarantine needs a reason, replacement protection and a clear restoration condition; it is not a pass.++**Situation:** sharing a browser page or extracted package reduces setup time.++Check storage, globals, timers, network, files and cleanup for isolation. Start rejection cases from clean inputs. Reuse must not conceal leaks when cleanup is part of the behavior under test. A faster case does not establish a faster parallel pipeline.++## Test doubles and test layers++Cheap, controllable tests suit pure rules and fault injection. Packaged relative paths, filesystem casing, browser layout and real process lifecycles need corresponding environments. Preserve necessary integration paths without sending every rule through the UI or public CLI.++Mocked filesystem success does not establish Windows support; skipped Chrome tests do not establish browser acceptance; generated screenshots do not establish readability. Report these as separate claims.++## Implementation and pre-commit review++**Ordinary bug fix:** find existing coverage and extend it with an input reproducing the user's failure. Avoid expanding the task into a test-system redesign.++**Copy-only change or equivalent internal refactor:** reuse existing protection and run affected checks when needed. Do not manufacture string assertions to give every commit a new test.++**Rare output-loss or permission failure:** low frequency does not mean low value. Improve fixtures and scheduling while preserving assertions that distinguish the actual failure.++**Request for faster feedback:** prefer targeted checks and applicable existing evidence. Shortening the local loop does not remove required release checks or authorize committing, pushing or publishing.diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdindex 003b1258..9248571c 100644--- a/.github/PULL_REQUEST_TEMPLATE.md+++ b/.github/PULL_REQUEST_TEMPLATE.md@@ -6,11 +6,15 @@ Current-base trigger or rationale, intended outcome, why the approach is worth m## Stability impact+<!-- Summarize applicable PR improvement findings or why no improvement was needed; CONTRIBUTING.md#pr-improvement-check defines scope. -->+- Impact class and changed behavior/shared callers: <!-- CONTRIBUTING.md#choose-evidence-by-impact -->- Existing behavior preserved / intended compatibility changes / failure behavior:## Tests run+<!-- For behavior changes, apply project test-value to the affected tests and explain meaningful protection/cost tradeoffs here. -->+Comparison base and candidate head; applicable commands/results or evidence links. Identify reused evidence by its original revision and explain material coverage gaps. Follow CONTRIBUTING.md#choose-evidence-by-impact; required remote CI still applies.## Visual evidencediff --git a/AGENTS.md b/AGENTS.mdindex 4e3d489b..56278812 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -2,6 +2,10 @@Follow [CONTRIBUTING.md](CONTRIBUTING.md) for repository changes and [REVIEWING.md](REVIEWING.md) for reviews.+## PR preparation++Before requesting final review, follow the scoped [PR improvement check](CONTRIBUTING.md#pr-improvement-check) using the project Skills when applicable.+## Test selectionBefore running tests, read [Choose evidence by impact](CONTRIBUTING.md#choose-evidence-by-impact) to select coverage for the changed behavior. Use the [focused test workflow](CONTRIBUTING.md#local-setup-and-verification) for local iteration. Before integration, follow [Final integration and follow-up](CONTRIBUTING.md#final-integration-and-follow-up) to verify CI and reused evidence against the final revision.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 640d5f58..1f7900af 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -27,6 +27,34 @@ Before requesting final review, explain:Use [the PR template](.github/PULL_REQUEST_TEMPLATE.md); link existing receipts or CI output instead of transcribing long logs. Classify impact by behavior and callers, not file extension or diff size.+## PR improvement check++Before requesting final review of a behavior-changing PR, assess the changed+behavior, direct callers, and affected tests with the project Skills:++- [test-value](.agents/skills/test-value/SKILL.md): use its implementation or+ pre-commit review mode to decide which tests to add, adapt, reuse, or retire.+ Protect user outcomes and real failure boundaries at proportionate cost.+- [simplify-codebase](.agents/skills/simplify-codebase/SKILL.md): use Focused+ Survey mode when the diff introduces or touches duplicate logic/state, dead+ paths, redundant layers, or another concrete complexity concern. Trace the+ relevant consumers before recommending a cut.++Keep this check within the PR's changed ownership boundaries. A conclusion of+“no worthwhile improvement” is valid. Pure prose or generated-only refreshes+with no behavior change may skip it; authored Skill instructions and behavioral+build inputs still need assessment. Apply proved improvements within the task's+existing authorization. Report changes that would retire a supported capability+or compatibility contract for maintainer decision.++Summarize useful findings, implemented improvements, or the reason for skipping+in the PR's existing problem/impact and test sections. Reuse applicable evidence+under [Choose evidence by impact](#choose-evidence-by-impact); this check adds no+separate audit report or CI gate. Repository instructions govern scope and+publication authority. Treat the two vendored Skills as read-only guidance in+ordinary PRs; update their pinned sources through a dedicated reviewed change.+See [Skill sources](.agents/skills/README.md) for provenance and update procedure.+## Choose evidence by impact| Impact | Typical change | Evidence to prepare |