From bae62d94dc667721863d829d2aed8780608c1d67 Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 17 Sep 2025 11:11:07 -0500 Subject: [PATCH] docs: add architecture and full audit; fill project templates (.gitignore, scripts/test.sh) per audit findings --- docs/architecture.md | 34 +++++++++++++++++++++++ docs/audits/2025-09-17-audit.llm.md | 29 +++++++++++++++++++ docs/audits/2025-09-17-audit.md | 34 +++++++++++++++++++++++ docs/devlog/DEVLOG_LLM.md | 9 ++++++ templates/project/_shared/.gitignore | 7 +++++ templates/project/_shared/scripts/test.sh | 32 +++++++++++++++++++++ 6 files changed, 145 insertions(+) create mode 100644 docs/architecture.md create mode 100644 docs/audits/2025-09-17-audit.llm.md create mode 100644 docs/audits/2025-09-17-audit.md create mode 100644 templates/project/_shared/.gitignore create mode 100644 templates/project/_shared/scripts/test.sh diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..f4e80b8 --- /dev/null +++ b/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//{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//` + +- 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. + diff --git a/docs/audits/2025-09-17-audit.llm.md b/docs/audits/2025-09-17-audit.llm.md new file mode 100644 index 0000000..a4e7dc3 --- /dev/null +++ b/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. + diff --git a/docs/audits/2025-09-17-audit.md b/docs/audits/2025-09-17-audit.md new file mode 100644 index 0000000..b60b331 --- /dev/null +++ b/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. + diff --git a/docs/devlog/DEVLOG_LLM.md b/docs/devlog/DEVLOG_LLM.md index f0b5f05..3d06be2 100644 --- a/docs/devlog/DEVLOG_LLM.md +++ b/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 diff --git a/templates/project/_shared/.gitignore b/templates/project/_shared/.gitignore new file mode 100644 index 0000000..cb48cde --- /dev/null +++ b/templates/project/_shared/.gitignore @@ -0,0 +1,7 @@ +# Generated runs and logs +runs/ + +# OS files +.DS_Store +Thumbs.db + diff --git a/templates/project/_shared/scripts/test.sh b/templates/project/_shared/scripts/test.sh new file mode 100644 index 0000000..5b5ba70 --- /dev/null +++ b/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 +