Skip to content

phase2-onboarding: adopt Phase 0 contract for m-test-engine#2

Merged
rafael5 merged 1 commit into
mainfrom
phase2-onboarding
May 11, 2026
Merged

phase2-onboarding: adopt Phase 0 contract for m-test-engine#2
rafael5 merged 1 commit into
mainfrom
phase2-onboarding

Conversation

@rafael5
Copy link
Copy Markdown
Contributor

@rafael5 rafael5 commented May 11, 2026

Summary

Tier-2 onboarding per AI-discoverability-plan.md §3.4 and phase1-plan.md §9. Third and final tier-2 repo to ship the Phase-0 contract — completes Phase 2 onboarding after m-modern-corpus PR #2 and tree-sitter-m PR #4.

What landed

Surface Contents
AGENTS.md Authored from scratch — this repo had no CLAUDE.md to rename. Frontmatter declares the container's public contract (name, image base, mount point, lifecycle targets); CLAUDE.md symlinked to it. Five Phase-0 sections present.
dist/lifecycle.json Hand-authored machine-readable description: container_name, image_base, mount_point, lifecycle (per-target make + compose forms), exec_convention (the docker exec ... bash -lc '...' shape), consumers.
dist/repo.meta.json Phase-0 contract. Exposes lifecycle (dist/lifecycle.json) + dockerfile (docker/Dockerfile) + compose (docker/compose.yml). License AGPL-3.0.
tools/check-manifest.py Stdlib-only validator — same pattern as tree-sitter-m.
Makefile Three new targets: manifest (informational — lifecycle.json is hand-authored, not regenerated), check-manifest, check-docs-prose.
.github/workflows/ci.yml Two new steps before the docker build, so a broken manifest fails fast without spinning up containers.

Verification (all green)

  • make manifest — informational pointer
  • make check-manifest — manifest valid + all 3 exposes.* paths present
  • make check-docs-prose — no docs/ directory ✓
  • Canonical Track-A validator (.github/profile/build/validate-repo-meta.py) — OK: dist/repo.meta.json

Design notes

  • Hand-authored lifecycle.json (not generated). Container name, image base, mount point, and the make/compose lifecycle are static — a generator would parse the Dockerfile + compose.yml + Makefile to derive values that don't drift. AGENTS.md § Guardrails captures the "update lifecycle.json in the same commit when these change" rule.
  • Manifest gate before Docker build. Cheaper to fail in 100ms on a malformed JSON than to wait for a container build. The CI ordering reflects this.

Phase 2 progress: 3 of 3 tier-2 repos onboarded with this PR.

Repo Status
m-modern-corpus ✅ Onboarded
tree-sitter-m ✅ Onboarded
m-test-engine ✅ This PR

Phase 1 hook

Once .github ships build-catalog.py (Phase-1 Track B) and adds m-test-engine to its TIER_2 list, this repo's manifest will be picked up by the org catalog automatically — completing the parent plan's Phase 2 exit criterion ("all three tier-2 repos appear in generated tools.json with verified_on dates within 30 days").

Test plan

  • All local gates green
  • Canonical Track-A validator green
  • CI green on this PR (manifest + docs-prose gates run before docker build, then existing smoke chain)

Tier-2 onboarding per .github/docs/AI-discoverability-plan.md §3.4
and phase1-plan.md §9. Third and final tier-2 repo (after
m-modern-corpus + tree-sitter-m) to ship the Phase-0 contract.

What landed:

- AGENTS.md authored from scratch (this repo had no CLAUDE.md to
  rename). Frontmatter declares the container's public contract
  (name, image base, mount point, lifecycle make-targets);
  CLAUDE.md symlinked to it. Five required Phase-0 sections
  (Setup / Test / Build / Verify / Guardrails) present.

- dist/lifecycle.json — hand-authored machine-readable description
  of the container's lifecycle, exec convention, and consumer wiring.
  Mirrors what a downstream tool needs to know to drive the container
  without reading the Dockerfile + compose.yml + Makefile by hand.

- dist/repo.meta.json — Phase-0 contract. $schema points at the
  org-level repo.meta.schema.json. exposes:
    - lifecycle  → dist/lifecycle.json
    - dockerfile → docker/Dockerfile
    - compose    → docker/compose.yml
  License AGPL-3.0. verification_commands: make smoke + make check-manifest.

- tools/check-manifest.py — same stdlib-only validator pattern as
  tree-sitter-m. Asserts manifest parses, required fields present,
  exposes.* paths exist; optional full jsonschema validation when
  the lib is available.

- Makefile — three new targets: manifest (informational; declares
  lifecycle.json is hand-authored, not regenerated), check-manifest,
  check-docs-prose.

- .github/workflows/ci.yml — two new steps in the existing `smoke`
  job, BEFORE the docker build so a broken manifest fails fast:
  "Phase-0 manifest contract gate" + "docs/ prose-only gate".

Verification, all green:
- make manifest                            informational pointer
- make check-manifest                      ✓ (manifest valid + all 3 paths present)
- make check-docs-prose                    ✓ (no docs/ directory)
- canonical Track-A validator              OK: dist/repo.meta.json

Once .github ships build-catalog.py (Phase-1 Track B) and adds
m-test-engine to its TIER_2 list, this repo's manifest will be picked
up by the org catalog automatically.

Phase 2 progress: 3 of 3 tier-2 repos onboarded with this PR
(m-modern-corpus + tree-sitter-m + m-test-engine).
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