**Bootstrap CI/CD Proposal (Phase 1)**

- Scope: Local developer parity via Docker-first tooling and hooks, minimal CI placeholders (no runners required yet). Applies to this repo (docs/scripts/docker-compose), with an easy path to template for others.

**Checks To Implement Now (Local via Docker)**

- Stacks: shell, Dockerfiles/Compose, Markdown/Docs, YAML; Python/Node optional later.
- Formatters/Linters:
  - shell: shfmt + shellcheck
  - docker: hadolint
  - markdown: markdownlint + prettier
  - yaml: yamllint + actionlint (for workflows)
- Tests: none for now (lint-only baseline).
- Security: skip for this repo now.

**Execution Model**

- Docker-only: all checks run inside a pinned `ci` image. Host only orchestrates Docker/Compose.
- Single entrypoint: `scripts/ci` with phases: `format`, `lint`, `build` (compose validate), `test` (no-op for now), `security` (no-op), `all`.
- Compose file: `docker/ci.compose.yml` defines `ci` service that mounts repo and executes `scripts/ci <phase>`.

**Hooks Parity**

- Provide Git hooks via pre-commit framework and native Git hooks:
  - pre-commit: run `format`, `lint`, and commit message check (Conventional Commits).
  - pre-push: run `build` (compose config validation) and keep `test`/`security` as no-ops for now.
- Commit message style: Conventional Commits via `commitlint` rule-set; enforce in CI later and locally via `commit-msg` hook.

**Minimal CI (Deferred Enablement)**

- Workflows will be prepared but can stay disabled until runners are available:
  - `.gitea/workflows/ci.yml`: mirrors local `lint` + `build` using the same `ci` image; triggered on PRs when enabled.
  - `.gitea/workflows/release.yml`: on `main` merges, tags with `vYYYY.MM.DD-HHMM` and (optionally) creates release notes; can be enabled later.
  - `.gitea/workflows/nightly.yml`: scheduled dependency/lint refresh; optional for later.
- All jobs execute inside the `ci` container image; no host package installs.

**Caching & Matrix**

- Matrix: single Linux image for now.
- Caching: enable Docker layer cache when CI runners are available; no special local caching required.

**Concurrency & Timeouts (defaults for later)**

- Cancel in-progress on same ref: enabled for PRs.
- Job timeout: 30 minutes.

**Protected Check Names (for later enforcement)**

- `ci / lint`, `ci / build`, `ci / commitlint`. Tests/Security can be added when introduced.

**Files To Add (upon approval)**

- `scripts/ci` (bash) — phases and Docker/host detection (host executes Docker only).
- `ci.Dockerfile` — pinned versions: shfmt, shellcheck, hadolint, yamllint, markdownlint-cli, prettier, actionlint, commitlint.
- `docker/ci.compose.yml` — `ci` service to run checks.
- `.pre-commit-config.yaml` — wire to `scripts/ci` phases; enable `commit-msg` hook for commitlint.
- `commitlint.config.cjs` — Conventional Commits rules.
- `.gitea/workflows/ci.yml`, `release.yml`, `nightly.yml` — prepared but can be disabled until runners are ready.
- `Makefile` — `check`, `quick`, `lint`, `format`, `build` targets mapping to scripts.

**Rollout Plan**

1) Implement local tooling and hooks on `bootstrap-cicd`.
2) Document quickstart in [docs/engineering/ci-cd.md](docs/engineering/ci-cd.md).
3) Later: enable Gitea workflows when runners are ready; add protected checks.
4) Optionally expand with tests/security scanners and language stacks per repo.

If this matches your intent, I will scaffold the above on `bootstrap-cicd` and then capture the finalized process in [COMMON/bootstrap-cicd.md](COMMON/bootstrap-cicd.md).