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

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.
+

docs/devlog/DEVLOG_LLM.md

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

meta/AGENTS.seed.llm.md

@@ -5,7 +5,8 @@
 - 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.
+- 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.

meta/AGENTS.seed.md

@@ -39,7 +39,8 @@ Note: This is a template copied into generated projects. Customize as needed for
 - 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.
+- 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.

prompts/global/system.llm.md

@@ -52,4 +52,8 @@
 -- 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.
+- 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

@@ -35,7 +35,12 @@ You are a coding agent running in the Codex CLI (terminal-based). Be precise, sa
 - 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.
+- 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.

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/AGENTS.md

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