diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index eb8491d..6914fb0 100644 --- a/.gitea/workflows/ci.yml +++ b/.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 - diff --git a/collab/proposals/01-codexhelper.llm.md b/collab/proposals/01-codexhelper.llm.md index b9fd3d5..47c4037 100644 --- a/collab/proposals/01-codexhelper.llm.md +++ b/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 diff --git a/collab/proposals/01-codexhelper.md b/collab/proposals/01-codexhelper.md index 98189f5..c4b5c4a 100644 --- a/collab/proposals/01-codexhelper.md +++ b/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) diff --git a/collab/questions/02-branching.llm.md b/collab/questions/02-branching.llm.md new file mode 100644 index 0000000..72d729a --- /dev/null +++ b/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. + diff --git a/collab/questions/02-branching.md b/collab/questions/02-branching.md new file mode 100644 index 0000000..08d406d --- /dev/null +++ b/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. + diff --git a/docs/devlog/DEVLOG_LLM.md b/docs/devlog/DEVLOG_LLM.md index 3d06be2..982ad4d 100644 --- a/docs/devlog/DEVLOG_LLM.md +++ b/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 diff --git a/docs/wrapper.md b/docs/wrapper.md index 32e6bd3..014ba48 100644 --- a/docs/wrapper.md +++ b/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. diff --git a/meta/AGENTS.seed.llm.md b/meta/AGENTS.seed.llm.md index 71b444a..7daa0b6 100644 --- a/meta/AGENTS.seed.llm.md +++ b/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. diff --git a/meta/AGENTS.seed.md b/meta/AGENTS.seed.md index e280f10..a974ac5 100644 --- a/meta/AGENTS.seed.md +++ b/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. diff --git a/prompts/global/system.llm.md b/prompts/global/system.llm.md index 84e81b1..6976b79 100644 --- a/prompts/global/system.llm.md +++ b/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. diff --git a/prompts/global/system.md b/prompts/global/system.md index f95c9f5..535806a 100644 --- a/prompts/global/system.md +++ b/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). diff --git a/scripts/audit.sh b/scripts/audit.sh new file mode 100644 index 0000000..3a74db0 --- /dev/null +++ b/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" + diff --git a/templates/project/_shared/.gitea/workflows/ci.yml b/templates/project/_shared/.gitea/workflows/ci.yml index eb8491d..6914fb0 100644 --- a/templates/project/_shared/.gitea/workflows/ci.yml +++ b/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 - diff --git a/templates/project/_shared/AGENTS.md b/templates/project/_shared/AGENTS.md index 6184f1b..7395f52 100644 --- a/templates/project/_shared/AGENTS.md +++ b/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.