chore(repo): clean root and move docs

- Move docs to docs/; keep areas for prompts only - Relocate Makefile to scripts/Makefile; update docs to use it - Move ci.Dockerfile to docker/ci.Dockerfile; update compose - Move commitlint config to .config and update hook - Remove root AGENTS.md (use area AGENTS.md)
2025-09-10 18:00:50 -05:00
parent d381070c75
commit a00b6a8782
15 changed files with 61 additions and 45 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,15 @@
+Repository Docs
+
+Purpose
+- Centralize human‑readable documentation. Area folders (COMMON/CTO/COO/CCO) are reserved for questions, proposals, and prompt modules.
+
+Key Documents
+- Git workflow: [git-workflow.md](git-workflow.md)
+- Local CI parity: [bootstrap-cicd.md](bootstrap-cicd.md)
+- Documentation style: [docs-style.md](docs-style.md)
+- Operational notes: [RESUME.md](RESUME.md), [TODO.md](TODO.md)
+- History: [history/BOOTSTRAP.md](history/BOOTSTRAP.md)
+
+Usage
+- Make targets moved to `scripts/Makefile`. Use `make -f scripts/Makefile <target>`.
+
--- a/docs/RESUME.md
+++ b/docs/RESUME.md
@@ -0,0 +1,53 @@
+Resume Guide
+
+Purpose
+- Quick checklist to pick up work after restarting Codex CLI with expanded permissions.
+
+Branches on remote
+- main (default), integration, release, bootstrap, bootstrap-cicd
+
+1) Pull latest
+- git fetch --all --prune
+- git switch bootstrap && git pull
+- git switch bootstrap-cicd && git pull
+- git switch integration && git pull
+
+2) Ensure Docker is available
+- Start Docker Desktop/daemon as needed
+
+3) Install hooks locally
+- make -f scripts/Makefile hooks-setup
+
+4) Run local checks (Docker-only)
+- git switch bootstrap && make -f scripts/Makefile quick && make -f scripts/Makefile build
+- git switch bootstrap-cicd && make -f scripts/Makefile quick && make -f scripts/Makefile build
+- Optional full pass: make -f scripts/Makefile check
+
+5) Open PRs (when branches are green locally)
+- bootstrap → integration: https://git.knownelement.com/KNEL/LLMScaffolding/pulls/new/bootstrap
+- bootstrap-cicd → integration: https://git.knownelement.com/KNEL/LLMScaffolding/pulls/new/bootstrap-cicd
+
+6) Merge to integration
+- Use squash merge, allow auto-merge on green where configured
+
+7) Release to main
+- Open PR: integration → main (require 1 approval)
+- After merge, tag manually (until CI runners are enabled):
+  - git switch main && git pull
+  - TAG=$(date -u +"v%Y.%m.%d-%H%M")
+  - git tag -a "$TAG" -m "Release $TAG"
+  - git push origin "$TAG"
+- Optional: fast-forward release branch pointer:
+  - git branch -f release main && git push -f origin release
+
+8) Docs & parity
+- Git workflow: [docs/git-workflow.md](git-workflow.md)
+- Local CI parity: [docs/bootstrap-cicd.md](bootstrap-cicd.md)
+
+9) Defer CI enablement for two weeks
+- Track in [docs/TODO.md](TODO.md): Revisit enabling runners and protected checks on 2025-09-24
+
+10) Next tasks
+- Answer any outstanding questions in questions/*
+- On approval, implement further proposals and update instructions/*
+
--- a/docs/TODO.md
+++ b/docs/TODO.md
@@ -0,0 +1,35 @@
+TODO
+
+- Git workflow
+  - [x] Questions gathered and answered
+  - [x] Proposal iteration 2 drafted
+  - [x] Finalize approval and capture in [docs/git-workflow.md](git-workflow.md)
+
+- Branches
+  - [x] Create integration, release, bootstrap from main
+  - [x] Push bootstrap to origin
+  - [ ] Decide whether to maintain a fast-forwarded release branch to the latest tag
+
+- CI/CD bootstrap
+  - [x] Create branch bootstrap-cicd from main
+  - [x] Add questions at [questions/bootstrap-cicd.md](../questions/bootstrap-cicd.md)
+  - [x] Draft proposal based on answers
+  - [x] Implement parity tooling: scripts/ci, docker/ci.Dockerfile, docker/ci.compose.yml
+  - [x] Add .gitea/workflows: ci.yml, release.yml, nightly.yml
+  - [x] Add commitlint.config.cjs, Makefile
+  - [ ] Optional: add .pre-commit-config.yaml (defer for now)
+  - [ ] Optional: add CODEOWNERS
+
+- Protections & settings (in Gitea UI)
+  - [ ] Protect main and release/* with required checks
+  - [ ] Leave integration unprotected; allow auto-merge on green
+  - [ ] Require 1 approval for integration→main
+  - [ ] Revisit enabling CI and protections after runners are ready (target: 2025-09-24)
+
+- Releases
+  - [ ] Tag format vYYYY.MM.DD-HHMM (UTC) in release workflow
+  - [ ] Optional: fast-forward release branch to latest tag
+
+- Docs
+  - [ ] Write [docs/engineering/git-workflow.md](engineering/git-workflow.md) with diagrams and examples
+
--- a/docs/bootstrap-cicd.md
+++ b/docs/bootstrap-cicd.md
@@ -0,0 +1,21 @@
+Local CI Parity & Bootstrap
+
+Purpose
+- Provide a portable CI toolchain via a Dockerized image and compose file so that format/lint/build checks run identically locally and in CI.
+
+Components
+- `docker/ci.Dockerfile` – builds the CI image with shellcheck, shfmt, hadolint, actionlint, yamllint, Node tools.
+- `docker/ci.compose.yml` – runs the CI container mounting the repo at `/workspace`.
+- `scripts/ci` – wrapper for phases: `format`, `lint`, `build`, `test`, `security`, `all`.
+- Git hooks – `.githooks/*` installed via `scripts/setup-hooks`.
+
+Usage
+- Install hooks: `make -f scripts/Makefile hooks-setup`
+- Quick checks: `make -f scripts/Makefile quick` (format + lint)
+- Full pass: `make -f scripts/Makefile check` (all phases)
+
+Notes
+- Pre-commit hook runs format/lint and commit message checks.
+- Pre-push hook runs build/test/security placeholders.
+- CI workflow runs on integration and protected branches when runners are enabled.
+
--- a/docs/docs-style.md
+++ b/docs/docs-style.md
@@ -0,0 +1,8 @@
+Documentation Style Guide
+
+- When referencing another Markdown file in this repo, use a relative link so it is clickable in Gitea. Example: [docs/git-workflow.md](git-workflow.md).
+- Keep titles concise and descriptive; use sentence case unless a proper noun.
+- Prefer short bullets (one point per line). Merge related points.
+- Use backticks for commands, file paths, env vars, and code identifiers.
+- Make documents actionable: lead with outcomes, then steps, then background.
+
--- a/docs/git-workflow.md
+++ b/docs/git-workflow.md
@@ -0,0 +1,38 @@
+Git Workflow – Finalized Instructions
+
+Scope
+- Applies across projects. Contributors work via branches/PRs. CI/CD is Gitea‑native.
+
+Branches
+- main: production; default branch. Protected.
+- integration: development (unprotected; merges auto on green).
+- Working branches: `feature/<topic>`, `fix/<topic>`, `chore/<topic>` from integration.
+- Hotfix: `hotfix/<date>` from main; PR back to main, then forward‑merge into integration.
+- Release branch: ephemeral or lightweight `release/*`. Protect when present; may fast‑forward to latest tag via CI.
+
+Merges & Approvals
+- Feature → integration: squash merge; auto‑merge on green (no human approval). Self‑merge allowed.
+- integration → main: squash merge; require 1 approval; self‑merge not allowed.
+- Force pushes disabled on protected branches (`main`, `release/*`); PRs required.
+
+Commit Style
+- Conventional Commits for PR titles and commit messages.
+
+Versioning & Tags
+- Calendar tags: `vYYYY.MM.DD-HHMM` (UTC) for traceability.
+- Release tags: semantic or milestone tags (e.g., `v0.0.1-Bootstrap`).
+
+Release Flow
+1) Feature branches PR into integration; checks pass → auto‑merge.
+2) PR integration → main; 1 approval required; on merge, deploy and tag release.
+3) Optional: CI fast‑forwards a `release` branch pointer to the new tag.
+
+Protected Checks (enable when runners are ready)
+- On protected branches (`main`, `release/*`): ci / lint, ci / build, ci / commitlint. Add ci / test and ci / security when introduced.
+
+CODEOWNERS
+- Keep minimal; require review for integration → main.
+
+Notes
+- No secrets in this base repo. Future repos should integrate Vault for secrets.
+
--- a/docs/history/BOOTSTRAP.md
+++ b/docs/history/BOOTSTRAP.md
@@ -0,0 +1,16 @@
+The purpose of this repository is to create a re-usable set of prompts for use in AI chat intefaces and with agentic AI.
+
+This file is being created at the very start of the repository in an attempt to provide full traceability. It will be passed to codex as a prompt.
+
+Codex instructions:
+
+- Remain in planning mode only. Ask questions and gather data.
+- Create a propsoals directory and write out proposals to it for me to review and approve.
+- Do not undertake any work unless I ask you for a proposal and I approve the proposal.
+- Ask questions with numbers and allow them to be answered like 1:y 2:n or (for multiple choice) 1:a 2:b and so forth.
+- Keep the chat message output short. Use proposal files that I can view in my editor (vsCode). 
+- The directory you are in is one level up from the git repository. This is so that git worktree can be used, to help mitigate issues with git branching. The repository is in a child directory called LLMScaffolding.
+
+Your first concreate action:
+- Please help me establish a git workflow (via the proposal/approval process I have outlined). This workflow should follow best practices, it should presume the use of CI/CD via Gitea (Gitlab/Github are banned, never produce anything for those platforms).
+