Contracts

adversarial-evidence-contract.md

Contract — Adversarial Evidence

Every adversarial-squad pass on this mission records, for each contested finding, a disposition of exactly one of: accepted, changed, or deferred_with_rationale. No contested finding may be silently dropped.

  • post-spec squad → reviews/post-spec-squad.md (done; dispositions folded into revised spec).
  • post-plan squad → reviews/post-plan-squad.md (dispositions folded into plan/artifacts).
  • post-tasks squad (anti-laziness) → reviews/post-tasks-squad.md.

Each review lists: finding, lens, severity, disposition, and the resulting spec/plan/tasks change (or the rationale for deferral). This contract satisfies the plan step's mandatory adversarial-evidence requirement.

audience-resolution-contract.md

Contract — Audience Resolution (FR-002/FR-003)

list) targeting a persona under docs/context/audience/. Cardinality: single value preferred; a list is permitted.

structural_lint_config.frontmatter_required_fields (would red every untouched page).

pages; fails on 0 examined. Emits checked_count.

row naming this resolver; 047-audience-oriented-writing references it.

  • Field: audience: in page frontmatter. Value = one resolvable repo-relative .md path (or a
  • Scope: required on touched pages only (C-012). MUST NOT be added to
  • Resolver (scripts/docs/audience_resolver.py or an extension of related_validator):
  • Walks docs/**.md, collects audience: values, asserts each resolves to an existing file.
  • Non-vacuous: reuses assert_examined_floor with min_files ≥ the count of audience-tagged
  • Runs --strict on PR in docs-freshness.yml; exit 1 on any dangling reference.
  • Canonization: 042-common-docs + common-docs styleguide document the field with a tooling:

pre-merge-build-contract.md

Contract — Pre-Merge DocFX Build Gate (FR-017, NFR-001)

Today the DocFX build, seo_verify, and redirect-coverage gates run only on push to main/2.x. This mission adds a pull_request job so structural doc moves are verified before merge.

1. docfx docs/docfx.json — build MUST be zero-error and zero-warning (no glob rot, e.g. the dead apidoc/** glob must be resolved). 2. redirect_stub_generator.py coverage — every baseline URL + every occurrence-map move covered. 3. seo_verify.py --strict against the built _site (description band, etc.).

tracked under #3265. Advisory beyond build correctness (does not add a new blocking Commit-Boundary gate).

redirect_map.yaml entries runs on PR even when the full build is skipped.

  • Trigger: pull_request touching docs/, scripts/docs/, or the nav manifests.
  • Steps:
  • Relation to #3265: folds the pre-merge slice of the deferred SEO gate; the remainder stays
  • Cross-check: a cheap source-level assertion that occurrence_map.yaml moves: ⊆

redirect-tooling-contract.md

Contract — Redirect / Move Tooling (FR-021, C-010, NFR-010)

--occurrence-map kitty-specs/common-docs-convergence-01KZMTR9/occurrence_map.yaml (NOT the hardcoded closed-mission default). Parameterizing/removing that hardcode is part of IC-02.

(cumulative spine or additive merge); coverage and check-map subcommands pass; moves: ⊆ map.

structural lint's shadow_tree_basename skips it.

mission) is reconciled — see #2358. IC-11 is this mission's single writer.

  • Move spine: this mission's occurrence_map.yaml. Every file move is a moves: entry.
  • Invocation: redirect_stub_generator.py and relative_link_fixer.py are driven with
  • redirect_map.yaml: DERIVED artifact — regenerated from baseline + moves, never hand-edited.
  • redirect_baseline_urls.json: IMMUTABLE input — the coverage denominator; never edited per move.
  • Cumulative coverage (NFR-010): regeneration MUST preserve the prior closed mission's 149 entries
  • Stubs: every generated redirect stub carries description: "Redirect stub: …" (FR-022) so the
  • Cross-mission: single-writer ownership of redirect_map.yaml (WP07 of the closed structural-move