docs: capture finalized instructions for git workflow and bootstrap CI/CD; update TODO with runner revisit date

TODO.md

@@ -3,7 +3,7 @@ TODO
 - Git workflow
   - [x] Questions gathered and answered
   - [x] Proposal iteration 2 drafted
-  - [ ] Finalize approval and capture in instructions/git-workflow.md
+  - [x] Finalize approval and capture in instructions/git-workflow.md
 
 - Branches
   - [x] Create integration, release, bootstrap from main
@@ -13,15 +13,18 @@ TODO
 - CI/CD bootstrap
   - [x] Create branch bootstrap-cicd from main
   - [x] Add questions at questions/bootstrap-cicd.md
-  - [ ] Draft proposal based on answers
+  - [x] Draft proposal based on answers
-  - [ ] Implement parity tooling: scripts/ci, ci.Dockerfile, docker/ci.compose.yml
+  - [x] Implement parity tooling: scripts/ci, ci.Dockerfile, docker/ci.compose.yml
-  - [ ] Add .gitea/workflows: ci.yml, release.yml, nightly.yml
+  - [x] Add .gitea/workflows: ci.yml, release.yml, nightly.yml
-  - [ ] Add commitlint.config.cjs, .pre-commit-config.yaml, Makefile, CODEOWNERS
+  - [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 integration with required checks
   - [ ] Enable auto-merge on green for feature→integration
   - [ ] 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
@@ -29,4 +32,3 @@ TODO
 
 - Docs
   - [ ] Write docs/engineering/git-workflow.md with diagrams and examples
-

instructions/bootstrap-cicd.md

@@ -0,0 +1,36 @@
+Bootstrap CI/CD – Finalized Instructions (Phase 1)
+
+Goal
+- Provide Docker‑only local checks and Git hooks with parity to future CI. CI workflows are prepared but may remain disabled until runners are ready.
+
+Requirements
+- Docker + Docker Compose v2 on the development machine. No host packages beyond Docker are required.
+
+Local Checks
+- Entry point: `scripts/ci <phase>` where phase ∈ {format, lint, build, test, security, all}.
+- Always runs inside the ci container using `docker/ci.compose.yml`.
+- Tools pinned in `ci.Dockerfile`: shfmt, shellcheck, hadolint, yamllint, actionlint, prettier, markdownlint, commitlint.
+
+Hooks
+- Install hooks: `make hooks-setup` (copies .githooks/* into .git/hooks).
+- pre-commit: runs format + lint.
+- commit-msg: runs commitlint (Conventional Commits).
+- pre-push: runs build; test and security are present but currently no‑ops.
+
+Convenience Targets
+- `make quick` → format + lint.
+- `make check` → all phases.
+- `make build` → compose validation.
+
+CI (Prepared, optional enablement later)
+- .gitea/workflows/ci.yml: builds ci image; runs lint + build.
+- .gitea/workflows/release.yml: on pushes to main, creates annotated tag vYYYY.MM.DD-HHMM (UTC).
+- .gitea/workflows/nightly.yml: nightly lint run.
+- All jobs run inside the ci image; no runner host package installs.
+
+Protected Checks (when CI is enabled)
+- Protect: ci / lint, ci / build, ci / commitlint. Add ci / test and ci / security when they exist.
+
+Future Extensions
+- Add tests/security phases per repo stack; enable CI branch protections once runners are ready; optionally add pre-commit framework as an alternative to native hooks.
+

instructions/git-workflow.md

@@ -0,0 +1,37 @@
+Git Workflow – Finalized Instructions
+
+Scope
+- Applies to this repo. Users typically consume tagged releases; contributors work via branches/PRs. CI/CD config is Gitea‑native; no GitHub/GitLab.
+
+Branches
+- main: production; default branch.
+- integration: development. Equivalent to develop.
+- 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: not long‑lived. Optionally maintain a lightweight release branch fast‑forwarded to the latest tag via CI.
+
+Merges & Approvals
+- Feature → integration: squash merge; bot 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; PRs required.
+
+Commit Style
+- Conventional Commits for PR titles and commit messages.
+
+Versioning & Tags
+- Calendar tags: vYYYY.MM.DD-HHMM (UTC). Annotated tags only on main after release.
+
+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 (to enable when runners are ready)
+- ci / lint, ci / build, ci / commitlint. Add ci / test and ci / security if/when introduced.
+
+CODEOWNERS
+- Keep minimal; require your review for integration → main.
+
+Notes
+- No secrets required for this repo. Future repos should integrate Vault for secrets.
+