governance: enforce strict Questions→Proposal→Plan gates with explicit approval phrases; add branching proposal; mark plan pending; audit checks sequencing

collab/plan/02-branching.llm.md

@@ -0,0 +1,24 @@
+# 02 — Branching/Release — Plan (LLM)
+
+- Model: Trunk-based with protected `main` (always green, production-ready) + short-lived feature branches (`feat/*`, `fix/*`, `chore/*`, `docs/*`, `ci/*`, `refactor/*`). Optional `next` integration branch only if batching risky work.
+- Repo content on `main`: Full repo (code, prompts, templates, docs) — must pass CI and audits on every merge.
+- Tags: `YYYY-MM-DD-HHMM` on release-ready commits.
+- CI protections: Required checks (audit + Docker tests), linear history, PR required, Conventional Commits.
+
+- Migration steps:
+  1) Tag current good baseline (e.g., `YYYY-MM-DD-HHMM`).
+  2) Create `wip/phase1` branch from current `main`; continue all WIP there under PRs to `main`.
+  3) Enable protections on `main` in Gitea: required checks (audit/test), PR reviews, linear history.
+  4) Document policy in `docs/branching.md` and update README.
+  5) Add templates/docs for downstream projects to adopt same policy (if needed).
+
+- Acceptance:
+  - `main` protected with required CI checks; PR required; Conventional Commits enforced.
+  - `wip/phase1` exists; ongoing work targets it.
+  - Tags used only for release-ready commits on `main`.
+  - `docs/branching.md` present and referenced by README.
+
+- Notes:
+  - Reassess `next` only if multiple parallel risky features emerge.
+  - Keep branches short-lived; delete after merge.
+

collab/plan/02-branching.md

@@ -0,0 +1,37 @@
+# 02 — Branching/Release — Plan
+# Status: Pending Proposal Approval — do not execute until 02-branching proposal is approved (“Approved for Plan”).
+
+Purpose: Keep `main` production-ready and clean while enabling fast, safe iteration via short-lived branches and CI protections.
+
+## Chosen Model
+- Trunk-based development:
+  - `main` is always green and production-ready (zero technical debt).
+  - Work happens on short-lived branches by type: `feat/*`, `fix/*`, `chore/*`, `docs/*`, `ci/*`, `refactor/*`.
+  - Optional `next` integration branch only if batching risky changes is necessary.
+
+## Repo Content on `main`
+- Full repository (code, prompts, templates, docs). Every merge must pass audits and Docker-based CI.
+- Releases tagged `YYYY-MM-DD-HHMM` on `main` only.
+
+## CI/Gitea Protections
+- Required checks on `main`: scripts/audit.sh and Docker test job.
+- Require PRs to merge; block direct pushes.
+- Enforce linear history (no merge commits) or squash-merge per preference.
+- Enforce Conventional Commits in PR titles.
+
+## Migration Steps
+1) Tag current baseline on `main` (e.g., `YYYY-MM-DD-HHMM`).
+2) Create `wip/phase1` from current `main`; continue TDD work there.
+3) Configure Gitea branch protection for `main` with required checks and PR requirement.
+4) Add `docs/branching.md` describing this policy; link from README.
+5) Optionally create `next` if multiple risky features need integration before `main`.
+
+## Acceptance Criteria
+- `main` is protected in Gitea with required audit/test checks and PR-only merges.
+- `wip/phase1` branch exists and becomes the target for ongoing work until Phase 1 is complete.
+- Tags are created only on `main` for release-ready states.
+- `docs/branching.md` added and referenced by README.
+
+## Notes
+- Keep branches short-lived; delete after merge.
+- If policy changes, update `docs/branching.md`, AGENTS templates, and prompts/global to propagate.

collab/proposals/02-branching.llm.md

@@ -0,0 +1,9 @@
+# 02 — Branching/Release — Proposal (LLM)
+
+- Goal: Keep `main` always green and production-ready with CI protections, while developing on short-lived branches.
+- Recommended model: Trunk-based. Optional `next` only for batching risky work.
+- Main content: full repo (code, prompts, templates, docs). Release tags: `YYYY-MM-DD-HHMM` on `main` only.
+- Protections: required checks (audit + Docker tests), PRs required, Conventional Commits, linear history/squash.
+- Migration: tag baseline; create `wip/phase1`; enable protections; add docs/branching.md.
+
+Approve by replying in the human doc with “Approved for Plan”.

collab/proposals/02-branching.md

