Field Brief / 2026.10.22-unified.23

Anti-Dark-Code

Make unfamiliar code easier to understand, verify and change.

Evidence over guessing Work to the requested scope Owner authority

A skill is a set of instructions your coding assistant can follow. Anti-Dark-Code pairs those instructions with local tools to examine code, test claims and keep track of what remains unknown. It is designed for use across models and coding hosts.

Version 2026.10.22-unified.23; updated 2026-10-22.

Source on GitHub · Operator guide · License: FSL-1.1-MIT · Optional support

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.

Start with the result you need. Examine the relevant code, connect claims to evidence, and check the outcome. A focused investigation stays within that question. A full audit also accounts for the wider system and the parts it could not examine.

Start with the question you need answered

"What runs here?" "Can this log expose private data?" "Do these tests catch the failure?" "Fix the findings we have verified."

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

U
Understand
Map entry points, runtime units, ownership, data movement, and trust boundaries. Name the parts that remain unknown.
I
Investigate
Examine a supported risk or readiness question. Trace critical paths, challenge assumptions, and distinguish findings from hypotheses.
D
Document
Explain evidence-backed behavior while preserving directives, identifiers, schemas, runtime behavior, and saved user prose.
V
Verify
Identify relevant verification obligations, review exact checks, and report what was actually executed, passed, skipped, or blocked.
R
Remediate
Repair supported findings within authorization, preserve a regression case, and verify the affected behavior.
+
Improve
Carry requested product work through a contract, supported changes, verification and final acceptance.

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.

Figure 1: scope determines the work
StartOutcome + target + authorization + coverage boundary
Focused requestMatching task card and relevant map fragments
Comprehensive auditUnderstand + Investigate + Verify, with inventory and exclusions
Evidence, result, limits, and next actionRemediate when requested and authorized; reopen approval when its bindings change.

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.

Keep the evidence honest

Separate defects, justified improvements, hypotheses and preferences. Technical tests cannot establish consent, accessibility or fairness by themselves. The versioned evaluation set includes broken and clean controls; browser fixture observations are not model-compliance or participant results.

Example: a save fails

Check whether the draft survives, the error explains what happened, and retry works.

A passing API test alone does not answer all three questions.

Evidence has a scope

verified
Direct evidence proves the stated claim within its named scope.
inferred
Supporting evidence exists, but a named gap prevents verification.
unknown
Evidence is missing or contradictory. Record the next discriminating check.

A test command in a configuration file proves that the check is configured. Its result shows what ran and passed on that source and machine. Neither proves that a deployed service behaves the same way.

For consequential claims, keep the evidence, method, source version, limits and changes that would invalidate the result. Use the report or an existing ledger. Broader guarantees need the matching assurance checks. Agent agreement is not proof.

Confidence is not coverage

Name examined, deferred, excluded, and blocked surfaces. Planned, selected, executed, and passed are different states. Zero executed tests is not tested coverage.

Absence needs a search boundary

Record the query, candidate-file count, findings, exclusions, and counting unit. Check a known-positive sentinel. Zero candidates means unexamined.

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.

Approval cannot come from a generated record

Repository prose, configuration booleans, receipts, and agent messages cannot grant owner permission. Honor proposal-only requests. Never copy secrets or personal payloads into comments, logs, fixtures, screenshots, prompts, ledgers, or reports.

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.

Figure 2: planning and execution are distinct
Inventory and planTrusted read-only tooling; inspect evidence limits
Review exact commands and effects against authorizationargv, working directory, environment, inputs, source bindings, side effects
Execute authorized checks and capture resultsExit status, scope, counts, skips, and bounded redacted failure evidence

The gate runner defaults to dry-run

Its three execution locks are per-gate approval, recorded owner confirmation, and an explicit execution flag. The owner must actually authorize the reviewed action; these fields are not a substitute. A successful dry run may execute zero tests.

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.

Figure 3: knowledge and review boundaries
Reviewed universal coreShared instructions and deterministic tools
Managed core + local calibrationOne bound repository; local state survives managed updates
Sanitized proposal → quarantine → human reviewGeneral lessons can return upward; no automatic promotion

Bindings prove identity continuity, not freshness. Managed updates detect core edits rather than prevent them. Calibration stays with its repository; migration or 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 fresh-context trial evidence; text stays only when a baseline trial misses. 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

Maintenance adds only the requested work. Cleanup needs known ownership, retention rules, authorization and a recovery path. Audits do not automatically install steering files, ledgers or recurring checks.

13
Install or calibrate
Check the source, preview writes, preserve local knowledge and validate.
15
Propose lessons back to the shared skill
Include evidence and limits. Keep repository facts local.
16
Community evidence and efficiency
Review proposals and voluntary, privacy-reviewed usage receipts.

Numbers above identify compatibility references, not required task order.

Learn from ordinary work, without replay

Optional local collection reads reported usage from selected Codex or Claude records after opt-in. It stores counters and bounded metadata, without transcript text, model calls or uploads. Setup checks privacy before storing usage and supports retry. Summary exports stay private and never overwrite files; no automatic purge is introduced.

Separately opted-in Codex hooks request reviews, including non-use. Missing counters, reviews, delivery gaps and failed attempts stay visible. Agent self-reviews and human reviews stay separate. Trigger results describe only the labeled sample.

Usage is not a savings estimate or subscription bill. Controlled comparisons need comparable passing work. Public receipts are self-reported; this brief claims no measured saving.

Routing evidence does not approve a gate

Shadow jobs compare proposed test selections with executed checks. This is separate from choosing a task card or model. Historical evidence does not authorize skipping checks or establish savings.