opencode-skills-collection 4.1.1 → 4.1.3

package/bundled-skills/repo-foundation/references/evolution.md

@@ -0,0 +1,60 @@
+# Evolution: adapting architecture and contracts
+
+Use this reference when a task alters core contracts, architectural boundaries, or domain ownership, or when working in a repository with conflicting conventions.
+
+---
+
+## 1. Intentional contract changes vs. regressions
+
+When requirements evolve, contracts must adapt. Tell intent apart from regression: an intentional change alters public API signatures, schemas, data models, or error codes because the user explicitly asked for new behavior. A regression is an unintended break in existing functionality.
+Accept what the user requested. Don't fight explicit requests by forcing compatibility with deprecated behavior. Foundation and refactor work both accommodate authorized changes while preserving untouched contracts.
+
+---
+
+## 2. Blast radius assessment
+
+Before mutating shared contracts, determine the blast radius:
+
+1. **Identify callers and consumers:** Locate all internal modules, external consumers, database schemas, message queues, or serialized data structures affected by the change.
+2. **Boundary scope:** Confirm whether the change can be completed within the authorized scope or if it requires updating multiple subsystem boundaries.
+3. When all callers reside within the codebase and are under the current task's scope, update the contract, callers, and tests together (the atomic update). When consumers are external, persisted data must be migrated, or callers span multiple independent services, maintain a compatibility bridge, migration script, or dual-read/write strategy as requested (the transitional migration).
+
+---
+
+## 3. Controlled migration workflow
+
+Execute architectural adjustments in logical order:
+
+1. **Update contract definitions:** Modify the authoritative interfaces, schemas, or type definitions first.
+2. **Migrate callers:** Update calling code, dependency injection bindings, and data transformations to use the new contract.
+3. **Align tests:** Update existing tests that assert the old contract so they verify the new behavior. Add tests covering edge cases and error semantics of the new contract.
+4. **Synchronize documentation:** Update repository instructions, schema definitions, and API documentation to prevent stale instructions from misleading future agents.
+
+---
+
+## 4. Reconciling conflicting repository conventions
+
+In mature repositories, different modules often reflect different architectural eras or styles:
+
+When patterns conflict, resolve using evidence hierarchy in order:
+  1. User's explicit instruction for the current task.
+  2. Documented architecture and repository instructions.
+  3. Preserved public contracts and persisted schemas.
+  4. Healthy sibling code within the *same* owning domain and runtime boundary.
+  5. Relevant tests, schemas, callers, and dependencies.
+  6. Local module conventions.
+Do not rewrite healthy sibling code in another module merely to match your current change. Preserve legitimate domain-specific differences unless codebase-wide unification is explicitly requested; premature homogenization helps no one.
+If existing code contains obvious workarounds or defects, do not replicate them in new code. Follow the healthiest precedent within the domain: defects never become precedent.
+
+---
+
+## 5. Multi-pressure checklist
+
+When migration, risk, docs, and workspace pressures stack (the usual evolution mess),
+work in this order and do not skip steps:
+
+1. Baseline: record revision, failing checks, and uncommitted user work.
+2. Protect user work: distinct-region edits only; stop on real collision.
+3. Reconcile docs against code reality before mutating (code describes behavior, docs get fixed after).
+4. Highest-risk caller first with maximum conservatism; atomic path for the rest.
+5. Rerun affected checks on the final tree; report what remains red and why.

package/bundled-skills/repo-foundation/references/migration-examples.md

@@ -0,0 +1,53 @@
+# Migration Examples (atomic vs transitional)
+
+Read in Evolve mode when changing a public contract or persisted schema.
+
+## Atomic replacement (preferred for single-node file state)
+
+```python
+import os
+import tempfile
+from pathlib import Path
+
+def replace_file(dest: Path, new_bytes: bytes) -> None:
+    tmp = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb",
+            dir=dest.parent,
+            prefix=f".{dest.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as file:
+            tmp = Path(file.name)
+            file.write(new_bytes)
+            file.flush()
+            os.fsync(file.fileno())
+
+        os.replace(tmp, dest)
+    finally:
+        if tmp is not None:
+            tmp.unlink(missing_ok=True)
+```
+
+Invariants: validate inputs + destination ownership before mutation; retain last valid
+state until replacement succeeds. Stage on the destination filesystem with a unique
+temporary name; close the file before replacement and clean up the temporary file on
+success or failure. Verify successful replacement and preservation of the old state
+when writing, syncing, or replacement fails.
+This example addresses ordinary I/O failures. Power-loss durability and recovery after
+forced termination require platform-specific guarantees and separate verification.
+
+## Transitional compatibility (multi-caller migration)
+
+Bad: change producer to `Decimal("5.00")` while callers expect `int 5` → hidden breakage.
+Good:
+1. Keep old readers working (accept `int | str | Decimal`, normalize internally).
+2. Migrate callers one by one while preserving compatibility for remaining consumers.
+3. Add contract and caller tests covering both surfaces during transition.
+4. Remove compat shim only after all callers + docs updated.
+
+## Docs sync checklist
+
+- Update `README.md` + CLI help in the same diff as the contract change.
+- Document only behavior implemented and verified in the delivered code state.

