Explore a template validation module

[zengsipei]

What to build

Explore a template validation module with one command that checks whether the dev container template still works as a coherent template.

The architecture review found that the repo currently relies on manual confidence across JSON, Docker Compose, shell scripts, workflow release behavior, ports, and documentation. This issue should be designed after the image release contract is clarified, because release-policy checks depend on that contract.

Initial questions to resolve:

• What should the validation command verify locally?
• Which checks belong in CI versus local development?
• Should the validation module inspect docs for declared ports and image names?
• Should it verify shell scripts, JSON, Compose shape, and workflow trigger policy?
• What is the smallest useful first validation surface?

Acceptance criteria

• The validation module interface is decided.
• The first useful validation scope is defined.
• The relationship to the image release contract is explicit.
• Follow-up implementation work is either completed or split into ready-for-agent issues.
• Any surprising or durable trade-off is captured in an ADR if needed.

Blocked by

• Explore an image release contract module #2

[zengsipei]

Two inputs for this exploration, surfaced by the code review of #10 (persistence policy implementation, PR #11):

1. Docs/comment duplication with drift risk. devimage-build/README.md (cache layout section, currently around lines 136–158 and the "add a new cache" recipe near 235–240) repeats the per-link cache mapping that #10 sank into devimage-build/.devcontainer/Dockerfile comments. It was left alone as a builder-facing doc, outside #10's user-docs scope — but it now duplicates the Dockerfile and will silently rot when the manifest or cache links change. Question for the validation surface: should the module check declared facts in docs against the code that owns them (image names, ports, cache links, Persistence Manifest dotdirs), or should we instead dedupe the docs so there's nothing to check?

2. A candidate for "smallest useful first validation surface". After #10, persistence wiring has a single runtime source (scripts/link-agent-home.sh), which makes an end-to-end check cheap and well-defined: start the agent-compose service, verify every manifest dotdir in $HOME is a symlink into the Agent Home mount, tear down. That one check would have caught all three bugs #10 fixed (missing .hapi, conditional links, ln -sf nesting). CI's image build-check never executes the runtime scripts, so this is currently uncovered.

[zengsipei]

This was generated by AI during triage.

Triage Resolution

Explored with the maintainer on 2026-07-07; all decisions are captured in ADR 0004 (docs/adr/0004-template-validation-policy.md), which also revises the ADR 0002 ownership table. Summary:

• Principle: dedupe over check. Checkers exist only for irreducible duplication — facts that must live in two executable files that cannot reference each other (e.g. the ADR 0001 invariants). Prose that restates code gets deduped to a link; the template deliberately has no docs-vs-code sync checkers. This resolves the ADR 0002 vs ADR 0003 §6 conflict over the cache symlink mapping: the Dockerfile comments own it now.
• Three validation tiers. Static (always, local + CI: shellcheck, JSON/JSONC, docker compose config, existing release-contract script) / build (existing path-filtered image build check, untouched) / runtime (new: agent-compose end-to-end).
• Interface: umbrella scripts/check-template.sh with selectable tiers; CI stays a thin caller. The relationship to the image release contract is explicit: ADR 0001's check-release-contract.sh is orchestrated unchanged as part of the static tier.
• First validation surface = the runtime tier (both inputs from the Implement the persistence policy module (ADR 0003) #10/Implement the persistence policy module (ADR 0003) #11 review adopted): fresh Agent Home boot of agent-compose, real bootstrap path (npm installs not skipped), asserting manifest links / idempotency-on-restart / installed CLIs — the layer where all three Implement the persistence policy module (ADR 0003) #10 bugs lived. A volume-isolation safety constraint is recorded (fixed volume names; fresh home via WSL_HOME=<temp dir>, teardown never down -v).

Follow-up implementation, all ready-for-agent:

• Dedupe builder README cache-layout prose into the Dockerfile comments #12 — dedupe the builder README cache prose into the Dockerfile comments
• Dedupe Startup Install: one shared agent-CLI install script for both consumers #13 — dedupe Startup Install into one shared agent-CLI install script
• Add the runtime validation tier: agent-compose end-to-end persistence and startup check #15 — runtime tier end-to-end check (blocked by Dedupe Startup Install: one shared agent-CLI install script for both consumers #13)
• Add the static tier and umbrella command: scripts/check-template.sh #14 — static tier + umbrella command

All acceptance criteria of this issue are satisfied: interface decided, first scope defined, release-contract relationship explicit, work split into ready-for-agent issues, durable trade-offs in ADR 0004. Closing.