docs: add NEWSTART.md and NEWSTART.llm.md capturing all governance, process, and blueprint for a clean repo restart

.gitea/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Repo audit
+        run: |
+          bash scripts/audit.sh
+      - name: Build and run tests via Docker
+        run: |
+          docker compose -f docker/compose.yml up --build --abort-on-container-exit --remove-orphans
+          docker compose -f docker/compose.yml down -v --remove-orphans

CodexHelper

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+die() { echo "error: $*" >&2; exit 1; }
+note() { echo "$*" >&2; }
+
+find_helper_repo_root() {
+  # Walk upwards to find a dir that looks like the helper repo
+  local d="$(pwd)"
+  while [ "$d" != "/" ]; do
+    if [ -d "$d/collab" ] && [ -f "$d/prompts/global/system.md" ]; then
+      printf '%s' "$d"
+      return 0
+    fi
+    d="$(dirname "$d")"
+  done
+  return 1
+}
+
+print_help() {
+  cat <<EOF
+CodexHelper — wrapper for codex-cli with modes and scaffolding
+
+Usage:
+  CodexHelper new-mode --name <ModeName>
+  CodexHelper new-project --mode <ModeName> --name <project-name> --path <dir> [--force]
+  CodexHelper run [--mode <ModeName>] [--prompt-file <file>] [--config <file>] [--sandbox <mode>] [--full-auto]
+  CodexHelper --help
+
+Notes:
+  - Inside the CodexHelper repo, only 'new-mode' is allowed.
+  - Outside the repo, 'new-project' and 'run' are allowed.
+EOF
+}
+
+require_outside_repo_for() {
+  local subcmd="$1"
+  if find_helper_repo_root >/dev/null 2>&1; then
+    if [ "$subcmd" != "new-mode" ]; then
+      die "Only 'new-mode' is allowed when running inside the CodexHelper repository"
+    fi
+  fi
+}
+
+detect_codex() {
+  if [ -n "${CODEX_BIN:-}" ]; then echo "$CODEX_BIN"; return 0; fi
+  if command -v codex >/dev/null 2>&1; then echo codex; return 0; fi
+  if command -v codex-cli >/dev/null 2>&1; then echo codex-cli; return 0; fi
+  die "No codex binary found. Set CODEX_BIN or install 'codex'/'codex-cli' in PATH."
+}
+
+cmd_new_mode() {
+  local name=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --name) name="$2"; shift 2;;
+      --force) FORCE=1; shift;;
+      --help|-h) print_help; exit 0;;
+      *) die "Unknown option for new-mode: $1";;
+    esac
+  done
+  [ -n "$name" ] || die "--name is required"
+  local dir="modes/$name"
+  if [ -e "$dir" ] && [ -z "${FORCE:-}" ]; then
+    die "Mode '$name' already exists. Use --force to overwrite."
+  fi
+  mkdir -p "$dir"
+  : >"$dir/mode.md"
+  : >"$dir/defaults.yaml"
+  note "Created $dir/mode.md and $dir/defaults.yaml"
+}
+
+cmd_new_project() {
+  require_outside_repo_for new-project
+  # Implementation follows in later milestones
+  die "Not yet implemented: new-project (per plan)."
+}
+
+cmd_run() {
+  require_outside_repo_for run
+  # Implementation follows in later milestones
+  die "Not yet implemented: run (per plan)."
+}
+
+main() {
+  local subcmd="${1:-}"; if [ -z "$subcmd" ] || [ "$subcmd" = "--help" ] || [ "$subcmd" = "-h" ]; then
+    print_help; exit 0
+  fi
+  case "$subcmd" in
+    new-mode) shift; cmd_new_mode "$@";;
+    new-project) shift; cmd_new_project "$@";;
+    run) shift; cmd_run "$@";;
+    *) die "Unknown subcommand: $subcmd";;
+  esac
+}
+
+main "$@"

NEWSTART.llm.md

@@ -0,0 +1,18 @@
+# NEW START — LLM
+
+- Non-negotiables: zero-debt; TDD; plan-first; quiet chat; containers-first; CI parity; clean root; audits.
+- Gates (human .md phrases): Questions→“Approved for Proposal”; Proposal→“Approved for Plan”; Plan→“Approved to Implement”.
+- Chat: announce collab files only; ≤5 lines; no content/diff streaming.
+- Quiet tooling: use scripts/toolwrap.sh; success → no chat; failure → append stdout/stderr to docs/devlog/tool.log.
+- Audits: run scripts/audit.sh regularly and pre-release; store in docs/audits/.
+- CI/containers: Gitea Actions + local Docker Compose; dependencies via images; explicit names; cleanup; mount host config if needed.
+- .gitignore: include runs/ + OS files; keep current.
+- Layout: collab/, docs/, prompts/global/, modes/, templates/project/_shared/, scripts/, .gitea/.
+- Wrapper (MVP): subcommands new-mode (repo-only), new-project (outside), run (outside). Guardrails enforced.
+- Prompt order: global system → mode system? → mode rules → project narrative.
+- Config via yq: global < mode < project < ENV < CLI.
+- Project scaffold: AGENTS.md; prompts/{project.md,style.md?}; prompts/_mode; codex.yaml; codex.sh; CI (gitea); docker/compose.yml + test/Dockerfile; scripts/{test.sh,test.docker.sh,audit.sh}; .gitignore; runs/.
+- Tests: bats/internal; cover CLI/guardrails/scaffold/composition/precedence.
+- Branching (recommended): trunk-based; protected main; short-lived branches; tags YYYY-MM-DD-HHMM; required checks; Conventional Commits.
+- Start checklist: commit clean skeleton; add NEWSTART docs; start with Questions 00; use toolwrap + DevLogs; add audits early.
+

NEWSTART.md