package/bundled-skills/repo-foundation/references/shared-contracts.md

@@ -0,0 +1,48 @@
+# Shared contracts
+
+These rules apply to repository development and review.
+
+## 1. Strict contract adherence (canonical wording)
+
+Preserve documented or demonstrably consumed public contracts across public interfaces,
+exported parameters, module constants, return types, errors, and serialization.
+
+- A requested behavior change may authorize a contract change only when that consequence
+  is clear from the task or from an authorized evolution. Then update affected callers,
+  tests, and living documentation within scope.
+- Otherwise preserve exact declared types. For example, never substitute or wrap an exposed
+  primitive `str` path contract with `pathlib.Path` or custom wrapper objects merely for
+  internal convenience or preference.
+- Internal intermediate representations may use appropriate helpers, provided all exposed
+  public contracts and types remain exact.
+
+## 2. Evidence hierarchy (canonical order)
+
+Use to guide investigation, not to auto-resolve material contradictions:
+
+1. User requirements and explicitly authorized scope.
+2. Documented architecture and repository guidelines.
+3. Observable public contracts and persisted schemas.
+4. Healthy sibling code within the same domain and runtime boundary.
+5. Relevant tests, schemas, callers, and dependencies.
+6. Dominant local conventions.
+7. Language and runtime idioms.
+8. Conservative, idiomatic defaults.
+
+Never treat a temporary workaround, buggy sibling, or accidental pattern as precedent.
+Never rewrite history or rubber-stamp code with stale notes. Reconcile before mutating
+the affected contract.
+
+## 3. Verification final-state rule (canonical)
+
+- Record baseline failures as: (1) pre-existing outside scope, (2) in-scope to fix,
+  (3) regressions from current changes, (4) environment errors.
+- Verify the final code state. Never use pre-cleanup results to certify modified code.
+- Never claim a check ran when it did not. Distinguish verified behavior,
+  inspection-only conclusions, and unverified assumptions.
+
+## 4. Shared judgment tests (canonical)
+
+Two questions that both skills use when the text alone under-determines the answer.
+
+A pattern counts as healthy precedent only if three things hold: code outside its original author consumes it, it does not contradict docs or contracts, and you would copy it into a new domain without apology. Popularity proves nothing; a workaround with tests and docs still fails. When two domains overlap, the owner is whoever owns the failure (who gets paged, who fixes the bug, whose reason to change fires first). Consolidate toward that owner, or leave both alone.

package/bundled-skills/repo-foundation/references/verification.md