@@ -0,0 +1,22 @@
+# 02 — Branching/Release — Proposal
+
+Purpose: Keep `main` production-ready and clean; iterate on short-lived branches with CI protections.
+
+## Recommendation
+- Model: Trunk-based development
+  - `main` is always green and production-ready (zero technical debt).
+  - Use short-lived branches by type: `feat/*`, `fix/*`, `chore/*`, `docs/*`, `ci/*`, `refactor/*`.
+  - Optional `next` integration branch if batching risky work.
+- Repo content on `main`: full repo (code, prompts, templates, docs). Every merge passes audits and Docker-based CI.
+- Releases: tag `YYYY-MM-DD-HHMM` on `main` only.
+- Protections: required checks (audit + Docker tests), PRs required, Conventional Commits, linear/squash merges.
+
+## Migration (high level)
+- Tag current baseline on `main`.
+- Create `wip/phase1` from `main` and continue ongoing TDD work there.
+- Enable branch protections for `main` in Gitea (required checks + PRs).
+- Add `docs/branching.md` policy and link in README.
+
+## Decision
+Please reply “Approved for Plan” to proceed to the detailed branching plan.
+

collab/questions/02-branching.md

@@ -18,6 +18,8 @@ simplify consumption by other projects
 
 3) Consumption: Will external automation/scripts rely on cloning `main` to bootstrap? If yes, what assets must be present on `main` (templates, prompts, wrapper) to keep bootstrapping simple?
 
+No. I don't believe this will ever be automatically cloned to bootstrap. I expect that to be only done by a human. I can't control what people do of course, it's a public repo.
+
 ## Branching Models (pick one or adjust)
 4) Trunk-based (recommended):
    - `main` = always green, release-ready. All commits pass CI (Docker) and TDD.
@@ -30,25 +32,38 @@ simplify consumption by other projects
    - `main` for releases; `develop` for integration; feature branches; release/hotfix branches.
    - Heavier process; likely overkill unless multiple contributors and scheduled releases.
 
+   Trunk based sounds perfect
+
 ## Repo Content Policy
 7) What exactly belongs on `main`? Options:
    - A) Full repo (code + prompts + templates + docs) — but always green.
    - B) Everything except code/prompts (your suggestion) — use branches/tags for code.
    - C) Minimal bootstrap subset (AGENTS seeds, prompts/global, templates/_shared) + docs.
    Please choose and list mandatory directories for `main`.
+
+   A
+
 8) If B or C: where do code/prompts live (branch names/tags)? How will downstream projects fetch them reliably?
 
 ## CI/Gitea Protections
 9) Protect `main` with required checks (Docker tests) and linear history? Approve? 
+yes I approve
+
 10) Require PR reviews and enforce Conventional Commits? Approve?
+
+Yes I approve
+
 11) Tagging: continue `YYYY-MM-DD-HHMM`. Should `main` tags correspond only to release-ready points?
 
+Hmmm.... I was using tags/releases as a kind of "hack" or "snapshots" and that's not the practice I want to have. Yes the tags should only be release-ready points.
+
 ## Migration Plan (once we choose)
 12) Baseline selection: pick commit/tag for the new `main` baseline.
 13) Branch ops: create `WIPhax`/`next`/`develop` as chosen; move ongoing TDD work there.
 14) CI updates: confirm branch protections and required checks in Gitea.
 15) Docs: add `docs/branching.md` describing the policy; update README.
 
+Do you need anything from me for this section? It's statements not questions, but that plan looks good to me.
+
 ## Decision
 16) Please pick one model (4/5/6) and option (7 A/B/C), then reply “Approved for Branching Plan” (or edit inline). I’ll draft `collab/plan/02-branching.md` for review.
-

docs/devlog/DEVLOG_LLM.md

@@ -214,3 +214,19 @@ This log is concise and structured for quick machine parsing and summarization.
   - Updated proposal/plan/docs to reflect audits
 - next:
   - Continue TDD implementation; run audits before any release tags
+
+## 2025-09-17T17:22Z
+- context: Branching plan drafted after approval (no changes applied yet)
+- actions:
+  - Added `collab/plan/02-branching.md` and `.llm.md` choosing trunk-based model with protected `main`, short-lived branches, and migration steps
+- next:
+  - Await plan approval; then execute branch creation/protections
+
+## 2025-09-17T17:28Z
+- context: Corrected sequencing slip (plan before proposal) and hardened governance
+- actions:
+  - Added `collab/proposals/02-branching.{md,llm.md}` for formal approval; marked plan as pending
+  - Strengthened system prompts and AGENTS templates with strict approval gates and exact phrases
+  - Enhanced audit script to check sequencing gates and warn when pending
+- next:
+  - Await “Approved for Plan” on 02-branching proposal before executing the plan

meta/AGENTS.seed.llm.md

@@ -1,6 +1,7 @@
 # AGENTS (Seed, LLM)
 
 - One-way workflow: questions → proposal → plan → implement; no backsteps after approval.