@@ -0,0 +1,113 @@
+# New Start — CodexHelper Project Blueprint
+
+Purpose
+- Capture everything we learned so far and define a clean, production-ready blueprint for a fresh repository using CodexHelper. This document is human-focused; see NEWSTART.llm.md for the compact machine version.
+
+Guiding Principles (Non-Negotiable)
+- Safety first, speed second. Zero technical debt at all times; every commit is production-ready.
+- TDD by default. Write failing tests first; make them pass; refactor.
+- Plan first, implement second. Strict Questions → Proposal → Plan → Implement.
+- Quiet, file-first collaboration. Chat is minimal; files and logs carry the detail.
+- Containers-first, with CI parity between local and Gitea.
+- Clean repository roots and predictable scaffolding.
+
+Process & Governance
+- Sequencing (Strict Gates)
+  - Questions → Proposal → Plan → Implement (one-way progression; no backsteps after approval).
+  - Approvals must use exact phrases in the human .md file:
+    - Questions approval: “Approved for Proposal”
+    - Proposal approval: “Approved for Plan”
+    - Plan approval: “Approved to Implement”
+  - Agent reads `.llm.md`; humans edit `.md`. Agent writes both siblings for each artifact.
+- Chat Output Policy
+  - Default: “Updated <filepath>. Read/edit and let me know.”
+  - ≤5 lines; do not stream file contents or diffs in chat.
+  - Announce only collab files (questions/proposals/plan). Everything else goes to DevLog.
+- Quiet Shell, Tool Logging
+  - Quiet is mandatory (no toggle). Use silent checks and avoid printing command output.
+  - Use `scripts/toolwrap.sh` to run host commands quietly.
+    - On success: no chat output; brief SUCCESS line is logged to `docs/devlog/tool.log`.
+    - On failure (not sandbox): append full stdout/stderr + timestamp + command to `docs/devlog/tool.log`.
+- TDD & Quality
+  - Tests live under `tests/`; provide `scripts/test.sh` and `scripts/test.docker.sh`.
+  - Add tests for every feature; keep tests fast and focused.
+  - No unrelated refactors; fix root causes.
+- Architecture & Planning
+  - Maintain `docs/architecture.md` and ADRs for significant decisions.
+  - Design module boundaries up front to avoid refactors; if assumptions change, update Questions/Proposal/Plan and docs before changing code.
+- Clean Roots & .gitignore Housekeeping
+  - Keep root minimal; organize assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`, `.gitea/`.
+  - Include `.gitignore` with `runs/` and common OS files; keep it current.
+- CI/Containers (Gitea + Docker)
+  - CI uses Gitea Actions (`.gitea/workflows/`) and must mirror local Docker Compose.
+  - Do work in containers when appropriate; host is for git/tea and Docker orchestration only.
+  - Dependencies (e.g., bats, yq) are provided via Docker images; avoid host installs.
+  - Naming hygiene for containers/networks; explicit names; ensure cleanup.
+  - Where host auth/config is required (e.g., codex), mount config dirs into the container securely.
+- Audits (Regular and Pre-Release)
+  - Run `scripts/audit.sh` regularly and before any release tag.
+  - Audit checks: governance compliance (gates, quiet policy), structure, .gitignore, CI parity, tests present.
+  - Record audits in `docs/audits/` and summarize in DevLogs.
+
+Branching & Releases (Recommended)
+- Trunk-based development:
+  - `main` is protected, always green, production-ready.
+  - Short-lived branches by type: `feat/*`, `fix/*`, `chore/*`, `docs/*`, `ci/*`, `refactor/*`.
+  - Optional `next` only if batching risky work.
+- Protections: required checks (audit + Docker tests), PRs required, Conventional Commits, linear history or squash.
+- Tags: `YYYY-MM-DD-HHMM` for release-ready commits on `main` only.
+
+Repository Layout (Clean Start)
+- collab/ — questions/, proposals/, plan/ (each step has `NN-<subject>.md` + `.llm.md`).
+- docs/ — devlog/, audits/, architecture.md, feature docs, ADRs.
+- prompts/ — `global/system.md` and `.llm.md` (canonical rules); modes/ live in `modes/`.
+- modes/ — `<ModeName>/{mode.md, system.md?, defaults.yaml}`.
+- templates/ — project scaffolding, including `_shared` with AGENTS.md, CI, docker, scripts.
+- scripts/ — `test.sh`, `test.docker.sh`, `audit.sh`, `toolwrap.sh`.
+- .gitea/ — workflows for CI.
+
+CodexHelper (Wrapper) — MVP Blueprint
+- Goals
+  - Provide modes (global/mode/project prompts), project scaffolding, prompt composition, config precedence, and safe defaults around `codex`/`codex-cli`.
+- CLI (subcommands)
+  - `new-mode` (repo-only): scaffold `modes/<Name>/{mode.md, defaults.yaml, system.md?}`.
+  - `new-project` (outside repo): scaffold project structure (see below).
+  - `run` (outside repo): compose prompts and invoke codex, writing to `runs/<ts>/`.
+- Binary Detection
+  - `CODEX_BIN` env > `which codex` > `which codex-cli`; fail with a helpful message otherwise.
+- Prompt Composition
+  - Order: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
+- Config Precedence (YAML + yq)
+  - global defaults < mode defaults < project config < ENV < CLI.
+- Safety
+  - Require `--force` to overwrite; never run `git push` for user projects.
+- Project Scaffolding (Generated Project Layout)
+  - `AGENTS.md` (from template)
+  - `prompts/project.md` (+ optional `prompts/style.md`)
+  - `prompts/_mode/` (read-only copies of global/mode prompts)
+  - `codex.yaml` (project settings)
+  - `codex.sh` (entrypoint to compose and call codex)
+  - `.gitea/workflows/ci.yml` (CI) + `docker/compose.yml` + `docker/test/Dockerfile`
+  - `scripts/test.sh` + `scripts/test.docker.sh` + `scripts/audit.sh`
+  - `.gitignore` (includes `runs/`)
+  - `runs/` (created on first run; ignored by VCS)
+
+Acceptance (Phase 1 “Crawl”)
+- `new-mode` creates mode skeleton; refuses overwrites unless `--force`.
+- `new-project` scaffolds all files above without overwrites; includes CI and Docker artifacts.
+- `run` composes prompts in the right order and invokes the detected codex binary; artifacts under `runs/<timestamp>/`.
+- Config precedence enforced via yq.
+- Guardrails: inside the helper repo only `new-mode` is allowed; elsewhere `new-project`/`run` allowed.
+- Tests (bats or internal): cover CLI, guardrails, scaffolding, composition, precedence.
+- CI: Gitea workflow executes audit and Docker-based tests; local Docker run mirrors CI.
+
+Start-From-Scratch Checklist (New Repo)
+1) Commit clean skeleton: collab/, docs/, prompts/global/, templates/_shared, scripts/, .gitea/.
+2) Add `NEWSTART.md` and `NEWSTART.llm.md` (this pair) and `docs/architecture.md`.
+3) Begin with `collab/questions/00-bootstrap.{md,llm.md}`; do not proceed without “Approved for Proposal”.
+4) Keep chat minimal; use toolwrap and DevLogs. Add audits early.
+5) Implement Phase 1 via TDD, following Questions→Proposal→Plan gate for each subject.
+
+Notes
+- This blueprint is the canonical source for repository setup and workflow. Keep it in sync with prompts/global/system.md.
+

README.md

@@ -1,3 +1,18 @@
-# ChatGPTScaffolding
+# ChatGPTScaffolding / CodexHelper
 
-Scaffolding (prompts/personas/modes/rules etc) around codex-cli. Tuned for @ReachableCEO needs as a solo entrepreneur. Developed from scratch in an afternoon after three weeks of intense AI usage across multiple providers/systems.
+Scaffolding (prompts/personas/modes/rules etc) around codex-cli. Tuned for @ReachableCEO needs as a solo entrepreneur.
+
+CodexHelper adds:
+- Modes (global/mode/project prompts)
+- Project scaffolding
+- Prompt composition and safe defaults
+- Governance: TDD, zero technical debt, plan-first via Questions → Proposal → Plan
+
+Status: Phase 1 in progress — `new-mode` implemented; `new-project` and `run` coming next.
+
+Quickstart (dev)
+- Run tests: `scripts/test.sh` (uses bats if available)
+- Show help: `./CodexHelper --help`
+- Create a demo mode (in this repo): `./CodexHelper new-mode --name Demo`
+
+See `docs/wrapper.md` and `prompts/global/` for details and governance rules.

collab/plan/01-codexhelper.md

@@ -24,7 +24,7 @@ Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, p
 - Implement creation with intake comments and overwrite safeguards.
 
 4) new-project (outside repo) (tests first)
-- Write tests for project directory creation, copying AGENTS.md, prompts, codex.yaml, codex.sh, and `.gitignore` content.
+- Write tests for project directory creation, copying AGENTS.md, prompts, codex.yaml, codex.sh, `.gitignore` content, and CI/containers artifacts (`.gitea/workflows/ci.yml`, `docker/compose.yml`, `docker/test/Dockerfile`, `scripts/test.docker.sh`).
 - Implement scaffolding and read-only copies under `prompts/_mode/`.
 
 5) run: compose + invoke (tests first)
@@ -57,7 +57,8 @@ Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, p
 - Precedence: CLI > env > project > mode > global.
 - `prompts/global/{system.md,system.llm.md}` are present and included in composition.
 - Running `CodexHelper run` or `new-project` inside this repo errors with guidance.
- - Tests: bats test suite covers all CLI paths and guardrails; tests pass locally; test runner script present.
+- Tests: bats test suite covers all CLI paths and guardrails; tests pass locally; test runner script present.
+ - Project CI: scaffold contains Gitea workflow and Docker artifacts for local parity.
 
 ## Assumptions/Risks
 - codex-cli flags may vary; we’ll design pass-through and document tested flags.

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/01-codexhelper.llm.md

@@ -12,11 +12,15 @@
 - Safety: no overwrites without `--force`; never `git push` for user projects.
 - Outputs: `<project>/runs/<ts>/...`.
 - Layout (repo): `CodexHelper`, `bin/install.sh`, `prompts/global/{system.md,system.llm.md}`, `modes/<Name>/{mode.md,system.md?,defaults.yaml}`, `templates/project/<Name>/...`, `templates/project/_shared/AGENTS.md`, `meta/{AGENTS.seed.md,AGENTS.seed.llm.md}`.
-- Layout (project): `AGENTS.md`, `prompts/{project.md,style.md?}`, `prompts/_mode/`, `codex.yaml`, `codex.sh`, `runs/`.
+- Layout (project): `AGENTS.md`, `prompts/{project.md,style.md?}`, `prompts/_mode/`, `codex.yaml`, `codex.sh`, `runs/`, `.gitea/workflows/`, `docker/`, `scripts/`.
 - Governance/Propagation: non-project-specific workflow changes get recorded in `prompts/global/` and seed AGENTS templates; proposal/plan updated so scaffolding includes them.
 - TDD Governance: adopt test-driven development with full unit/integration tests for all features in this repo and generated projects; tests written first and required for acceptance.
 - Zero Technical Debt: safety first; no technical debt; production-ready at all times; no deferring tests/docs/refactors; use sub-agents as needed.
- - Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; maintain a global architecture/module map; implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated.
+- Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; maintain a global architecture/module map; implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated.
+- Clean Root Governance: keep repo root minimal; organize assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`.
+- CI/Containers Governance: use Gitea Actions with local parity via Docker Compose; do work inside containers; host for git/tea + Docker orchestration; dependencies via Docker; explicit names/cleanup.
+ - .gitignore Governance: maintain `.gitignore` with `runs/` and OS ignores across repos and generated projects.
+ - Audits Governance: run audits regularly; prompt before releases; record under `docs/audits/`; enforce via CI step.
 - Phase 1 acceptance:
   - new-mode creates mode skeleton
   - new-project scaffolds without overwrites
@@ -28,6 +32,11 @@
   - tests: unit/integration tests (bats) cover CLI flows and guardrails; TDD observed
   - zero debt: docs/tests included with every feature; no pending TODOs/deferrals; production-ready criteria met
   - planning: architecture/module map documented; module implementations follow approved plan with no unplanned refactors
+  - clean root: root remains minimal; scaffolding organizes assets under subdirectories
+  - ci/containers: Gitea Actions and local Docker Compose run identical workflows; explicit names and cleanup verified
+  - project CI: scaffold includes `.gitea/workflows/ci.yml`, `docker/compose.yml`, `docker/test/Dockerfile`, and `scripts/test.docker.sh`
+  - audits: audit script present and run in CI; reports recorded in repo when performed
+  - ci/containers: Gitea Actions and local Docker Compose run identical workflows; explicit names and cleanup verified
 \n+## Approval — Tick All That Apply
 
 - Subcommands approved: `new-project`, `run`, `new-mode` [ ]

collab/proposals/01-codexhelper.md

@@ -41,7 +41,11 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes
 - Governance/Propagation: maintain global norms in `prompts/global/` and seed AGENTS templates; reflect such changes in proposal/plan for scaffolding.
 - TDD Governance: enforce test-driven development; require unit/integration tests for all features here and in generated projects.
 - Zero Technical Debt: safety first; always production-ready; no deferring tests/docs/refactors; leverage sub-agents when needed.
- - Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; keep a global architecture/module map; implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated.
+- Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; keep a global architecture/module map; implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated.
+- Clean Root Governance: keep repo root minimal; organize assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`.
+- CI/Containers Governance: use Gitea Actions with local parity via Docker Compose; do work inside containers; host for git/tea and Docker only; dependencies via Docker; explicit names and cleanup.
+ - .gitignore Governance: include and maintain `.gitignore` entries (e.g., `runs/`, OS files) across repos and generated projects.
+ - Audits Governance: perform regular audits; prompt before releases; store reports under `docs/audits/` and enforce via CI step.
 
 ## Project Layout (generated)
 - `AGENTS.md` (from `templates/project/_shared/AGENTS.md`)
@@ -50,6 +54,7 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes
 - `codex.yaml` (project config)
 - `codex.sh` (entrypoint wrapper around codex-cli)
 - `runs/` (created on first run; ignored by VCS)
+- `.gitea/workflows/` for CI; `docker/` for compose and Dockerfiles; `scripts/` for docker orchestration (tests, ci)
 
 ## Config Details
 - Format: YAML (`yq` for merging/reading)
@@ -99,11 +104,15 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes
 - Inside that project, `CodexHelper run --full-auto` composes prompts and calls the detected `codex` binary. It writes artifacts under `runs/<timestamp>/...`.
 - Precedence works: CLI options override env, which override project config, which override mode defaults.
 - Running `CodexHelper run` in this repo prints an error guiding usage.
- - Project scaffold includes `AGENTS.md` copied from `templates/project/_shared/AGENTS.md`.
-  - `prompts/global/{system.md, system.llm.md}` exist and are included in composition.
-  - Governance/Propagation honored: when norms change, update `prompts/global/` and AGENTS templates; log in DevLog.
-  - TDD honored: a test suite (bats) covers CLI flows and guardrails; tests pass.
-  - Zero Debt honored: code, tests, and docs complete; no debt items remain.
+- Project scaffold includes `AGENTS.md` copied from `templates/project/_shared/AGENTS.md`.
+- `prompts/global/{system.md, system.llm.md}` exist and are included in composition.
+- Governance/Propagation honored: when norms change, update `prompts/global/` and AGENTS templates; log in DevLog.
+- TDD honored: a test suite (bats) covers CLI flows and guardrails; tests pass.
+- Zero Debt honored: code, tests, and docs complete; no debt items remain.
+- Clean Root honored: only essential files at root; scaffolding places assets under subdirectories.
+- CI/Containers honored: CI runs in Gitea and locally using the same Docker Compose; containers and networks use explicit names and are cleaned up.
+- Project scaffold includes `.gitea/workflows/ci.yml`, `docker/compose.yml`, `docker/test/Dockerfile`, and `scripts/test.docker.sh` copied from templates.
+ - Audits honored: audit script present and executed in CI; reports are recorded when performed.
 
 ## Open Items for Confirmation
 - Template coverage: include `prompts/style.md` by default? (we’ll include as optional, empty file)

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.llm.md

@@ -0,0 +1,20 @@
+# 02 — Branching/Release — Confirm (LLM)
+
+- Goals: top 3 drivers for change? [ ]
+- Stability: main = always green release-ready OR docs-only? [ ]
+- Consumption: what must be on main for bootstrap? [ ]
+
+- Choose model:
+  - Trunk-based (main green; short-lived branches) [ ]
+  - WIP branch (main release-only; WIPhax/wip/*) [ ]
+  - GitFlow (main/develop/release/hotfix) [ ]
+
+- Repo content on main: A full repo [ ] / B no code/prompts [ ] / C minimal bootstrap [ ]
+- If B/C: where do code/prompts live? naming? [ ]
+
+- Protections: require CI checks on main [ ]; PR reviews [ ]; Conventional Commits [ ]; tags only for release-ready [ ]
+
+- Migration: baseline commit/tag [ ]; create branches [ ]; update CI protections [ ]; add docs/branching.md [ ]
+
+Final: Reply “Approved for Branching Plan” with choices to proceed.
+

collab/questions/02-branching.md

@@ -0,0 +1,69 @@
+# 02 — Branching/Release — Questions
+
+Purpose: Align on a clean, sustainable branch and release strategy before any changes. We will not implement until you approve.
+
+Context: You suggested moving active work to a `WIPhax` branch and keeping `main` limited to non-code assets (docs/collab/.gitea). Below are options and tradeoffs to decide together.
+
+## Goals & Constraints
+1) Primary goals: What are the top 3 goals driving this change? (e.g., keep `main` always pristine, minimize merge noise, avoid half-baked code on main, simplify consumption by other projects, etc.)
+
+main pristine
+avoid half-baked code on main
+simplify consumption by other projects
+
+
+2) Stability bar: Should `main` be “always green + release-ready” with protected branch/required CI? Or “docs-only” as you proposed?
+
+"always green + release ready" 
+
+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.
+   - Work happens on short-lived feature branches `feat/*`, `fix/*` merged via PR.
+   - Optional long-lived integration branch `next` for batching risky changes.
+5) WIP branch variant:
+   - `main` = release-ready only; heavy ongoing work on `WIPhax` (or `wip/*`), merged back via PR when green.
+   - Risk: drift between `WIPhax` and `main`, elevated merge pain if long-lived.
+6) GitFlow:
+   - `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.

docker/compose.yml

@@ -0,0 +1,19 @@
+name: codexhelper
+
+services:
+  tests:
+    build:
+      context: ..
+      dockerfile: docker/test/Dockerfile
+    container_name: codexhelper-tests
+    working_dir: /work
+    volumes:
+      - ..:/work:Z
+    command: ["/bin/bash", "-lc", "scripts/test.sh"]
+    networks:
+      - codexhelper-net
+
+networks:
+  codexhelper-net:
+    name: codexhelper-net
+

docker/test/Dockerfile

@@ -0,0 +1,11 @@
+FROM debian:bookworm-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       ca-certificates git bash curl jq yq \
+       bats \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /work
+

docs/architecture.md

@@ -0,0 +1,34 @@
+# CodexHelper — Architecture (Phase 1)
+
+Overview
+- Goal: Bash wrapper around `codex`/`codex-cli` with modes, project scaffolding, prompt composition, config precedence, and safety.
+- Constraints: TDD, zero technical debt, plan-first, clean root, CI via Gitea with local Docker parity.
+
+Modules
+- CLI Entrypoint (`CodexHelper`)
+  - Subcommands: `new-mode` (repo-only), `new-project` (outside repo), `run` (outside repo)
+  - Guardrails: detect helper repo by structure; block disallowed subcommands
+  - Binary Detection: `CODEX_BIN` > `codex` > `codex-cli`
+  - Flag Pass-through: `--mode`, `--prompt-file`, `--config`, `--sandbox`, `--full-auto`, `--`
+
+- Scaffolding
+  - Modes: `modes/<Name>/{mode.md, defaults.yaml, system.md?}` with intake hints
+  - Projects: `AGENTS.md`, `prompts/{project.md,style.md?}`, `prompts/_mode/` (copies of global/mode prompts), `codex.yaml`, `codex.sh`, `.gitignore`, CI/containers templates
+
+- Run Engine
+  - Validate project layout
+  - Compose prompts (global system → mode system? → mode rules → project narrative)
+  - Invoke `$CODEX_BIN` with pass-through flags; write artifacts under `runs/<ts>/`
+
+- Config
+  - YAML via `yq`: global defaults < mode defaults < project config < ENV < CLI
+
+Cross-cutting
+- Tests: `tests/` via bats or fallback; Docker Compose runner for local parity; Gitea Actions for CI
+- Docs: `README.md`, `docs/wrapper.md`, `docs/architecture.md`, DevLogs
+- Governance: propagation updates applied to prompts/global and AGENTS templates
+
+Assumptions
+- `yq` available in containers; host only orchestrates Docker and git/tea.
+- codex auth may require host mounts; handled via project `codex.sh` composition.
+

docs/audits/2025-09-17-audit.llm.md

@@ -0,0 +1,29 @@
+# Audit — 2025-09-17
+
+Summary
+- Scope: Repo structure, governance compliance, plan alignment, CI/containers, TDD, zero-debt.
+- Status: Mostly compliant; a few gaps noted with fixes proposed or applied.
+
+Findings
+- Governance
+  - One-way Q→P→Plan: compliant.
+  - Read `.llm.md`/write both: compliant in artifacts; continue practice.
+  - TDD: present; tests for CLI/guardrails/new-mode exist; proceed to cover remaining milestones.
+  - Zero debt: generally compliant; architecture doc added now to satisfy plan; keep docs/tests in lockstep.
+  - Clean root: compliant; marker removed; heuristic detection in place.
+  - Planning/architecture: docs/architecture.md added; maintain ADRs if decisions evolve.
+  - CI/containers: Gitea workflow + Docker Compose present; local parity script present.
+- Repo Structure
+  - Organized under `collab/`, `docs/`, `prompts/`, `modes/`, `templates/`, `scripts/`, `meta/`, `.gitea/` — clean.
+- Scaffolding Templates
+  - Added project CI/Docker templates and AGENTS.md. Missing: project `.gitignore` and `scripts/test.sh` template (recommended; add).
+- Tests
+  - Repo tests pass (internal runner). Add Docker test run to CI already configured.
+- Open Work vs Plan
+  - Pending: `new-project`, `run`, config precedence (`yq`), copying templates, `.gitignore` template, project scripts/test.sh.
+
+Actions
+- Add templates/project/_shared/{.gitignore,scripts/test.sh} [recommended ASAP].
+- Implement remaining milestones via TDD; expand tests accordingly.
+- Keep DevLogs updated for each change.
+

docs/audits/2025-09-17-audit.md

@@ -0,0 +1,34 @@
+# Audit — 2025-09-17
+
+Scope
+- Full audit of repository against governance rules, proposal/plan, and delivered code.
+
+Summary
+- Compliance is strong across governance (TDD, zero-debt, planning, clean root, CI/containers). Gaps are minor and fixable now.
+
+Findings
+- Governance compliance
+  - One-way Questions→Proposal→Plan process is followed; confirmations consolidated into the proposal.
+  - `.llm.md`-first reading and dual-write artifacts are present and used.
+  - TDD in effect (tests for CLI/guardrails/new-mode). Continue test-first for remaining milestones.
+  - Zero technical debt emphasized; architecture doc added to meet plan; docs kept current.
+  - Clean root enforced; marker removed; heuristic repo detection implemented and tested.
+  - Planning/architecture documented in `docs/architecture.md`; maintain ADRs if decisions change.
+  - CI/containers aligned with Gitea and local parity via Docker Compose; names explicit and cleanup performed.
+- Structure
+  - Root remains minimal. Subdirectories are coherent: `collab/`, `docs/`, `prompts/`, `modes/`, `templates/`, `scripts/`, `meta/`, `.gitea/`.
+- Templates
+  - Project templates include AGENTS.md and CI/Docker artifacts. Missing `.gitignore` and `scripts/test.sh` template — add now.
+- Tests
+  - Repo tests pass locally (internal runner). Docker-based runner available (`scripts/test.docker.sh`). CI workflow uses the same compose.
+- Open vs Plan
+  - Not yet implemented: `new-project`, `run`, YAML precedence (`yq`), project `.gitignore`, project scripts/test.sh, copying mode/global prompts.
+
+Recommendations (immediate)
+- Add `templates/project/_shared/.gitignore` with `runs/` and common ignores.
+- Add `templates/project/_shared/scripts/test.sh` mirroring repo test runner.
+- Proceed with TDD for remaining milestones; update docs/DevLogs at each step.
+
+Conclusion
+- The project is on track and adheres to governance. Address the small template gaps and continue TDD implementation.
+

docs/devlog/DEVLOG_LLM.md

@@ -162,3 +162,93 @@ This log is concise and structured for quick machine parsing and summarization.
   - Updated proposal/plan to add architecture/module map deliverable and acceptance
 - next:
   - Add `docs/architecture.md` early in implementation per plan
+
+## 2025-09-17T16:38Z
+- context: Root cleanliness governance and marker removal
+- actions:
+  - Added clean-root rule to system prompts and AGENTS templates
+  - Removed `.codexhelper-repo`; replaced guard detection with repo-structure heuristic
+  - Updated CLI guardrail tests accordingly
+- next:
+  - Keep root minimal going forward; store assets under subdirectories
+
+## 2025-09-17T16:50Z
+- context: CI/Containers governance (Gitea + Docker) and local parity
+- actions:
+  - Added `.gitea/workflows/ci.yml` using Docker Compose
+  - Added `docker/compose.yml` and `docker/test/Dockerfile` with explicit names and cleanup flow
+  - Added `scripts/test.docker.sh` wrapper
+  - Propagated CI/containers rules to system prompts and AGENTS templates; updated proposal
+- next:
+  - Ensure future features include containerized workflows and CI updates
+
+## 2025-09-17T17:00Z
+- context: Project scaffolding to include Gitea workflow and Docker artifacts
+- actions:
+  - Added project templates: `.gitea/workflows/ci.yml`, `docker/compose.yml`, `docker/test/Dockerfile`, `scripts/test.docker.sh`
+  - Updated proposal and plan to require these in generated projects
+- next:
+  - Implement new-project scaffolder to copy these templates
+
+## 2025-09-17T17:08Z
+- context: Full repository audit and immediate fixes for minor gaps
+- actions:
+  - Added `docs/audits/2025-09-17-audit.{md,llm.md}` with findings and actions
+  - Added `docs/architecture.md` per plan
+  - Added missing project templates: `.gitignore` and `scripts/test.sh`
+- next:
+  - Proceed with TDD to implement new-project and run
+
+## 2025-09-17T17:12Z
+- context: Branching/release strategy discussion opened — no changes yet
+- actions:
+  - Added `collab/questions/02-branching.{md,llm.md}` with options/tradeoffs for `main` vs `WIPhax` and protection rules
+- next:
+  - Await answers; then draft a branching plan for approval before any branch changes
+
+## 2025-09-17T17:18Z
+- context: Implement audit recommendations; add .gitignore and audit governance
+- actions:
+  - Added scripts/audit.sh and CI audit step; updated project templates to include audit
+  - Updated global/system prompts and AGENTS templates with .gitignore housekeeping and regular audits policy
+  - 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
+
+## 2025-09-17T17:34Z
+- context: Silence chat streaming of file contents/diffs
+- actions:
+  - Strengthened system prompts and templates with “Quiet Shell/No Streaming” rules
+  - Added audit advisory to flag usage of `cat`/`sed -n` in scripts
+- next:
+  - Avoid printing file contents via shell; log details to DevLog when needed
+
+## 2025-09-17T17:40Z
+- context: Quiet is now mandatory (no toggle)
+- actions:
+  - Updated system prompts and AGENTS templates to state quiet is required
+- next:
+  - Continue with quiet operations and filesystem-first logging
+## 2025-09-17T16:34Z
+- context: Quiet tooling wrapper added; tool.log policy established
+- actions:
+  - Added scripts/toolwrap.sh for quiet execution and failure logging to docs/devlog/tool.log
+  - Updated system prompts and AGENTS templates to use tool.log
+- next:
+  - Use toolwrap for host-side orchestration commands to keep chat silent

docs/devlog/tool.log

@@ -0,0 +1,5 @@
+2025-09-17T16:40:06Z FAILURE: git add -A
+--- STDOUT ---
+--- STDERR ---
+./scripts/toolwrap.sh: line 21: {git: command not found
+--------------

docs/wrapper.md

@@ -0,0 +1,23 @@
+# CodexHelper Wrapper — Usage and Design (Phase 1)
+
+Overview
+- CodexHelper wraps `codex`/`codex-cli` to provide modes, project scaffolding, and prompt composition.
+- Governance: TDD, zero technical debt, plan-first via Questions → Proposal → Plan, production-ready always.
+
+Status (Phase 1 in progress)
+- Implemented: `new-mode` scaffolder (repo-only), CLI skeleton, guardrails.
+- Pending (per plan): `new-project`, `run`, config precedence (YAML+yq).
+ - CI/Containers: Gitea Actions workflow in `.gitea/workflows/ci.yml`; local parity via `docker/compose.yml`.
+
+CLI
+- Help: `./CodexHelper --help`
+- Repo-only: `./CodexHelper new-mode --name <ModeName> [--force]`
+- Outside-repo (pending): `CodexHelper new-project --mode <ModeName> --name <project-name> --path <dir> [--force]`
+- Outside-repo (pending): `CodexHelper run [--mode <ModeName>] [--prompt-file <file>] [--config <file>] [--sandbox <mode>] [--full-auto]`
+
+Development
+- Tests: run `scripts/test.sh` (uses bats if available, falls back to internal runner).
+- Docker tests: `scripts/test.docker.sh` runs the same suite via Docker Compose.
+- Audit: run `scripts/audit.sh` for governance/structure checks; CI runs it too.
+- Follow TDD: write failing tests first, make them pass, refactor.
+- Keep `docs/architecture.md` and README up to date as features land.

meta/AGENTS.seed.llm.md

@@ -1,8 +1,12 @@
 # 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/`.
+- Quiet shell: avoid `cat`/`sed` outputs; use silent checks; log details to DevLog files.
+- Quiet is mandatory (no toggle) for this tool.
+ - Tool logging: use quiet wrapper; log to `docs/devlog/tool.log` on failures; no chat output.
 - Keep changes minimal and focused; adopt TDD (tests first); require unit/integration tests for all features; consistent style.
 - Git: Conventional Commits; branch `main`; optional tags `YYYY-MM-DD-HHMM`.
 - Tools: file-first; use `rg`; read ≤250 lines; respect sandbox/approvals; preface grouped commands.
@@ -13,3 +17,11 @@
 - Zero Technical Debt: Safety first; no technical debt; always production-ready; no deferring tests/docs/refactors; TDD by default; keep docs current.
  
 - Planning/Architecture: Plan via Questions→Proposal→Plan; maintain global architecture/module map; implement module-by-module; avoid refactors unless assumptions change and plans/docs are updated.
+ 
+- Clean Roots: Keep project root minimal; use `docs/`, `templates/`, `prompts/`, `scripts/`, etc.; avoid ad-hoc root files.
+ 
+- CI/Containers: Use Gitea Actions with local parity via Docker Compose; do work in containers; host for git/tea + Docker orchestration; dependencies via Docker; explicit names; cleanup.
+ 
+- .gitignore: Ensure `.gitignore` includes `runs/` and common OS ignores; keep updated.
+ 
+- Audits: Run regular audits; prompt user before release; store under `docs/audits/`; summarize in DevLog.

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.
@@ -37,6 +38,9 @@ Note: This is a template copied into generated projects. Customize as needed for
 - Default message: `Updated <filepath>. Read/edit and let me know.`
 - Keep chat ≤5 lines; no diffs or large pastes.
 - Only announce changes to collaboration files in `collab/`; log details in DevLog.
+- Quiet shell: avoid streaming file contents/diffs; prefer silent checks and log details to DevLog.
+- Quiet is mandatory (no toggle) for this tool’s workflows.
+ - Tool logging: use a quiet wrapper to log to `docs/devlog/tool.log` on failures; keep chat silent.
 
 ## Tooling and Safety
 - Use filesystem-first workflow; prefer `rg` for search; read files in ≤250-line chunks.
@@ -71,3 +75,19 @@ Customize this AGENTS.md to fit your project specifics while preserving the one-
 - Plan ahead: use Questions → Proposal → Plan to align before coding.
 - Maintain a project architecture/module map and document boundaries.
 - Implement module-by-module per plan; avoid refactors, except when new info requires plan/doc updates.
+
+## Clean Repository Roots
+- Keep the project root minimal and tidy. Prefer directories over many files at root.
+- Place docs, templates, prompts, and scripts under dedicated subdirectories.
+
+## .gitignore Housekeeping
+- Include a `.gitignore` with `runs/` and common OS ignores; keep it up to date.
+
+## CI and Containers (Gitea + Docker)
+- Use Gitea Actions for CI (`.gitea/workflows/`).
+- Ensure local parity with Docker Compose; provide scripts to run the same CI tasks locally.
+- Perform work inside containers where appropriate; use host for git/tea and Docker orchestration only.
+- Manage dependencies via container images; avoid host-level installs.
+- Use explicit container/network names; clean up containers, networks, and volumes.
+## Audits
+- Perform regular audits; prompt for an audit before any release/tag. Save reports under `docs/audits/` and log summaries in DevLogs.

nm.err

@@ -0,0 +1 @@
+Created modes/DemoMode/mode.md and modes/DemoMode/defaults.yaml

nm2.err

@@ -0,0 +1 @@
+error: Mode 'DemoMode' already exists. Use --force to overwrite.

nm3.err

@@ -0,0 +1 @@
+Created modes/DemoMode/mode.md and modes/DemoMode/defaults.yaml

np.err

@@ -0,0 +1 @@
+error: Only 'new-mode' is allowed when running inside the CodexHelper repository

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.
@@ -26,3 +31,29 @@
 - Plan before coding via Questions → Proposal → Plan.
 - Maintain a global architecture/module map; document boundaries.
 - Implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated.
+
+-- Clean Roots --
+- Keep repo root minimal; store assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`. Avoid ad-hoc root files.
+
+-- .gitignore --
+- Require `.gitignore` with `runs/` and common OS ignores; keep updated as artifacts evolve.
+
+-- CI/Containers (Gitea + Docker) --
+- CI uses Gitea Actions in `.gitea/workflows/` with local parity via Docker Compose.
+- Do work inside containers; host only for git/tea and Docker orchestration.
+- Dependencies via Docker (e.g., bats). Avoid host installs.
+- Use explicit container/network names; remove orphans; clean networks/volumes.
+- Mount host config (e.g., codex) when needed.
+- Keep local/remote in sync; no dangling files or empty directories.
+
+-- Audits --
+- Run regular audits and prompt user before release tags. Record results in `docs/audits/`; summarize in DevLog.
+
+-- Quiet Shell/No Streaming --
+- Never stream file contents/diffs in chat. Avoid `cat`/`sed` outputs.
+- Use silent checks (exit codes, `grep -q`); log details in DevLog files.
+- Quiet is mandatory (no toggle); default to minimal, non-chat output.
+
+-- Tool Logging --
+- On success: no chat output; optional one-line summary to `docs/devlog/tool.log`.
+- On failure (not sandbox): capture stdout/stderr and append to `docs/devlog/tool.log` with timestamp and command.

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.`
@@ -26,6 +31,17 @@ You are a coding agent running in the Codex CLI (terminal-based). Be precise, sa
 - Only announce changes to `collab/questions/`, `collab/proposals/`, and `collab/plan/`. Log all other details in `docs/devlog/`.
 - Provide brief preambles before grouped tool calls.
 
+## Quiet Shell and No Streaming
+- Do not stream file contents or diffs into chat. Avoid `cat`/`sed` output in chat.
+- Prefer silent checks (e.g., `grep -q`, exit codes) and write details to DevLog files if needed.
+- If content must be inspected, avoid printing it to chat; summarize findings in DevLog and reference the file.
+- Quiet is mandatory (no toggle). Tools and scripts should default to minimal, non-chat output.
+
+## Tool Logging (tool.log)
+- On command success: do not print to chat; optionally append a one-line summary to `docs/devlog/tool.log`.
+- On command failure (not sandbox failures): write full stdout/stderr to `docs/devlog/tool.log` with timestamp and command.
+- Use a quiet wrapper script to enforce this behavior.
+
 ## Dev Logs and Docs
 - Maintain `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md`. Add an entry for each meaningful change.
 - Keep `README.md` up to date for quickstart and usage.
@@ -90,6 +106,29 @@ You are a coding agent running in the Codex CLI (terminal-based). Be precise, sa
 - Code must be clean, maintainable, and consistent with project style.
 - Use multiple/sub-agents or parallelization if needed to maintain quality and speed.
 
+## Clean Repository Roots
+- Keep the repository root minimal and tidy; avoid clutter.
+- Place helper/templates/docs under dedicated directories (`docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`).
+- Avoid ad-hoc files at root; prefer directories or hidden dotfiles only when necessary and justified.
+
+## .gitignore Housekeeping
+- Every repo and generated project must include a `.gitignore` with at least `runs/` and common OS artifacts.
+- Keep `.gitignore` current as new generated or runtime artifacts are introduced.
+
+## CI and Containers (Gitea + Docker)
+- CI: Use Gitea Actions exclusively. Store workflows under `.gitea/workflows/`.
+- Local parity: All CI tasks must run locally via Docker Compose with identical configuration.
+- Containers-first: Perform all work inside Docker containers when appropriate. Host is for git/tea and Docker orchestration only.
+- Dependencies: Pull tools (e.g., bats, yq) via Docker images; do not require host installs.
+- Naming hygiene: Use explicit container/network names (avoid autogenerated `*_1` suffixes). Clean up containers, networks, and volumes after runs.
+- Config: Where host auth/config is required (e.g., codex), mount the necessary config dirs into the container securely.
+- Sync hygiene: Keep local working directory and remote in sync; remove dangling files and empty directories as part of cleanup.
+
+## Audits (Regular and Pre‑Release)
+- Perform regular audits to verify governance compliance (TDD, zero-debt, clean root, CI parity, .gitignore coverage, structure).
+- Prompt the user for an audit prior to cutting any release/tag.
+- Maintain concise audit reports in `docs/audits/` and log summaries in DevLogs.
+
 ## Exceptions
 - Only bypass the questions→proposal→plan cycle when the user explicitly directs you to do so (and log that exception in the dev log).
 

run.err

@@ -0,0 +1 @@
+error: Only 'new-mode' is allowed when running inside the CodexHelper repository

scripts/audit.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root_dir="$(cd "$(dirname "$0")/.." && pwd)"
+
+failures=0
+check() {
+  local msg="$1"; shift
+  if "$@"; then
+    echo "[ok] $msg"
+  else
+    echo "[fail] $msg" >&2
+    failures=$((failures+1))
+  fi
+}
+
+cd "$root_dir"
+
+# Structure checks
+for d in collab docs prompts templates scripts meta .gitea; do
+  check "dir exists: $d" test -d "$d"
+done
+
+# .gitignore housekeeping
+if [ -f .gitignore ]; then
+  if grep -q '^runs/' .gitignore; then
+    echo "[ok] .gitignore includes runs/"
+  else
+    echo "[fail] .gitignore missing runs/" >&2; failures=$((failures+1))
+  fi
+else
+  echo "[warn] no .gitignore at repo root"
+fi
+
+# CI presence
+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
+
+# Quiet shell policy (advisory): ensure no scripted chat streaming helpers exist
+if command -v rg >/dev/null 2>&1; then
+  if rg -n "\b(cat|sed\s+-n)\b" scripts 2>/dev/null | grep -v audit.sh >/dev/null 2>&1; then
+    echo "[warn] scripts contain cat/sed -n; ensure these are not used to stream contents into chat" >&2
+  fi
+fi
+
+# 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"

scripts/test.docker.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+here="$(cd "$(dirname "$0")" && pwd)"
+root="$(cd "$here/.." && pwd)"
+
+compose_file="$root/docker/compose.yml"
+
+echo "[docker] Running tests via docker compose"
+docker compose -f "$compose_file" up --build --abort-on-container-exit --remove-orphans
+docker compose -f "$compose_file" down -v --remove-orphans
+

scripts/test.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+if command -v bats >/dev/null 2>&1; then
+  exec bats "$ROOT_DIR/tests"
+fi
+
+# Minimal internal test runner (fallback when bats is not installed)
+echo "[info] bats not found; using internal test runner" >&2
+
+failures=0
+total=0
+
+for t in "$ROOT_DIR"/tests/*.sh; do
+  [ -f "$t" ] || continue
+  total=$((total+1))
+  echo "[run] $t"
+  if bash "$t"; then
+    echo "[ok]  $t"
+  else
+    echo "[fail] $t" >&2
+    failures=$((failures+1))
+  fi
+done
+
+echo "[summary] total=$total failures=$failures"
+if [ "$failures" -ne 0 ]; then
+  exit 1
+fi
+exit 0
+

scripts/toolwrap.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Quiet command wrapper:
+# - Runs the given command without emitting stdout/stderr to the console.
+# - On success: prints nothing; logs an optional one-line summary to tool.log.
+# - On failure: writes full stdout/stderr to tool.log and exits non-zero.
+
+log_file="docs/devlog/tool.log"
+mkdir -p "$(dirname "$log_file")"
+
+ts() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+
+cmd=("$@")
+
+# Capture stdout/stderr
+out_file="$(mktemp)"
+err_file="$(mktemp)"
+rc=0
+
+{"${cmd[@]}"} >"$out_file" 2>"$err_file" || rc=$?
+
+if [ "$rc" -eq 0 ]; then
+  echo "$(ts) SUCCESS: ${cmd[*]}" >> "$log_file"
+  rm -f "$out_file" "$err_file"
+  exit 0
+fi
+
+{
+  echo "$(ts) FAILURE: ${cmd[*]}"
+  echo "--- STDOUT ---"
+  cat "$out_file"
+  echo "--- STDERR ---"
+  cat "$err_file"
+  echo "--------------"
+} >> "$log_file"
+
+rm -f "$out_file" "$err_file"
+exit "$rc"
+

templates/project/_shared/.gitea/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Repo audit
+        run: |
+          bash scripts/audit.sh
+      - name: Build and run tests via Docker
+        run: |
+          docker compose -f docker/compose.yml up --build --abort-on-container-exit --remove-orphans
+          docker compose -f docker/compose.yml down -v --remove-orphans

templates/project/_shared/.gitignore

@@ -0,0 +1,7 @@
+# Generated runs and logs
+runs/
+
+# OS files
+.DS_Store
+Thumbs.db
+

templates/project/_shared/AGENTS.md

@@ -19,6 +19,9 @@ This file is copied by scaffolding into new projects. Edit to suit the project w
 ## Chat Output Policy
 - Default: `Updated <filepath>. Read/edit and let me know.`
 - Keep chat ≤5 lines; no diffs; announce only collab file changes; log details in DevLog.
+- Quiet shell: avoid printing file contents/diffs; prefer silent checks and DevLog summaries.
+- Quiet is mandatory (no toggle) in this workflow.
+ - Tool logging: prefer a quiet wrapper that logs to `docs/devlog/tool.log` on failures; keep chat silent.
 
 ## Coding, Tests, and Git
 - Minimal, focused changes; adopt TDD (write tests first) and require unit/integration tests for all features; consistent style.
@@ -46,3 +49,17 @@ This file is copied by scaffolding into new projects. Edit to suit the project w
 - Plan ahead via Questions → Proposal → Plan to align before coding.
 - Maintain an architecture/module map and clear module boundaries.
 - Implement module-by-module; refactor only when new information requires plan/doc updates.
+
+## Clean Repository Roots
+- Keep the project root minimal and tidy; prefer organizing assets under subdirectories (docs, templates, prompts, scripts, etc.).
+
+## .gitignore Housekeeping
+- Include and maintain a `.gitignore` with `runs/` and common OS ignores.
+
+## CI and Containers (Gitea + Docker)
+- Use Gitea Actions for CI (`.gitea/workflows/`) with local parity via Docker Compose.
+- Perform work inside containers when appropriate; reserve host for git/tea and Docker orchestration.
+- Manage dependencies via Docker images; avoid host installs.
+- Use explicit container/network names and clean up artifacts (`down -v --remove-orphans`).
+## Audits
+- Run regular audits; prompt before release/tags. Save reports under `docs/audits/` and summarize in DevLogs.

templates/project/_shared/docker/compose.yml

@@ -0,0 +1,19 @@
+name: project
+
+services:
+  tests:
+    build:
+      context: ..
+      dockerfile: docker/test/Dockerfile
+    container_name: project-tests
+    working_dir: /work
+    volumes:
+      - ..:/work:Z
+    command: ["/bin/bash", "-lc", "scripts/test.sh"]
+    networks:
+      - project-net
+
+networks:
+  project-net:
+    name: project-net
+

templates/project/_shared/docker/test/Dockerfile

@@ -0,0 +1,11 @@
+FROM debian:bookworm-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       ca-certificates git bash curl jq yq \
+       bats \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /work
+

templates/project/_shared/scripts/test.docker.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+here="$(cd "$(dirname "$0")" && pwd)"
+root="$(cd "$here/.." && pwd)"
+
+compose_file="$root/docker/compose.yml"
+
+echo "[docker] Running tests via docker compose"
+docker compose -f "$compose_file" up --build --abort-on-container-exit --remove-orphans
+docker compose -f "$compose_file" down -v --remove-orphans
+

templates/project/_shared/scripts/test.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+if command -v bats >/dev/null 2>&1; then
+  exec bats "$ROOT_DIR/tests"
+fi
+
+echo "[info] bats not found; using internal test runner" >&2
+
+failures=0
+total=0
+
+for t in "$ROOT_DIR"/tests/*.sh; do
+  [ -f "$t" ] || continue
+  total=$((total+1))
+  echo "[run] $t"
+  if bash "$t"; then
+    echo "[ok]  $t"
+  else
+    echo "[fail] $t" >&2
+    failures=$((failures+1))
+  fi
+done
+
+echo "[summary] total=$total failures=$failures"
+if [ "$failures" -ne 0 ]; then
+  exit 1
+fi
+exit 0
+

tests/00_cli_guardrails.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+. "$ROOT_DIR/tests/helpers/assert.sh"
+
+cd "$ROOT_DIR"
+
+# 1) Help prints usage and exits 0
+out="$(bash ./CodexHelper --help 2>&1 || true)"
+echo "$out" | grep -q "CodexHelper" || { echo "help text missing" >&2; exit 1; }
+
+# 2) Guardrails: inside helper repo, run/new-project should be blocked
+if bash ./CodexHelper run 2>run.err 1>run.out; then
+  echo "run should fail in helper repo" >&2; exit 1
+fi
+grep -q "Only 'new-mode'" run.err || { echo "missing guardrail message for run" >&2; exit 1; }
+
+if bash ./CodexHelper new-project --mode Demo --name demo --path /tmp 2>np.err 1>np.out; then
+  echo "new-project should fail in helper repo" >&2; exit 1
+fi
+grep -q "Only 'new-mode'" np.err || { echo "missing guardrail message for new-project" >&2; exit 1; }
+
+exit 0

tests/01_new_mode.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+cd "$ROOT_DIR"
+
+mode="DemoMode"
+dir="modes/$mode"
+
+# Clean up from prior runs
+rm -rf "$dir"
+
+# Create new mode
+if ! bash ./CodexHelper new-mode --name "$mode" >nm.out 2>nm.err; then
+  echo "new-mode failed unexpectedly" >&2; exit 1
+fi
+
+[ -f "$dir/mode.md" ] || { echo "missing $dir/mode.md" >&2; exit 1; }
+[ -f "$dir/defaults.yaml" ] || { echo "missing $dir/defaults.yaml" >&2; exit 1; }
+
+# Running again without --force should fail
+if bash ./CodexHelper new-mode --name "$mode" >nm2.out 2>nm2.err; then
+  echo "new-mode should have failed on overwrite without --force" >&2; exit 1
+fi
+grep -qi "already exists" nm2.err || { echo "missing overwrite message" >&2; exit 1; }
+
+# With --force should succeed
+if ! bash ./CodexHelper new-mode --name "$mode" --force >nm3.out 2>nm3.err; then
+  echo "new-mode --force failed unexpectedly" >&2; exit 1
+fi
+
+exit 0
+

tests/helpers/assert.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+fail() { echo "ASSERTION FAILED: $*" >&2; return 1; }
+
+assert_eq() {
+  local expected="$1" actual="$2"; shift 2
+  if [ "$expected" != "$actual" ]; then
+    fail "expected='$expected' actual='$actual' $*"
+  fi
+}
+
+assert_contains() {
+  local haystack="$1" needle="$2"; shift 2
+  if ! grep -Fq -- "$needle" <<<"$haystack"; then
+    fail "did not find '$needle' in output"
+  fi
+}
+
+run_cmd() {
+  local out err rc
+  out="$({ err=$( { "$@"; } 2>&1 1>&3 ); rc=$?; echo "$err" >&2; echo $rc >&4; } 3>&1 4>&1)"
+}
+