# Repository instructions

## Bootstrap

[`spec/GOVERNANCE.md`](spec/GOVERNANCE.md) defines document ownership, synchronization, and conflict
resolution. Read it before changing normative ownership, concepts, requirements, validation, or
document authority.

Load every project document whose activation description matches the task, then follow its relevant
links. Project documents use the Agent Skills discovery shape for progressive disclosure but are not
harness skills. Stop for clarification on conflict; never weaken a requirement silently.

<!-- generated: project-documents -->
<project_documents>
  <document>
    <name>governance</name>
    <description>
      Always read before changing normative ownership, concepts, requirements, validation, or
      document authority. Defines synchronization, conflicts, and process maturity.
    </description>
    <location>spec/GOVERNANCE.md</location>
  </document>
  <document>
    <name>goals</name>
    <description>
      Read when evaluating product direction, scope, or whether a proposed behavior serves the
      intended user outcome.
    </description>
    <location>spec/GOALS.md</location>
  </document>
  <document>
    <name>glossary</name>
    <description>
      Read when defining or using canonical concepts, terminology, aliases, distinctions, or
      concept-to-requirement relationships.
    </description>
    <location>spec/GLOSSARY.md</location>
  </document>
  <document>
    <name>product</name>
    <description>
      Read before designing, implementing, testing, or reviewing externally observable behavior or
      safety guarantees.
    </description>
    <location>spec/PRODUCT.md</location>
  </document>
  <document>
    <name>ui-guidelines</name>
    <description>
      Read when changing interaction, terminal behavior, layout, input, accessibility, or rendering.
    </description>
    <location>spec/UI_GUIDELINES.md</location>
  </document>
  <document>
    <name>coding-style</name>
    <description>
      Read before changing Zig, build.zig, runtime architecture, repository tooling, or
      implementation constraints.
    </description>
    <location>spec/CODING_STYLE.md</location>
  </document>
  <document>
    <name>testing</name>
    <description>
      Read when designing, implementing, reviewing, or running tests, evidence, simulations, or
      repository gates.
    </description>
    <location>spec/TESTING.md</location>
  </document>
  <document>
    <name>limits</name>
    <description>
      Read when changing capacities, bounds, exhaustion behavior, process limits, or resource
      accounting.
    </description>
    <location>spec/LIMITS.md</location>
  </document>
  <document>
    <name>performance</name>
    <description>
      Read when changing the resource model, performance budgets, bottlenecks, measurement methods,
      benchmarks, profiling evidence, or regression criteria.
    </description>
    <location>spec/PERFORMANCE.md</location>
  </document>
  <document>
    <name>filesystem-capabilities</name>
    <description>
      Read when changing traversal, roots, mounts, filesystem identity, accounting capabilities, or
      display truncation.
    </description>
    <location>spec/FILESYSTEM_CAPABILITIES.md</location>
  </document>
  <document>
    <name>classification</name>
    <description>
      Read when changing candidate classification, ownership, evidence, recommendation, or process
      observations.
    </description>
    <location>spec/CLASSIFICATION.md</location>
  </document>
  <document>
    <name>adapters</name>
    <description>
      Read when changing package ecosystems, manager capabilities, effect sets, Android integration,
      or external processes.
    </description>
    <location>spec/ADAPTERS.md</location>
  </document>
  <document>
    <name>configuration</name>
    <description>
      Read when changing configuration grammar, fields, defaults, paths, precedence, exclusions, or
      diagnostics.
    </description>
    <location>spec/CONFIGURATION.md</location>
  </document>
  <document>
    <name>artifacts</name>
    <description>
      Read when changing build outputs, release inputs, provenance, reproducibility, checksums, or
      artifact retention.
    </description>
    <location>spec/ARTIFACT.md</location>
  </document>
  <document>
    <name>manual-page</name>
    <description>
      Read when changing installed documentation, CLI help synchronization, manual rendering, or
      manual packaging.
    </description>
    <location>spec/MAN_PAGE.md</location>
  </document>
  <document>
    <name>termux-packages</name>
    <description>
      Read when preparing, publishing, deploying, verifying, or correcting an official Termux
      package.
    </description>
    <location>spec/TERMUX_PACKAGES.md</location>
  </document>
  <document>
    <name>requirements</name>
    <description>
      Read when tracing requirement identifiers, owners, suites, revisions, or structural coverage.
    </description>
    <location>spec/REQUIREMENTS.md</location>
  </document>
  <document>
    <name>experimental-evidence</name>
    <description>
      Read when relying on platform experiments, evaluating assumptions, or recording evidence
      limitations.
    </description>
    <location>spec/EXPERIMENTAL_EVIDENCE.md</location>
  </document>
  <document>
    <name>documentation-work</name>
    <description>
      Read when planning or completing specification and documentation work that remains unresolved.
    </description>
    <location>spec/TODO.md</location>
  </document>
  <document>
    <name>zig-documentation</name>
    <description>
      Read before relying on Zig language, standard-library, build-system, or command-line APIs.
    </description>
    <location>spec/ZIG_DOCUMENTATION.md</location>
  </document>
</project_documents>
<!-- end-generated: project-documents -->

## Work

- Keep generic `spec-engine` mechanics separate from Janitor-specific model, validation, projections,
  and commands; `spec-engine` must remain reusable by other projects.
- Read the coding style before changing Zig or `build.zig`.
- Follow [`spec/TESTING.md`](spec/TESTING.md) when designing, implementing, or reviewing tests.
- Use the pinned latest stable Zig only;
  consult [`spec/ZIG_DOCUMENTATION.md`](spec/ZIG_DOCUMENTATION.md) locally.
- Use the normal Zig CLI when sufficient; otherwise add a named `build.zig` step.
- Add or update tests for every behavior change.
- Treat mutation, package execution, traversal, and size accounting as safety-critical.
- Add no third-party code dependency, telemetry, persisted scan cache, TODO implementation, skipped
  gate, ignored error, or unexplained safety exception.