Establish specification-driven feature and verification workflow

[code2hack]

Actor

ChatGPT

Context

Video Pal needs a durable product-specification layer between human product decisions and agent implementation. AGENTS.md defines how collaborators work, while feature_list.json currently mixes product intent, execution state, and evidence without explicit traceability.

The approved direction from the human owner is to add a root spec/ system that both ChatGPT and Codex read. Approved specifications should drive feature decomposition, acceptance criteria, tests, and verification evidence.

This is a governance/harness change. Do not start application implementation in this issue.

Objective

Introduce a minimal, scalable specification workflow with clear authority boundaries:

• AGENTS.md: process authority
• spec/product.md: product scope authority
• spec/features/*.md: behavioral authority
• spec/quality.md: cross-cutting quality authority
• docs/**: architecture and decision authority
• feature_list.json: execution-state and traceability authority
• tests and recorded commands: verification evidence

Proposed scope

1. Add:
   • spec/README.md
   • spec/product.md
   • spec/quality.md
   • spec/features/VP-001-mvp.md
   • spec/templates/feature-spec.md
2. Define stable specification, requirement, and acceptance-criterion IDs.
3. Define lifecycle states: draft, approved, implemented, superseded.
4. Require human approval before a draft product spec becomes implementation authority.
5. Extend feature_list.json with traceability fields while preserving execution evidence.
6. Distinguish planning fields from execution fields so future generators do not overwrite Codex state.
7. Add specification and traceability validation to the harness without requiring an application package manifest.
8. Update tracked state and decision files.
9. Reconcile stale state that says the existing protocol update is still pending push; draft PR [ChatGPT] Define branch, file ownership, and actor identity protocol #2 is already open.

Required workflow

1. Human product intent is recorded in a draft spec.
2. ChatGPT drafts/refines the spec and acceptance criteria.
3. Human approves product behavior and material changes.
4. ChatGPT derives planning fields in feature_list.json from the approved spec.
5. Codex implements on a codex/... branch and maps tests to acceptance IDs.
6. Codex records exact DGX Spark verification evidence.
7. ChatGPT reviews requirement → feature → test → evidence traceability.
8. Human authorizes merge.

Acceptance criteria

• spec/README.md defines authority, lifecycle, IDs, and change control.
• Product, quality, feature, and feature-template files exist.
• The initial MVP feature spec is explicitly draft; no product choices are silently treated as approved.
• AGENTS.md defines the specification-driven workflow and ownership boundaries.
• Existing feature IDs are not silently repurposed.
• feature_list.json preserves existing evidence and adds traceability/ownership fields.
• Governance features may omit product spec references; implementation features may not.
• A validator checks spec structure and unique IDs.
• A traceability checker validates feature references and acceptance-criterion references.
• init.sh runs the new checks.
• State and decision artifacts describe this change and the next actor/action.
• Exact local validation commands and results are recorded before merge.

Human decisions already made

• Adopt a root spec/ directory with multiple small specification files.
• Use specifications to drive feature decomposition and verification obligations.
• Keep product behavior under human approval.
• Do not rely on chat-only product decisions.

Human decision still required

Approve the final file formats, feature-list schema, and lifecycle rules before merge.

[code2hack]

Specification workflow implementation is published in draft PR #4 on chatgpt/3-specification-workflow at head 3a662174ae4305ef13345c3c1e592cddd3a7a032.

Completed in the branch:

• layered spec/ authority and lifecycle
• draft product, quality, and MVP decision specs
• stable traceability IDs and feature template
• feature_list.json schema version 2 with planning/execution field ownership
• specification and traceability validators
• init.sh integration
• durable state and decision updates
• removal of the accidental temporary file

ChatGPT-container evidence:

• python3 scripts/validate_specs.py passed
• python3 scripts/check_traceability.py passed
• Python compilation passed
• bash -n init.sh passed
• negative lifecycle and draft-implementation cases were rejected as expected

Pending before merge:

1. Codex runs ./init.sh and git diff --check on DGX Spark and records exact output in PR [ChatGPT] Establish specification-driven workflow #4.
2. ChatGPT reviews any findings.
3. Human owner resolves PR [ChatGPT] Define branch, file ownership, and actor identity protocol #2/[ChatGPT] Establish specification-driven workflow #4 merge order, approves or revises the governance model, and explicitly authorizes merge.

Product implementation remains blocked because all product specifications are intentionally draft.