+ - Gates: human `.md` must include exact phrases — Questions: "Approved for Proposal"; Proposal: "Approved for Plan"; Plan: "Approved to Implement".
 - Read `.llm.md` only; write both `.md` and `.llm.md` siblings for collab artifacts.
 - Chat ≤5 lines; default “Updated <filepath>…”; no diffs; announce only collab file changes; log details in `docs/devlog/`.
 - Keep changes minimal and focused; adopt TDD (tests first); require unit/integration tests for all features; consistent style.

meta/AGENTS.seed.md

@@ -16,6 +16,7 @@ Note: This is a template copied into generated projects. Customize as needed for
 - Start with questions; after approval, proceed to proposal; after approval, proceed to plan; then implement.
 - Once a step is approved, never return to a prior step. Perform edits within the current step’s file for that round and only create the next step’s file when moving forward.
 - The agent reads `.llm.md` files; humans edit `.md`. The agent writes both `.md` and `.llm.md` siblings.
+ - Strict gates (phrases must appear in the human `.md`): Questions → "Approved for Proposal"; Proposal → "Approved for Plan"; Plan → "Approved to Implement". Do not create or advance steps without prior approval.
 
 ## Logs and Documentation
 - Dev logs: `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md` — add an entry for each meaningful change.

prompts/global/system.llm.md

@@ -3,6 +3,11 @@
 - Identity: Concise, precise coding agent in Codex CLI; follow repo AGENTS.md.
 - Read `.llm.md` only; write both `.md` and `.llm.md` siblings for collab artifacts.
 - Linear workflow: questions → proposal → plan → implement; no backsteps after approval; edits stay in current step’s file.
+ - Approval gates (exact phrases in human `.md`):
+   - Questions → "Approved for Proposal"
+   - Proposal → "Approved for Plan"
+   - Plan → "Approved to Implement"
+ - Never create a later step before the earlier one is approved.
 - Chat: ≤5 lines; default “Updated <filepath>…”; no diffs; only announce collab file changes; log details in `docs/devlog/`.
 - Dev logs: update `docs/devlog/DEVLOG_{LLM,HUMAN}.md` each meaningful change.
 - Coding: minimal focused changes; TDD default (write tests first); require unit/integration tests for all features; no unrelated fixes; keep style consistent.

prompts/global/system.md

@@ -19,6 +19,11 @@ You are a coding agent running in the Codex CLI (terminal-based). Be precise, sa
 - Workflow is linear and one-way:
   1) Questions → 2) Proposal → 3) Plan → Implement
 - Once a step is approved, never return to a prior step. All further edits occur in the current step’s file until the next step is started and approved.
+ - Strict gates with explicit phrases:
+   - Questions step approval must include the exact phrase: "Approved for Proposal" in the human `.md` file.
+   - Proposal step approval must include: "Approved for Plan" in the human `.md` file.
+   - Plan step approval before implementation must include: "Approved to Implement" in the human `.md` file.
+ - Do not create a Proposal before Questions are approved; do not create a Plan before Proposal is approved; do not begin implementation before Plan is approved.
 
 ## Chat Output Policy
 - Default chat message: `Updated <filepath>. Read/edit and let me know.`

scripts/audit.sh

@@ -38,6 +38,35 @@ check "Gitea workflow exists" test -f .gitea/workflows/ci.yml
 # Docker compose for local parity
 check "docker/compose.yml exists" test -f docker/compose.yml
 
+# Sequencing gates: for each plan, ensure corresponding proposal approved; for each proposal, ensure questions approved
+status_warn=0
+for plan in collab/plan/*.md; do
+  [ -f "$plan" ] || continue
+  base=$(basename "$plan")
+  prefix=${base%%.md}
+  proposal="collab/proposals/$prefix.md"
+  if [ ! -f "$proposal" ]; then
+    echo "[fail] Missing proposal for plan: $plan" >&2; failures=$((failures+1)); continue
+  fi
+  if ! grep -q "Approved for Plan" "$proposal"; then
+    echo "[warn] Proposal not yet approved for plan ($prefix). Plan should be pending." >&2
+    status_warn=1
+  fi
+  # check questions
+  qfile="collab/questions/$prefix.md"
+  if [ ! -f "$qfile" ]; then
+    echo "[fail] Missing questions for: $prefix" >&2; failures=$((failures+1))
+  else
+    if ! grep -q "Approved for Proposal" "$qfile"; then
+      echo "[warn] Questions not yet approved for proposal ($prefix)." >&2
+      status_warn=1
+    fi
+  fi
+done
+
+if [ "$status_warn" -eq 1 ]; then
+  echo "[note] Sequencing warnings present; ensure approvals before proceeding."
+fi
+
 echo "[summary] failures=$failures"
 exit "$failures"
-