feat: operating contract (AGENTS.md) + KB conformance linter (scripts/kb-lint.sh)

AGENTS.md

@@ -0,0 +1,79 @@
+# AGENTS.md — ~/.omp command center
+
+System-configuration command center for Frank's fleet: agent config, knowledge base,
+small system utilities, and (soon) dotfiles. You — the reader — are probably an agent
+running on Dankware with this repo as your working directory. Read
+`omp-docs/index.md` before you touch anything. This file is the operating contract;
+`omp-docs/` is the knowledge base (OKF v0.1 format: directory of markdown files
+with YAML frontmatter, spec at `omp-docs/references/okf-spec.md`).
+
+## What this repo is
+
+- The live agent-config directory AND a git repo pushed to Gitea
+  (`dank/command-center` on the Dankclaw instance). There is no staging copy:
+  **the checkout is the deployment.** Branch switches swap live config files out
+  from under the running agent — keep feature branches short-lived, and never end
+  a work session checked out on anything but `develop` or `main`.
+- Contents that belong here: `AGENTS.md`, `omp-docs/` (knowledge base),
+  `scripts/` (small system utilities), `agent/` + `plugins/` (harness config and
+  plugin manifests). Everything else under this directory is runtime state and is
+  gitignored on principle — see `.gitignore`. History must mean "the configuration
+  changed", not "the agent breathed".
+
+## Git-flow SDLC (full flow, from day one)
+
+- Work item = Gitea issue on `dank/command-center` (Gitea at 192.168.0.143:3000,
+  owner `dank`). Small fixes may go straight to a branch; anything with more than
+  one moving part gets an issue first.
+- Branch naming: `<type>/<issue#>-<slug>`, type ∈ feat|fix|docs|chore.
+  Release cuts: `release/X.Y.Z` from `develop`; hotfixes: `hotfix/<slug>` from `main`.
+- **Merge, never rebase**, when updating a branch against a moved main — Frank
+  dislikes the history rewrite. **Never merge a PR without an explicit OK from Frank.**
+- Merge into `develop` with `--no-ff` so feature arcs stay visible in history.
+- Releases: cut `release/X.Y.Z` from `develop`, verify, merge to `main`, tag
+  `vX.Y.Z`, back-merge `main` into `develop`. Tags are the deploy markers every
+  other machine pulls to.
+- Trash convention: never `rm` anything user-authored — move it to `.AGENTTRASH/`
+  (gitignored). Deletion is a pruning session with Frank present.
+
+## Secret gate (HARD rule)
+
+The pre-commit hook (`.githooks/pre-commit`, enabled via
+`git config core.hooksPath .githooks`) scans every staged diff for live-secret
+shapes (`sk-…`, `ghp_…`, `github_pat_…`, `glpat-…`, `xox…`, `AKIA…`, PEM headers,
+JWTs) and blocks the commit. Quarantine list — never tracked, ever: `auth.json`,
+`.env`, `trust.json`, `*.pem`, `*.key`, `identity*`. Deliberate override:
+`ALLOW_SECRETS=1 git commit …`. Remember why: a secret in a tracked file is a
+secret in every agent's context window on every machine that pulls this repo.
+
+## Machine facts (verify before trusting)
+
+| box | role | GPU | notes |
+|-----|------|-----|-------|
+| Dankware | dev laptop, never runs inference | Arc iGPU + RTX 4070 Max-Q (dGPU, non-unified) | 22 threads; mainline llama.cpp at `~/GitPackages/llama.cpp/build/bin/`; this repo lives here at `~/.omp` |
+| Dankclaw | bench target, runs the large serving model | Strix Halo APU — **unified memory** | ROCmFPX fork at `~/GitPackages/ROCmFPX/build-qwen38/bin/`; prod service `frank-default-large`, port 7770; ssh: `ssh dankclaw` |
+| Dankserver | FreeToken box | RTX 3090 dGPU — non-unified | runs `frank-default-small`; ssh: `ssh dankserver` |
+
+## Environment gotchas
+
+- Gitea API needs a token: `GITEA_TOKEN` env (gitignored `.env`). No `tea` CLI
+  installed anywhere. Remote URLs embed the token locally in `.git/config` — that
+  file is never pushed; it is not a substitute for the secret gate.
+- Passwordless sudo (`sudo -n`) works on Dankclaw and Dankserver for systemctl
+  verbs only; user units need no sudo at all.
+- SSH into both servers is BatchMode-capable from here:
+  `ssh -o BatchMode=yes dankclaw '<read-only command>'` — read-only probes are
+  always allowed; state changes on remote boxes are not, without a per-run OK.
+- `frank-default-large` on Dankclaw is a **production service** shared with this
+  repo's operator: never stop, mask, or restart it (or any production service on
+  any box) without an explicit, current, per-run OK from Frank.
+
+## File-organization doctrine (why this repo won't rot like ~/.pi did)
+
+- One concept, one file; directories get an `index.md` listing their contents —
+  that's the OKF contract, and it is also the anti-rot mechanism: nothing may
+  appear in a directory that its `index.md` doesn't list.
+- Root of the repo is capped: config, docs, scripts, harness dirs. A new
+  top-level entry requires a commit message that justifies itself.
+- Runtime state (dbs, logs, caches, sessions) is gitignored on principle — if you
+  feel the urge to commit one of those, stop and reread this section.