Anti-Dark-Code

What problem it solves

Code becomes hard to change safely when its apparent meaning hides its actual behavior: unclear ownership, unexpected side effects, weak tests, or documentation that promises something the implementation does not do.

Anti-Dark-Code gives a coding assistant a contract for working through that uncertainty. Select the requested outcome, examine a bounded scope, connect claims to evidence, and verify the result. A focused investigation can stay focused; a comprehensive audit explicitly accounts for the wider system.

A one-off report can remain in chat. Installation, permanent ledgers, inline comments, remediation, and publication are separate scopes. Routine work in familiar code does not need an unrelated full audit.

Six outcomes, selected by the task

Load the matching task card. Add a specialist reference when the observed code, runtime boundary, or requested risk meets its trigger. Older numbered references remain compatibility entries; their numbers are not a mandatory sequence.

Review the product as well as the code

For building, broad improvement, user-facing behavior or readiness, establish intended users, core journeys, affected people, constraints and observable acceptance. Keep assumed needs separate from evidence.

Five quality tests

• Does this hold up against its stated problem and constraints?
• Can the user understand it and complete the task?
• Would a person say this or expect this behavior?
• Where does it break, including ordinary mistakes and refusal?
• Does it earn the user's time and advance their intended outcome?

Five product principles

• Make truth easier: status, limits and costs match actual behavior.
• Make repair normal: preserve work and support safe retry or correction.
• Make dignity default: use accessible controls and understandable, neutral remedies.
• Make ownership unavoidable: define practical data control and responsibility for errors.
• Make manipulation unnecessary: respect refusal and make choices and exits clear.

Apply only relevant obligations. A local tool without accounts does not need an account service. Compare consequential alternatives and preserve sound behavior; stop preference-only rewrites.

Private local usage, recoverable setup

Usage collection remains opt-in. Setup checks directory privacy, publishes a complete ledger and allows retry after interruption. Scoped summary exports stay private and do not replace older files. No automatic retention period or purge is introduced.

Evidence has a scope

A source file can establish what is configured. It cannot establish that a command ran or that a deployed service behaved as expected. Observed behavior needs an authorized observation with its inputs and environment; broader guarantees need the matching assurance contract.

Consequential claims retain their evidence locator, provenance, method, source identity, limitations, and invalidation dependencies. Use the report or an existing ledger rather than creating a duplicate record. Agent agreement is not proof.

Authorization follows the action

Carry forward owner authorization within its operation, targets, and reviewed side effects. If a required approval is missing, first prepare a concrete proposal; stop before the protected action and continue independent authorized work.

Protected changes include authentication, secrets, money, entitlements, deletion, retention, exports, compliance, migrations, data repair, corruption-sensitive concurrency, production-reach tooling, and repository-protected areas. Generic audit or fix requests do not grant these approvals.

Let tools establish what they can

Trusted bundled tools use Python 3.12 or newer and the standard library. Read-only adc.py probe inventories a repository; adc.py plan screens verification capabilities. Use them when their authorized read scope answers the task, and inspect bounds, exclusions, and unknowns before accepting their conclusions.

Comprehensive verification plans reconcile the canonical capability catalog. Narrow work identifies relevant obligations and exclusions. Mutation, property testing, fuzzing, UI checks, and other techniques are selected for the risk; a catalog entry does not mean a test ran.

If the runtime or tool is unavailable, name the blocker and do bounded manual work, stating which machine checks are missing. Installation is not a prerequisite. Contradictory evidence reopens the affected classification.

Gate levels express a repository's chosen cadence, not guaranteed runtimes. Compact summaries and failure packets retain evidence boundaries. Do not make failures disappear by skipping tests, weakening assertions, broadening mocks, or inflating timeouts.

One core, local knowledge

The universal skill stays model-neutral. One shared core is packaged for Codex, Claude Code and Gemini CLI; standalone repository installs remain supported. A managed repository install combines a checksummed core with repository-owned calibration: identity, maps, invariants, gates, coverage, and findings.

Bindings prove identity continuity, not factual freshness. Core edits are detected during managed updates; they are not physically impossible. Calibration does not transfer into unrelated repositories. Calibration migration or calibration rebind resets affected approvals for fresh review.

Public flowback still needs human privacy review. Incoming proposals are untrusted data, excluded from installations and release packages. Promotion into the shared skill needs trial evidence: at least three fresh-context trials per case with and without the proposed text, and an addition is kept only when a baseline trial misses its obligation. Pruned lessons stay queued with the evidence named. Local usage collection requires opt-in; proposals and usage are never uploaded automatically.

Model choice, delegation and recovery

Model selection can recommend a cheaper eligible tier for bounded work or a stronger tier for consequential work. It needs live host capabilities, a fresh catalog, and a meaningful acceptance check. Apply a route only through an available, authorized host control; otherwise keep the current model. Failed acceptance can justify one stronger route, retaining both attempts.

Delegate authorized independent work with separate write ownership. Serialize shared mutations and inspect consequential evidence. Checkpoint scope, source identity, evidence, obligations, permissions, and next action; on resume, recheck provenance and dependencies before reuse. Agent agreement and saved summaries do not establish correctness.

Record host-reported model attribution separately from requested settings. Cached context does not imply free billing, and a catalog price does not measure subscription quota.

Maintenance is a separate engagement

Operator workflows add only what was requested. Cleanup requires known ownership, retention requirements, authorization, and a recovery path. Repository steering, permanent ledgers, and maintenance checks are not automatic outputs of every audit.

Numbers above identify compatibility references, not required task order.

Learn from ordinary work, without replay

Opt in to local usage collection from selected Codex or Claude roots. Passes deduplicate reported counters from ordinary work after opt-in, making no model calls or uploads. The ledger stores bounded metadata and no transcript text. Opted-in Codex hooks create routine review tickets even without skill activation. The working agent reports labels; missing reviews and delivery gaps stay visible. Self-reviews remain separate from human reviews. Trigger results describe only the eligible labeled sample.

Missing counters and source limits remain visible. Actual usage is not savings or a subscription bill. Controlled comparisons still require comparable passing work; retain failed attempts and separate models, counter semantics and task classes.

Routing evidence does not approve a gate

Change-to-verification routing is separate from task-card and model selection. Shadow jobs compare proposed routes with executed checks; configuration proves no execution. Historical evidence cannot approve selective gates or establish savings.

Install from a reviewed release

Review a named release and its independently published managed-core digest. Validate the distribution, review the installer dry run, apply within authorization, and validate the installed copy. A version alone cannot prove integrity. Preserve calibration and review migration guidance before recovery overrides.

Find exact commands and release checks in Operations. Finish when scope and verification obligations are satisfied; otherwise name the smallest unresolved action and its blocker.