docs: add architecture and full audit; fill project templates (.gitignore, scripts/test.sh) per audit findings

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

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

templates/project/_shared/.gitignore

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

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
+