You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+27-3Lines changed: 27 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,15 +46,39 @@ The subject is **lowercase** after the colon. Title Case prose (`Add the thing`)
46
46
47
47
### Solo-owner merge policy
48
48
49
-
This repo runs with a single code owner (`* @constk` in `CODEOWNERS`). GitHub forbids a PR author from approving their own PR, so the standard "1 code-owner review" gate cannot be satisfied without an admin override. While in this state, the **intended workflow is**:
49
+
> **Transitional — only while this repo has a single code owner.** Standard practice is a code-owner review on every PR. The flow below exists because GitHub forbids self-approval, so a single-owner repo cannot satisfy the "1 code-owner review" gate any other way. The exemption is **removed** the moment a second collaborator with merge rights joins.
50
+
51
+
This repo currently runs with a single code owner (`* @constk` in `CODEOWNERS`). While in this state, the intended merge command is:
50
52
51
53
```sh
52
54
gh pr merge <N> --admin --squash --delete-branch
53
55
```
54
56
55
-
…for `feat:` / `fix:` / `chore:` PRs, and `--admin --merge` (preserves history) for `release:` PRs. The `enforce_admins: false` line in `.github/branch-protection/{develop,main}.json` is the documented escape hatch — admin merge here is the policy, not a deviation from it.
57
+
…for `feat:` / `fix:` / `chore:` PRs, and `--admin --merge` (preserves history) for `release:` PRs. The `enforce_admins: false` line in `.github/branch-protection/{develop,main}.json` is the documented escape hatch — admin merge here is the documented single-owner workaround, not bypass of the gates (every required status check still has to pass).
58
+
59
+
**When the exemption ends.** As soon as a second collaborator with merge rights is onboarded:
60
+
61
+
1. Drop the `--admin` flag from the merge command and adopt standard PR review.
62
+
2. Remove this entire subsection.
63
+
3. Update `CODEOWNERS` to add the new collaborator.
64
+
4. Flip `enforce_admins` to `true` in the branch-protection JSON for both branches. Leaving it `false` would keep the admin-bypass door open even after the single-owner workaround is no longer needed — defeats the point of removing the workaround.
65
+
66
+
All four changes land in a single PR.
67
+
68
+
## Line endings (Windows clones)
69
+
70
+
This repo enforces LF line endings via `.gitattributes` (`* text=auto eol=lf`)
71
+
and the pre-commit hygiene hook. If you cloned on Windows with
72
+
`core.autocrlf=true`, the first checkout after pulling the `.gitattributes`
73
+
change can leave the working tree out of sync with the index. Renormalise
74
+
once:
75
+
76
+
```sh
77
+
git add --renormalize .
78
+
git commit -m "chore: renormalise line endings"
79
+
```
56
80
57
-
When a second collaborator joins, drop the `--admin` flag and adopt standard PR review. Update this section + `CODEOWNERS` in the same PR.
> A production-quality coding harness for Python (FastAPI) + Vite/React/TypeScript projects. Designed for LLM-driven development: every gate — lint, types, architecture, security, eval — is enforced mechanically so code quality stays consistent across many human and AI contributors.
11
+
> Production-grade SDLC harness for human–LLM coding collaborations — keeping quality consistent regardless of who shipped the code. Python (FastAPI) + Vite/React/TypeScript, with every gate (lint, types, architecture, security, eval) enforced mechanically in CI, not by discipline.
12
12
13
13
## What ships
14
14
@@ -81,23 +81,31 @@ The scaffold's React page hits `/api/v1/health` on load and renders the version
The full stack — backend, frontend, Jaeger collector — boots with `docker compose up`. Hitting `/api/v1/health` once produces an OpenTelemetry trace exported via OTLP/gRPC; the span hierarchy is visible at <http://localhost:16686> under the `harness-python-react` service, with `agent_span(...)` attributes attached using only the keys constant-defined at the top of [`src/observability/spans.py`](src/observability/spans.py).
87
+
84
88
<!--
85
-
TODO (#28): one capture left — Jaeger trace.
89
+
Screenshot pending: docs/images/jaeger-trace.png
86
90
87
-
docs/images/jaeger-trace.png
88
-
With the full stack running (`docker compose up`), hit /api/v1/health
89
-
once, then open http://localhost:16686, select service
90
-
`harness-python-react`, click the most recent trace, screenshot the
91
-
span timeline.
91
+
Capture recipe (run once and commit the PNG to docs/images/):
92
+
1. docker compose up
93
+
2. curl http://localhost:8000/api/v1/health
94
+
3. open http://localhost:16686 -> select service "harness-python-react"
95
+
4. click the most recent trace
96
+
5. screenshot the span timeline, save as docs/images/jaeger-trace.png
92
97
93
-
When the PNG lands in docs/images/, replace this comment with a section
94
-
analogous to "Hello page" above.
98
+
When the PNG is committed, replace this whole comment with:
99
+
100
+
95
101
-->
96
102
97
103
## Why a harness
98
104
99
105
The differentiator isn't the scaffold — it's that every layer of the pipeline catches a different failure class **without relying on the human or LLM coder remembering to run anything**. The same posture protects code regardless of who wrote it.
100
106
107
+
> **Example.** An agent added `from src.tools import ...` inside `src.models` for type reuse. `lint-imports` failed CI — the `src.models depends on nothing in src/` contract broke — and pointed the next iteration at [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md). The type moved into `src.models` instead. Never shipped.
108
+
101
109
See [`docs/HARNESS.md`](docs/HARNESS.md) for the full umbrella. Highlights:
102
110
103
111
-**Pydantic `StrictModel` everywhere a contract crosses a seam** (rejects unknown keys at construction).
0 commit comments