@@ -0,0 +1,50 @@
+# Verification: testing in proportion to risk
+
+Use this reference when designing checks for greenfield projects, high-risk boundaries (auth, data loss, concurrency, migrations), or weak test suites.
+
+---
+
+## 1. Baseline failures and scope
+
+Before or during initial execution, record baseline test failures and sort them:
+
+1. Failures outside the current task's scope count as pre-existing. You don't need them green before starting, and don't fix unrelated ones just to green the baseline.
+2. Failures inside the task's scope are in scope, such as a bugfix that starts with a failing test or repro script, and these are yours to resolve.
+3. Regressions are previously passing checks your changes broke. Catch and fix them before declaring completion.
+4. When checks can't run because of missing tools, dependencies, or setup, treat them as environment and tooling failures. Report them as environment limits, not code defects.
+
+---
+
+## 2. Picking checks by risk
+
+Match checks to the contract, boundary, and failure consequences. Don't mandate unit plus integration tests for every small helper, or unrelated checks (rollback tests for an auth change):
+
+- Mechanical or local changes include typos, formatting, localized helper refactoring, and other non-semantic edits within established boundaries. For those, run stack linters, formatters, and localized unit tests.
+- Contract and boundary changes modify public APIs, data formats, state machines, or subsystem contracts, so run tests that directly verify the updated contract and its callers.
+- Changes touching authorization, permission checks, data migrations, cryptographic routines, concurrency locks, transaction boundaries, or destructive persistence carry high risk even when they touch only a single line, which calls for critical boundary vigilance. Verify the specific critical behavior (e.g., testing both authorized and unauthorized paths for auth changes; testing schema validity and rollback for migration scripts).
+
+---
+
+## 3. Greenfield and acceptance checks
+
+When building new features or starting a repository from scratch:
+
+- Keep environment checks separate from acceptance checks:
+  - *Environment / pre-existing checks:* toolchain, package manager, and build environment must work. These pass before feature work starts.
+  - *Acceptance checks for new capabilities:* the expected observable behavior of the new feature.
+- For pre-build test states:
+  - An acceptance check for an unbuilt feature should detect the missing behavior when run in a valid environment.
+  - Tell apart a meaningful behavioral failure (endpoint 404s, CLI says unknown command, feature returns null) from an unrunnable test (syntax error, broken import, missing binary).
+  - Do not inject bugs, syntax errors, or failing stubs into test code just to force a failure.
+- After implementing, acceptance checks must pass cleanly on the final code state. That is the evidence of completion.
+
+---
+
+## 4. Testing integrity and final state
+
+- For defect fixes, reproduce the failure first with a minimal reproduction such as a failing test, repro script, or observed command output, because a fix verified only after the fact is a guess with good lighting. For regression tests, prove red-green by reverting the fix, watching it fail, restoring it, and watching it pass.
+- Check the external consequence of the action to assert observable outcomes, such as HTTP status code and body, database row contents, exit code and stdout/stderr, or rendered DOM elements.
+- Expected values must reflect business requirements to keep outcomes independent, not mirror internal implementation logic.
+- Never weaken tests to achieve a passing run by weakening assertion thresholds, deleting valid assertions, or skipping tests.
+- Always verify the final tree by executing verification commands on the actual code state intended for delivery. If a subsequent refactoring pass or companion skill modifies code, rerun all affected checks on the updated code.
+- Report actual results by stating exactly which commands were run, their outcomes, and any unverified areas.

