nginx-markdown-harness-maintenance

name	nginx-markdown-harness-maintenance
description	Route and validate harness maintenance work for nginx-markdown-for-agents. Use when changing AGENTS.md, docs/harness, tools/harness, Makefile, or CI harness wiring, and when you need spec resolution, risk-pack routing, and phased verification commands.

NGINX Markdown Harness Maintenance

Keep harness changes aligned with repo-owned truth surfaces and run the right verification matrix with minimal guesswork.

Quick Start

1. Resolve current spec intent: python3 tools/harness/resolve_spec.py --hint "<task summary>"
2. Route changed files to risk packs: python3 skills/nginx-markdown-harness-maintenance/scripts/harness_route.py --from-git
3. Run cheap blockers first: make harness-check
4. Run focused or umbrella checks from the route output.
5. If docs/release wiring changed, run: make harness-check-full

Example Output

$ python3 skills/nginx-markdown-harness-maintenance/scripts/harness_route.py --from-git
files: 2
  - docs/harness/README.md
  - docs/guides/HARNESS_MAINTENANCE.md
matched risk packs: 1
  - docs-tooling-drift (docs/harness/risk-packs/docs-tooling-drift.md)
    path hits:
      - docs/guides/HARNESS_MAINTENANCE.md
      - docs/harness/README.md
    keyword hits:
      - docs
verification families: 3
  - [cheap-blocker] docs-tooling
  - [cheap-blocker] harness-sync
  - [umbrella] release-quality

Workflow

1. Treat AGENTS.md and docs/harness/ as canonical contract surfaces.
2. Use tools/harness/resolve_spec.py before broad edits. If status is WARN_NEEDS_AUTHOR_REVIEW, stop and explain ambiguity before continuing.
3. Use python3 skills/nginx-markdown-harness-maintenance/scripts/harness_route.py --from-git to map changed files/hints to risk packs and verification families from docs/harness/routing-manifest.json.
4. Build a phased matrix:
   • cheap-blocker first
   • then focused-semantic
   • then umbrella only when needed
5. On first drift trigger:
   • identify minimal changed files related to the failing family
   • rerun only affected verification family commands
   • run make harness-check before broad retries
   • if drift repeats, escalate with full error output and affected surfaces
6. Keep optional local adapters optional. Missing local files must degrade as SKIP_NOT_PRESENT, not repository failure.
7. If harness behavior changes, update repo truth in the same change set: AGENTS.md, docs/harness/, tools/harness/, Makefile, CI workflow.

Definition of Done

• resolve_spec.py returns PASS or explicitly documented WARN_*
• matched verification families have been run and outcomes recorded
• repeated drift has either converged or been escalated with concrete evidence
• repo truth surfaces are updated when harness behavior changed

References

• Verification map: references/verification-map.md
• Truth surfaces and escalation rules: references/truth-surfaces.md

Document Updates

Version	Date	Author	Changes
0.5.0	2026-04-21	docs-standardization	Added update tracking section
0.6.2	2026-05-08	Kang	Unified version narrative to 0.6.2 current release line