diff --git a/collab/plan/02-branching.llm.md b/collab/plan/02-branching.llm.md new file mode 100644 index 0000000..50ada75 --- /dev/null +++ b/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. + diff --git a/collab/plan/02-branching.md b/collab/plan/02-branching.md new file mode 100644 index 0000000..570db7c --- /dev/null +++ b/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. diff --git a/collab/proposals/02-branching.llm.md b/collab/proposals/02-branching.llm.md new file mode 100644 index 0000000..7e51adc --- /dev/null +++ b/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”. diff --git a/collab/proposals/02-branching.md b/collab/proposals/02-branching.md new file mode 100644 index 0000000..e72ee7a --- /dev/null +++ b/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. + diff --git a/collab/questions/02-branching.md b/collab/questions/02-branching.md index 08d406d..f9b15ba 100644 --- a/collab/questions/02-branching.md +++ b/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? +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. - diff --git a/docs/devlog/DEVLOG_LLM.md b/docs/devlog/DEVLOG_LLM.md index 982ad4d..dd47922 100644 --- a/docs/devlog/DEVLOG_LLM.md +++ b/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 diff --git a/meta/AGENTS.seed.llm.md b/meta/AGENTS.seed.llm.md index 7daa0b6..939e289 100644 --- a/meta/AGENTS.seed.llm.md +++ b/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 …”; 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. diff --git a/meta/AGENTS.seed.md b/meta/AGENTS.seed.md index a974ac5..60b40e3 100644 --- a/meta/AGENTS.seed.md +++ b/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. diff --git a/prompts/global/system.llm.md b/prompts/global/system.llm.md index 6976b79..ebc8a49 100644 --- a/prompts/global/system.llm.md +++ b/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 …”; 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. diff --git a/prompts/global/system.md b/prompts/global/system.md index 535806a..4e10ebc 100644 --- a/prompts/global/system.md +++ b/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 . Read/edit and let me know.` diff --git a/scripts/audit.sh b/scripts/audit.sh index 3a74db0..d57ac19 100644 --- a/scripts/audit.sh +++ b/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" -