Task 16 Execution Packet: Replace Handwritten gen.py via SDS-021 (Aligned to 2026-01-25 Plan)

Use this as the exact execution guide for an agent implementing Task 16.

Objective

Replace handwritten tools/codegen/gen.py with SDS-021-generated code so that codegen tooling is fully spec-owned and deterministic.

Non-negotiables

• Spec-first: behavior must be defined in SDS-021 and emitted by generators.
• No handwritten edits in generated zones.
• Determinism: same inputs → same gen.py output.
• Offline-first: generation must not require network access.

Step 0 — Ground the current code reality (must confirm before editing)

Verify:

• tools/codegen/gen.py (contains handwritten markers?)
• docs/specs/shared/sds/021-* (current SDS-021 scope)
• Generator templates that emit codegen tools (search in tools/codegen/templates/ and generators/)
• Existing determinism tests in tools/tests/

If any of these differ, update this packet before coding.

Step 1 — Update SDS-021 to own gen.py

Modify the SDS-021 spec to include tools/codegen/gen.py as a generated artifact.

Requirements:

• The spec must fully define the generated entrypoint (name, outputs, required params).
• The spec must be deterministic and include no volatile fields.

Step 2 — Update generator templates to emit gen.py

Update the generator/templates that produce codegen tooling so tools/codegen/gen.py is emitted from SDS-021.

Requirements:

• No handwritten changes to tools/codegen/gen.py.
• Stable ordering, no timestamps, no random IDs.
• Any shared helpers live in existing handwritten runtime modules (if already present), but the entrypoint file itself is generated.

Step 3 — Regenerate and verify

Run the spec pipeline to regenerate outputs:

1
just pipeline shared

(If the repo uses a different target for SDS-021, use that instead.)

Step 4 — Tests

Add or update tests to prove gen.py is spec-generated and deterministic.

Required test file:

• tools/tests/test_codegen_determinism.py

Minimum assertions:

• gen.py does not contain HANDWRITTEN.
• gen.py output is deterministic across repeated generation.

Run:

1
pytest tools/tests/test_codegen_determinism.py -v

Only mark Task 16 complete after tests pass.

Acceptance criteria (from plan)

• No HANDWRITTEN markers in tools/codegen/gen.py.
• Determinism test passes.
• Generation is offline-capable.

“If you hit this, do this” diagnostics

• Circular dependency (generator needs gen.py to generate gen.py):
  • Add a minimal bootstrapping path only if required and keep it spec-owned.
  • Do not reintroduce handwritten bypass markers.
• Template drift:
  • Confirm SDS-021 is the only source of truth; remove any ad-hoc generation paths.