todo2code

Ticket 018: Enforce new-project governance as policy-as-code

Goal and scope

Turn wellmanifest/new-project from documentation-only guidance into a deterministic policy-as-code standard, then adopt that standard in todo2code. The gate must make intent visible before implementation: after a completed ticket, a new multi-step code change requires a new plan-only ticket and a separate human approval before source, test, build or CI implementation files may be changed.

This ticket covers two coordinated repositories:

The implementation will not treat an agent-edited Markdown field as trusted human approval. GitHub PR review/CODEOWNERS is the merge-time trust boundary; local validation reports approval as unverified when no trusted CI context is available.

The evolved scope also supports safe parallel work by several humans or agents without splitting the repository prematurely. todo2code remains one modular repository, but tickets are assigned to declared workstreams such as core-dsl, extractors, llm, runtime, interfaces, sdk, governance and integration. At most one active implementation ticket is allowed per workstream, and active tickets may not claim overlapping write paths. Explicit dependency and conflict edges replace implicit coordination; cross-workstream contract changes require an integration ticket instead of silently widening an existing ticket.

Planned changed paths

Planned multi-agent contract

Planned Koru code-review extension

The user requested automated code review through Koru. The implementation will add a read-only GitHub check named koru / code-review, run for pull requests and explicit historical-review dispatches. It will pin Koru 0.1.444 and Vallm 0.1.94, select only changed supported source files, and let Koru execute one bounded Vallm review round. The review runs deterministic complexity and security checks, attempts Vallm syntax analysis, and uses an OpenRouter semantic judge supplied by the existing organization-level OPENROUTER_API_KEY secret.

The historical semantic judge was google/gemini-3.1-pro-preview, selected from the then-current llm-code-benchmark/v1 report. The current executable judge is openrouter/z-ai/glm-5.2, selected by the human owner to bound review cost. This is a configuration decision, not a fabricated benchmark claim; no paid comparison was run. Vallm’s Python-oriented --regression mode is intentionally not used for TypeScript: the separate required verify job owns TypeScript compilation and the repository’s 335-test regression suite. Koru remains the read-only semantic, complexity and security review boundary. Vallm still attempts syntax analysis, but 0.1.94 passes the uppercase language enum TYPESCRIPT to a parser that accepts lowercase typescript. The workflow now applies a pinned lowercase compatibility boundary before parsing and still blocks if any syntax.unsupported finding remains.

The repaired execution budget is explicit and layered. GitHub terminates the whole job after 10 minutes; Vallm and its LiteLLM request are bounded to 420 seconds so report construction, artifact upload and attestation retain roughly three minutes of the job budget after an active-review timeout (less the setup time already consumed). Responses are capped at 8192 tokens. LiteLLM retries are disabled, therefore provider HTTP errors such as 401, 402, 403 or 404 fail immediately rather than consuming the timeout. A pinned compatibility boundary lowercases Vallm 0.1.94’s language ID before tree-sitter parsing. Semantic info and warning findings remain in the attested report as advisory when Vallm’s file-level verdict is pass; semantic errors and every syntax, complexity, security, provider, malformed/missing-result or timeout finding remain blocking.

The workflow will never use pull_request_target, check out untrusted code with a write-capable token, modify source, auto-fix, commit, push or submit a GitHub APPROVE review. A missing secret or semantic-provider failure is an explicit non-passing outcome rather than a silent deterministic fallback. Forked pull requests therefore require a trusted maintainer rerun in a safe context instead of receiving organization secrets.

The machine-readable report will be bound to repository, base SHA, head SHA, tool versions and verdict, uploaded as a CI artifact and covered by a GitHub artifact attestation. A repository ruleset will require both the existing governance check and koru / code-review; the Koru attestation is independent read-only review evidence, not evidence that the implementation author or this agent self-approved.

Planned bounded-delivery extension

The follow-up changes the central wellmanifest/new-project contract and its todo2code adoption so implementation tickets are small, predictable delivery slices rather than open-ended projects. A slice owns exactly one observable outcome in one workstream and has a hard active-execution timebox of at most 30 minutes. At 25 minutes the implementer records a checkpoint; at 30 minutes it must stop. Unfinished work becomes a newly planned dependency slice and may not be hidden by widening the current intent or PR.

Before EDIT, every slice will declare a machine-readable delivery budget:

Default hard limits will be conservative: one workstream, one capability, at most five implementation files, at most two affected components, no new runtime dependency and no public API/schema/database migration unless a separately approved integration slice owns that contract. File count excludes ticket evidence but not generated application artifacts. Line count and commit count remain descriptive signals, never the sole measure of complexity.

Architecture is decided before coding, proportionally to risk. Every ticket has a short architecture-impact record. An ADR/diagram is additionally required only when the slice moves responsibility, changes a component/interface edge, alters persistent data or adds a multi-state UI flow. UI slices must enumerate loading, empty, error and success states as applicable and name their visual, accessibility and interaction checks before implementation.

The validator will fail closed when the budget is absent, over 30 minutes, larger than S, exceeded by the actual diff, or when architecture/validation decisions remain unresolved. It will also compare the approved base with the current branch, reject a mixed-ticket diff, require explicit dependencies and conflicts, and invalidate approval after a base, scope or architecture change. Before publication the slice is refreshed against the target branch and tested again; a semantic or textual conflict returns it to planning rather than being resolved opportunistically inside the PR.

Pull requests remain a protected publication boundary for implementation, but their size is now bounded by the delivery contract. Documentation-only, generated-artifact and emergency exceptions require an explicit manifest mode and equivalent signed evidence; they are not a general direct-push bypass.

Planned canonical 0.10.0 adoption and review-cost correction

Upstream main@c0bb63e and feat/bounded-delivery-contract@1ae86a1 both identify themselves as 0.9.0 but carry different lifecycle semantics. This target is pinned to 1ae86a1, where PLAN and BLOCKED still reserve workstreams. Upstream main correctly reserves only IN_PROGRESS; the standard must reconcile these contracts before another target upgrade is trustworthy.

Wait for wellmanifest/new-project ticket-003 to publish one reviewed full SHA for 0.10.0 that combines bounded delivery with the corrected active/non-active state model. Then run adoption in --check mode, review the managed-file plan, apply the explicit upgrade and regenerate lock hashes against that exact SHA.

The executable Koru judge now uses openrouter/z-ai/glm-5.2 per the user’s cost decision. Historical Gemini benchmark logs remain unchanged as historical evidence. No live OpenRouter request or new paid comparison belongs to this migration.

Acceptance criteria

Participants

Risks and constraints

Approval boundary

Current hardening and validation evidence

Validation result and publication blockers

The multi-workstream extension was explicitly approved by the user in chat on 2026-08-01. The results below describe the already executed 0.7.0 baseline and remain historical evidence, not evidence for AC-11..AC-17.