package/bundled-skills/repo-native-refactor/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: repo-native-refactor
+description: "Review diffs without editing, or perform evidence-based cleanup while preserving authorized behavior, public contracts, and domain ownership."
+category: development
+risk: critical
+source: https://github.com/Natchannnn/repository-engineering-skills
+source_repo: Natchannnn/repository-engineering-skills
+source_type: community
+date_added: "2026-09-30"
+author: Natchannnn
+tags: [repository-engineering, code-review, refactoring, public-contracts]
+tools: [codex]
+license: MIT
+license_source: https://github.com/Natchannnn/repository-engineering-skills/blob/e55b378158d5134a77af3b8dace4a2a1b17e41e2/LICENSE
+metadata:
+  version: "0.3.0"
+  license: "MIT"
+---
+
+# Repo-native refactor
+
+## When to Use
+
+- Use when the user asks to review a diff, branch, or PR for correctness, contract breaks, or operational risk.
+- Use when the user authorizes bounded cleanup before opening a PR or asks to consolidate duplicated policy with shared ownership.
+- Use for repository rehabilitation only when the user explicitly requests work across multiple domains.
+- Establish review-only, edit, or combined authority before choosing the operating mode.
+
+Produce the smallest coherent change that belongs naturally in the target repository.
+
+Prioritize in order:
+1. **Correctness and security:** prevent regressions, avoid new security vulnerabilities, handle boundary conditions.
+2. **Semantic integrity:** preserve existing invariants, state transitions, validation, and error boundaries.
+3. **Contracts stay as declared:** the rule lives in `references/shared-contracts.md` §1. Preserve the authorized target contract; otherwise keep exact declared types. Internal helpers are fine when exposed contracts stay exact.
+4. **Repository conformity:** match surrounding naming, domain conventions, and architectural precedents.
+5. **Economy and simplicity:** minimal intervention. Delete dead weight, avoid premature abstractions.
+
+This is a post-implementation audit and small cleanup skill. It is not permission to redesign the repository. Establish a concrete consequence such as inconsistent behavior, duplicated policy that must change together, unclear ownership, avoidable resource cost, or a demonstrated maintenance obstacle. Leave healthy code unchanged when the benefit is speculative.
+
+---
+
+## Minimal intervention and evidence gate
+
+- **Evidence-based intervention:** refactor only with concrete evidence of divergence, defect, or operational risk. If greenfield code or an additive diff is already minimal, idiomatic, and passing, leave it. A pattern you recognize is a candidate finding, not a reason to change anything.
+- **Semantic DRY (Cost-benefit consolidation):** merge duplicated logic only when the copies share an owner, an invariant, and a reason to change, and only if merging saves more than it costs. Leave similar-looking checks in separate domains alone, and keep small local duplication when merging would obscure ownership.
+- **Contract boundary protection:** preserve public interfaces, parameter names, and return types, except where the task clearly authorizes the change. During cleanup, keep the authorized target contract; don't revert to the old one.
+
+---
+
+## Operating modes
+
+- **Review vs. Refactor Authority:** first establish the outcome: findings, edits, or both. Review-only means inspection and verification, no source edits. Authorized cleanup allows bounded corrections; don't ask approval again for routine choices.
+- **Change-set cleanup:** for a working tree, branch, commit range, feature, or bounded checkpoint. Work diff-first; read surrounding code only to understand ownership, contracts, and precedent.
+- **Repository rehabilitation:** only when explicitly requested across multiple domains. Read [repository rehabilitation](references/repository-rehabilitation.md), build a short profile, and work in batches you can verify independently.
+
+---
+
+## Evidence hierarchy
+
+Use the evidence hierarchy to guide investigation, not to resolve material contradictions automatically. Reconcile conflicting requirements, documentation, callers, and tests before changing the affected contract. When repository patterns conflict, resolve in order:
+1. User requirements and explicitly authorized scope.
+2. Documented architecture and repository guidelines.
+3. Observable public contracts and persisted schemas.
+4. Healthy sibling code within the same domain and runtime boundary.
+5. Relevant tests, schemas, callers, and dependencies.
+6. Dominant local conventions.
+7. Language and runtime idioms.
+8. Conservative, idiomatic defaults.
+
+Never treat a temporary workaround, buggy sibling, or accidental pattern as precedent.
+
+---
+
+## Workflow
+
+### 1. Establish scope and baseline
+Before mutating code, identify:
+- Comparison base and working-tree state.
+- In-scope files vs. untouched user modifications.
+- Existing verification commands and their current pass/fail status.
+
+Differentiate pre-existing failures from regressions introduced by this pass. Never claim a check ran when it did not.
+
+### 2. Establish intent, ownership, and preservation
+Refactoring is behavior-preserving by default. Protect:
+- Public APIs, serializations, and database schemas.
+- Concurrency guarantees, idempotency, timeouts, and retries.
+- Resource lifecycles (file handles, sockets, database transactions).
+
+If a bug requires an observable change, classify and report it as an intentional behavioral correction rather than routine cleanup.
+
+### 3. Inventory findings before rewriting
+Inspect the authorized scope for:
+- Validation or control flow whose structure obscures an invariant, creates inconsistent behavior, or duplicates the same owned policy.
+- Misplaced domain ownership or leaky abstractions.
+- Leaked unmanaged resources or missing atomic flush/sync calls.
+- Unnecessary boilerplate, dead code, or commentary narrating syntax.
+
+Read [finding taxonomy](references/finding-taxonomy.md) for complex cases. Establish the smallest adequate correction before editing.
+
+### 4. Classify risk and refactor
+Risk bands:
+- **R0 - Mechanical:** Established formatter or locally provable cleanup.
+- **R1 - Low Structural:** Local residue with straightforward test verification.
+- **R2 - Contextual Structural:** Renames, control-flow changes, extraction of shared predicates.
+- **R3 - Semantic:** Errors, fallbacks, retries, serialization, transactions, async, or lifecycles.
+- **R4 - Critical Boundary:** Auth, permissions, crypto, data migrations, persistence durability.
+
+Read [semantic risk](references/semantic-risk.md) for R2+ changes. Never mass-rewrite R3 or R4 behavior without explicit instructions and verified tests.
+
+### 5. Audit code prose
+- When prose is in scope, treat comments, docstrings, CLI output, and error messages as distinct surfaces. Read [repository prose](references/repository-prose.md) for that work.
+- Delete comments that merely narrate obvious syntax or execution order.
+- Preserve and tighten comments that explain non-obvious invariants, protocol quirks, rounding, or hardware workarounds.
+- Never invent fictitious tickets, PR references, or production incident IDs.
+
+### 6. Verify and review
+- Run the smallest repository-native checks that meaningfully exercise the change. For R3/R4 changes or weak test suites, read [error and reliability boundaries](references/error-reliability.md) and [testing integrity](references/testing-integrity.md).
+- Prioritize diff reviewability and coherence over raw line minimization; do not compress code into unreadable one-liners.
+- Distinguish intentional behavioral corrections from mechanical cleanup.
+- Review the final diff like a skeptical maintainer. Every line needs a reason. No contract changed without permission, no test got weaker, no dependency moved for nothing.
+
+---
+
+## Reference routing
+
+Read supporting references only when the corresponding trigger occurs:
+
+- **[references/shared-contracts.md](references/shared-contracts.md):** Canonical contract + evidence hierarchy. Read when touching any public interface or reconciling conflicts.
+- **[references/refactor-examples.md](references/refactor-examples.md):** R0–R4 good/bad diffs. Read before rewriting a candidate finding.
+- **[references/finding-taxonomy.md](references/finding-taxonomy.md):** Read for complex multi-smell diffs to name owner + consequence.
+- **[references/semantic-risk.md](references/semantic-risk.md):** Read for R2+ changes, justification gate, and stop conditions.
+- **[references/repository-prose.md](references/repository-prose.md):** Read when editing comments, docstrings, CLI output, or error messages.
+- **[references/error-reliability.md](references/error-reliability.md) + [references/testing-integrity.md](references/testing-integrity.md):** Read for R3/R4 or weak test suites.
+- **[references/deterministic-tooling.md](references/deterministic-tooling.md):** Read before introducing new scanners or bulk-codemod tools.
+- **[references/repository-rehabilitation.md](references/repository-rehabilitation.md):** Read only for explicitly requested multi-domain rehabilitation, in verifiable batches.
+
+---
+
+## Hard stops
+
+Do not force a refactor where intent, ownership, public-contract consequences, migration semantics, or concurrency behavior cannot be established. Do not guess between conflicting architectural patterns without evidence.
+
+---
+
+## Completion Report
+
+Scale the completion report to the change. Omit empty sections. Format completion concisely:
+
+### Result
+Use one: **Verified**, **Verified with caveats**, **Needs review**, or **Failed verification**.
+
+For review-only requests, an empty findings list is a complete result, not an
+embarrassing one. Never manufacture findings to fill a report: each reported
+finding needs a producer, a consumer, and an observed consequence, or it is
+not reported.
+
+### Changed
+Summarize material corrections by file and function.
+
+### Preserved intentionally
+Note specific patterns or contracts deliberately retained to avoid breaking downstream consumers.
+
+### Verification
+List exact verification commands executed and their outcomes.
+
+### Residual uncertainty
+Document unresolved limitations or high-risk boundaries intentionally deferred.
+
+---
+
+## Examples
+
+### Review without editing
+
+```text
+Use repo-native-refactor to review this branch against main for public-contract
+breaks and retry failures. Do not edit source files. Report only findings with
+a concrete producer, consumer, and observable consequence.
+```
+
+Inspect the comparison base and relevant callers, run proportionate verification,
+and report evidence-backed findings. An empty findings list is a valid result.
+
+### Consolidate one owned policy
+
+```text
+Use repo-native-refactor to consolidate the duplicated eligibility checks owned
+by this billing module. Preserve the current accepted inputs, error types, and
+return values. Leave similar checks in other domains alone and run the module's tests.
+```
+
+Confirm that the copies share an owner, invariant, and reason to change before
+extracting anything. Keep the correction bounded and verify the final behavior.
+
+## Limitations
+
+- Review requires an identifiable comparison base and enough repository evidence to establish contracts and ownership.
+- Similar syntax alone does not establish shared policy or justify consolidation.
+- The skill cannot establish migration or concurrency safety without relevant requirements and verification; unresolved material uncertainty is a hard stop.
+- Local checks and self-review do not establish independent review or universal reliability.
+
+## Security & Safety Notes
+
+Review-only mode permits inspection and verification without source edits. The
+authorized cleanup mode can modify source files, so the declared risk is `critical`
+under this collection's state-modification classification. Keep edits within the
+user's authorized scope, preserve unrelated user changes, and apply the R3/R4
+verification and stop conditions before changing sensitive behavior. Cleanup
+authority does not authorize publishing, deploying, or changing external systems.
+
+---
+
+## When NOT to Use
+
+- **Clean greenfield code:** Do not refactor newly written code that is already minimal, idiomatic, and passing all tests.
+- **Speculative cleanup:** If you cannot state the domain owner and the concrete maintenance consequence in a single sentence, leave the code unmodified.
+- **Risk classification:** When uncertain between risk bands (such as R2 structural vs. R3 semantic), default conservatively to the higher risk band and require explicit justification.
+
+
+## Source & License
+
+Adapted from [Natchannnn/repository-engineering-skills](https://github.com/Natchannnn/repository-engineering-skills/tree/e55b378158d5134a77af3b8dace4a2a1b17e41e2).
+The original MIT copyright notice and license are retained in [references/LICENSE.md](references/LICENSE.md).
+Collection adaptations add metadata, explicit triggers, interaction examples, limitations, and safety notes; the core workflow and supporting reference instructions are retained.

package/bundled-skills/repo-native-refactor/references/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Natchannnn
+
+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.

package/bundled-skills/repo-native-refactor/references/deterministic-tooling.md

@@ -0,0 +1,101 @@
+# Deterministic tooling policy
+
+Use deterministic tools for problems they can reliably establish.
+
+Examples:
+
+- formatter;
+- compiler;
+- type checker;
+- linter;
+- dependency graph analysis;
+- dead-code analysis;
+- security scanning;
+- AST/CST structural matching.
+
+Tool output is evidence, not architectural authority.
+
+## Project tools first
+
+Prefer tools already configured by the repository.
+
+Do not install a new slop scanner or refactoring dependency merely because this skill mentions one.
+
+Use repository configuration when available.
+
+## Structural search and rewrite
+
+AST/CST tools are strong for locating syntactic patterns.
+
+They do not prove semantic equivalence.
+
+Regex and text search may locate prose candidates such as step narration, repeated docstrings, or section banners. They cannot determine whether a comment carries a contract, historical constraint, or operational rationale. Never auto-delete or rewrite prose solely from a phrase match, comment-density target, or AI-detector score.
+
+`ast-grep` can display or interactively apply rewrites, while `--update-all/-U` accepts every matching rewrite without confirmation. Therefore unattended bulk application is appropriate only for transformations already classified as mechanically safe.
+
+Do not bulk-rewrite:
+
+- exception ownership;
+- fallback behavior;
+- retry;
+- authorization;
+- transaction semantics;
+- unresolved type mismatches;
+- async error behavior.
+
+## Dead-code and dependency analysis
+
+Unused-code tools build a model of repository reachability.
+
+A reported unused file/export/dependency may reflect:
+
+- missing entry points;
+- dynamic imports;
+- plugin registration;
+- generated files;
+- incomplete framework integration;
+- analyzer configuration gaps.
+
+Knip documentation explicitly describes these situations and recommends correcting module-graph/configuration understanding rather than blindly suppressing or deleting findings.
+
+Before deletion:
+
+1. determine why the analyzer considers the item unreachable;
+2. check framework/runtime discovery;
+3. check generated references;
+4. verify entry/plugin configuration;
+5. delete only when semantic ownership confirms it is dead.
+
+## Suppression policy
+
+Do not respond to surprising findings by immediately adding ignores or suppression.
+
+First determine whether:
+
+- the code is actually dead;
+- analyzer configuration is incomplete;
+- the tool does not model the framework behavior.
+
+Suppression should document a known limitation, not hide unexplained evidence.
+
+## Tool confidence
+
+Classify findings:
+
+**Confirmed:** tool result plus repository evidence agree.
+
+**Probable:** tool result plausible but not fully established.
+
+**Uncertain:** analyzer limitations or runtime behavior may invalidate it.
+
+When two repository tools disagree, the dynamic-entry check (imports, plugin
+registration, generated references, entry configuration) wins over static
+reachability claims. A scanner cannot declare dead what the runtime can load.
+
+Only confirmed findings should drive destructive automated changes.
+
+## Prose diagnostics
+
+Use deterministic prose scans only to build an inspection queue. A useful diagnostic reports location and pattern without asserting authorship or defect status.
+
+Do not install an AI detector or generic slop scanner merely to approve a refactor. If such a tool already exists in repository workflow, treat its output as a secondary signal and require repository evidence before mutation.