Skip to content

phase5-plan: continuous enforcement hardening plan#31

Merged
rafael5 merged 1 commit into
mainfrom
phase5-plan
May 11, 2026
Merged

phase5-plan: continuous enforcement hardening plan#31
rafael5 merged 1 commit into
mainfrom
phase5-plan

Conversation

@rafael5
Copy link
Copy Markdown
Contributor

@rafael5 rafael5 commented May 11, 2026

Summary

Phase 5 first move per AI-discoverability-plan.md §6 + AI-discoverability-architecture.md §5 "Operational invariants". Authors the plan doc that the four enforcement gates will be built against. No enforcement gates ship in this PR — Tracks A–E land as their own PRs per the calling convention.

Phase 5 scope

Four enforcement gates, each watching one architectural promise that's currently held by maintainer discipline:

Gate Watches Catches
Freshness verified_on across repo.meta.json + recipes Stale claims drifting under our feet
Link-check Every URL in llms.txt + every *_url in tools.json + doc in task_index.json Pointer-URL rot (kills "pointers, not facts")
License-reconcile Declared license vs LICENSE-file signature Silent license drift inside the org
Schema-version schema_compat bumps on *.schema.json A consumer pinned to v1 breaking when org publishes v2

Track layout

Five tracks. A–D are independent (no file overlap, no shared mutable state); any pair is safe to run in parallel. Each track ships:

  • one new profile/build/check-<gate>.py (TDD-covered)
  • one new Make target (make check-freshness / check-links / check-licenses / check-schema-compat)
  • one new CI step

PR-mode runs the --offline variants (fast, no flake). Weekly cron runs the live-fetch variants on the same firing as the existing handshake-live cron.

Track B carries a Phase 4 follow-up as B0: fix validate-repo-meta.py's UTF-8-decode bug on binary exposes.* URLs (the workaround ARGS=--no-resolve exists today; B0 removes the need).

Phase 5 done definition

Seven criteria (plan §10). When all green, the framework's operational loop is complete — every architectural promise has an automated watchdog.

Other changes

  • docs/ai-discoverability/README.md — Phase 5 row added to the phase table.
  • docs/ai-discoverability/AI-discoverability-architecture.md — "Phase 5 outlook" section rewritten to point at the plan + summarise the five-track shape.

Test plan

  • make check-docs-prose — clean
  • make recipes-check — 4/4 clean
  • make handshake — 8/8 steps green
  • CI green

Phase 5 first move per AI-discoverability-plan.md §6 +
AI-discoverability-architecture.md §5. Authors the plan doc that
the four enforcement gates (freshness / link-check /
license-reconcile / schema-version) will be built against.

* New: docs/ai-discoverability/phases/phase5-plan.md.
  Five tracks following the established phase0-/3-/4-plan shape:
  A freshness, B link-check (+B0 carry-over fix for the
  validate-repo-meta.py UTF-8-decode bug on binary URLs), C
  license-reconcile, D schema-version policing, E close-out
  evidence. Tracks A-D are independent (no file overlap, no shared
  mutable state); any pair is safe to run in parallel. Each track
  ships one profile/build/check-*.py gate + one Make target + one
  CI step. PR-mode runs the --offline variants; weekly cron runs
  the live-fetch variants.

* docs/ai-discoverability/README.md: added the Phase 5 row to the
  phase table.

* AI-discoverability-architecture.md "Phase 5 outlook" rewritten —
  now points at the plan doc and summarises the five-track shape.

This PR is plan-only — no enforcement gates ship here. Tracks A-E
land as their own PRs per the calling convention in §8.
@rafael5 rafael5 merged commit 3970ef6 into main May 11, 2026
2 checks passed
@rafael5 rafael5 deleted the phase5-plan branch May 11, 2026 13:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant