Define reusable project-loop protocol and portable naming

[code2hack]

Actor

ChatGPT

Objective

Record a reusable, repository-agnostic harness/loop protocol that can be carried into future projects.

All harness- and loop-related reusable artifacts must use project-* naming rather than the current repository name. Product-specific files may still use product names when appropriate.

Motivation

A project harness defines the environment and rules one agent works inside. A project loop sits above the harness: it discovers one eligible work item, invokes agents inside isolated worktrees, verifies results, records durable state, and decides the next transition.

The loop must reduce manual prompting without removing human product judgment, review responsibility, or merge authorization.

ChatGPT scope

• Add a durable design document at docs/project-loop.md.
• Update AGENTS.md with the reusable Project Loop Protocol.
• Record generic naming, safety, state-machine, maker/checker, evidence, and stop-condition rules.
• Update the relevant tracked state and decision files.
• Do not implement or schedule DGX Spark automation in this issue.

Portable naming contract

Use names such as:

project-loop.toml
.project-loop/
.agents/skills/project-loop/SKILL.md
.codex/agents/project-verifier.toml
scripts/project-loop/select_work.py
scripts/project-loop/run_cycle.sh
scripts/project-loop/validate_receipt.py
docs/project-loop.md

Do not name reusable harness or loop artifacts after video-pal or another product. Repository-specific values belong in configuration, specifications, issues, and state—not in reusable framework paths.

Required loop model

One bounded cycle:

DISCOVER
→ CLAIM
→ ISOLATE
→ RECONCILE
→ BASELINE
→ VERIFY
→ REPAIR (bounded)
→ INDEPENDENT REVIEW
→ RECEIPT
→ HANDOFF / STOP

The first supported workflow is PR verification and deterministic repair, not autonomous product creation.

Required safety rules

• Process at most one work item per cycle.
• Never work directly on main.
• Use an isolated Git worktree.
• Never merge, deploy, expose secrets, or make destructive changes.
• Never change approved product behavior to satisfy a test.
• Use a separate read-only verifier from the maker.
• Default to at most three repair attempts.
• Stop on human decisions, unchanged validation delta, conflicts, unexpected scope, exhausted budget, or repeated failure.
• A no-op run is successful when no eligible work exists.

Durable evidence

Every non-no-op cycle must post a structured receipt to the relevant issue or PR with:

• run ID
• actor/runtime
• work item
• starting and ending commit
• attempt count
• exact commands and exit results
• remaining validation delta
• changed files
• verifier result
• stop reason
• next actor
• known risks

Raw local logs may live under ignored .project-loop/; essential state must not exist only there.

Acceptance criteria

• docs/project-loop.md documents the portable architecture and state machine.
• AGENTS.md defines loop eligibility, isolation, maker/checker separation, bounded repairs, stop conditions, receipts, and human gates.
• Reusable artifact names use project-*, not product-specific names.
• State and decision files record the accepted naming and loop principles.
• The design distinguishes harness checks from the loop controller.
• The design identifies a separate Codex implementation issue and exact next actor.
• No DGX Spark execution is claimed in this governance issue.

Dependency and merge note

This protocol builds on draft PR #4's specification-driven workflow and must remain stacked or be rebased after the prerequisite governance PRs are resolved.

Human decision required

Approve or revise the reusable naming contract, bounded loop model, and safety gates before merge.

[code2hack]

Protocol implementation is published in stacked draft PR #6 on chatgpt/5-project-loop-protocol.

Recorded in Git:

• docs/project-loop.md
• Project Loop Protocol section in AGENTS.md
• portable project-* naming contract
• bounded one-item state machine
• isolated-worktree requirement
• maker/checker separation
• durable receipt and human-gate rules
• feat-007 protocol state and feat-008 implementation roadmap
• updated progress, handoff, current-state, and decision logs

Separate Codex implementation issue: #7.

Observed connector evidence:

• branch is 3 commits ahead and 0 behind the PR [ChatGPT] Establish specification-driven workflow #4 branch
• PR [ChatGPT] Define reusable project-loop protocol #6 changes 7 files
• PR [ChatGPT] Define reusable project-loop protocol #6 is currently mergeable and remains draft
• no DGX Spark execution is claimed

Next actors:

1. Codex comments on Implement project-loop v1 on DGX Spark #7 with a local plan and constraints.
2. Human reviews the protocol and governance merge order.
3. Codex begins Stage 0 only after explicit human authorization.