governance: add .gitignore housekeeping and regular audits; implement audit script and CI step; update templates, proposal, and docs

.gitea/workflows/ci.yml

@@ -10,8 +10,10 @@ jobs:
     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
-

collab/proposals/01-codexhelper.llm.md

@@ -19,6 +19,8 @@
 - 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
@@ -33,6 +35,7 @@
   - 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
 

collab/proposals/01-codexhelper.md

@@ -43,7 +43,9 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes
 - 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.
 - 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.
+- 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`)
@@ -109,7 +111,8 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes
 - 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.
+- 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/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,54 @@
+# 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?
+
+## 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.
+
+## 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`.
+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?
+10) Require PR reviews and enforce Conventional Commits? Approve?
+11) Tagging: continue `YYYY-MM-DD-HHMM`. Should `main` tags correspond only to 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.
+
+## 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

@@ -198,3 +198,19 @@ This log is concise and structured for quick machine parsing and summarization.
   - 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

docs/wrapper.md

@@ -18,5 +18,6 @@ CLI
 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

@@ -17,3 +17,7 @@
 - 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

@@ -76,9 +76,14 @@ Customize this AGENTS.md to fit your project specifics while preserving the one-
 - 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.

prompts/global/system.llm.md

@@ -30,6 +30,9 @@
 -- 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.
@@ -37,3 +40,6 @@
 - 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.

prompts/global/system.md

@@ -95,6 +95,10 @@ You are a coding agent running in the Codex CLI (terminal-based). Be precise, sa
 - 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.
@@ -104,6 +108,11 @@ You are a coding agent running in the Codex CLI (terminal-based). Be precise, sa
 - 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).
 

scripts/audit.sh

@@ -0,0 +1,43 @@
+#!/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
+
+echo "[summary] failures=$failures"
+exit "$failures"
+

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

@@ -10,8 +10,10 @@ jobs:
     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/AGENTS.md

@@ -50,8 +50,13 @@ This file is copied by scaffolding into new projects. Edit to suit the project w
 ## 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.