Skip to content

Commit edfb4b1

Browse files
roxdaviroxroxdavirox
committed
yhwh: a self-referential build engine
Author markdown specs that hydrate into a typed semantic model, weave into a validated graph, and hatch into runtime artefacts (TypeScript, registries, Claude Code agents/skills). The compiler types itself: an idempotent self-describing codegen with type-erasure fixed point, provable byte-stable across sandboxes (P1..P4 in scripts/self-host-proof.ts). See docs/SELF-HOST-PROOF.md for the formal proof, docs/MANIFESTO.md for the philosophy, and docs/YHWH.md for the code map. Stack: Bun + TypeScript strict + zod + biome + husky.
0 parents  commit edfb4b1

193 files changed

Lines changed: 8780 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/hwh.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: hwh
2+
3+
on:
4+
push:
5+
branches: [main, master]
6+
pull_request:
7+
branches: [main, master]
8+
9+
jobs:
10+
lint-test-build:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- uses: oven-sh/setup-bun@v2
16+
with:
17+
bun-version: latest
18+
19+
- name: install
20+
run: bun install --frozen-lockfile
21+
22+
- name: format check
23+
run: bun run format:check
24+
25+
- name: biome check
26+
run: bun x biome check src/ scripts/ tools/ tests/
27+
28+
- name: typecheck
29+
run: bun run typecheck
30+
31+
- name: lint specs (good fixtures must be clean)
32+
run: bun run hwh lint specs/__fixtures__/good/
33+
34+
- name: canonical drift check (production specs)
35+
run: bun run hwh canonicalize specs/lib/ --check
36+
37+
- name: canonical drift check (good fixtures)
38+
run: bun run hwh canonicalize specs/__fixtures__/good/ --check
39+
40+
- name: lint specs (bad fixtures must fail and exit 1)
41+
run: |
42+
if bun run hwh lint specs/__fixtures__/bad/ ; then
43+
echo "expected bad fixtures to produce diagnostics — got exit 0"
44+
exit 1
45+
fi
46+
47+
- name: lint specs (cross-ref bad fixtures must fail and exit 1)
48+
run: |
49+
if bun run hwh lint specs/__fixtures__/bad-cross/ ; then
50+
echo "expected bad-cross fixtures to produce diagnostics — got exit 0"
51+
exit 1
52+
fi
53+
54+
- name: tests
55+
run: bun test --coverage
56+
57+
- name: fp audit
58+
run: bun run check-fp
59+
60+
- name: parity (handwritten vs meta-derived)
61+
run: bun run scripts/parity-handwritten-vs-meta.ts
62+
63+
- name: builder cross-check (project spec vs runtime)
64+
run: bun run scripts/builder-cross-check.ts
65+
66+
- name: tests with RUN_FROM_BOOTSTRAP=1 (legacy zod path)
67+
run: RUN_FROM_BOOTSTRAP=1 bun test
68+
69+
- name: strip-bootstrap test (runtime survives without per-kind handwritten zod)
70+
run: bun run scripts/strip-bootstrap-test.ts
71+
72+
- name: self-host proof (codegen reproduces across 3 generations + 2 sandboxes)
73+
run: bun run scripts/self-host-proof.ts
74+
75+
- name: lint meta-specs
76+
run: bun run hwh lint meta-specs/
77+
78+
- name: canonical drift check (meta-specs)
79+
run: bun run hwh canonicalize meta-specs/ --check
80+
81+
- name: build (no codegen)
82+
run: bun run hwh build specs/__fixtures__/good/
83+
84+
- name: build (codegen preview)
85+
run: bun run hwh build specs/__fixtures__/good/ --codegen

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
node_modules/
2+
dist/
3+
.DS_Store
4+
*.log
5+
.env
6+
.env.local
7+
.bun
8+
coverage/
9+
.wave/

‎.husky/pre-commit‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
#!/usr/bin/env sh
2+
export PATH="$HOME/.bun/bin:$PATH"
3+
cd "$(dirname "$0")/.."
4+
5+
bun x biome check src/ scripts/ tools/ tests/ || {
6+
echo "[hwh] biome check failed — commit blocked"
7+
exit 1
8+
}
9+
10+
bun run src/index.ts lint specs/lib/ || {
11+
echo "[hwh] lint failed — commit blocked"
12+
exit 1
13+
}
14+
15+
# Wave 2: canonical drift gate on staged spec files (skip intentionally-bad fixtures)
16+
STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.spec\.md$' | grep -v '__fixtures__/bad' || true)
17+
if [ -n "$STAGED" ]; then
18+
bun run src/index.ts canonicalize $STAGED --check || {
19+
echo "[hwh] canonical drift detected — run 'hwh canonicalize <files> --write' and re-stage"
20+
exit 1
21+
}
22+
fi

‎CLAUDE.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# CLAUDE.md — yhwh
2+
3+
A self-referential build model: Y · Hydrate · Weave · Hatch. Spec markdown → typed semantic model → validated graph → canonical artefacts in `dist/` and `~/.claude/`. CLI binary: `hwh`. Husky gate on every commit. Philosophy: `docs/MANIFESTO.md`. Formal proof of Y: `docs/SELF-HOST-PROOF.md`.
4+
5+
Design principles: alchemy-first (Result/Option/pipe), tacit / point-free, HOC-side-effects, Bun-first.
6+
7+
## Scope
8+
9+
- **Production specs:** `specs/lib/**/*.spec.md` — linted by husky gate, canonical source.
10+
- **Fixtures:** `specs/__fixtures__/{good,bad,bad-cross}/` — exercise the linter, intentionally break rules. Not linted by husky.
11+
- **Dogfood:** `specs/self/` — yhwh describing itself (optional, not required by gate).
12+
- Source format: frontmatter YAML + body MD + mermaid.
13+
- Kinds: `agent | skill | flow | entity | harness | ralph`.
14+
- Output: `dist/types.ts`, `dist/registry.json`, `dist/diagnostics.json`. Optional codegen to `~/.claude/agents/*.md` and `~/.claude/skills/*/SKILL.md` (idempotent, marker `<!-- hwh:managed -->`).
15+
16+
## Conventions
17+
18+
- Each spec has `kind`, `id` (kebab-case globally unique), `version` (monotonic semver), `status`, `owner`, `tags`.
19+
- Cross-refs always by `id` — never by path.
20+
- Tests in `tests/`, fixtures in `specs/__fixtures__/{good,bad}/`. Each `bad/` file violates exactly 1 rule (asserted via snapshot).
21+
- Dogfood: `specs/self/` describes yhwh itself (agent + skill + harness + ralph).
22+
23+
## CLI
24+
25+
```
26+
hwh lint <path> # 3 layers: schema, structural, cross-refs
27+
hwh lint --staged # husky integration
28+
hwh build <path> # full pipeline -> dist/
29+
hwh build <path> --codegen
30+
hwh new <kind> <id> # scaffold
31+
hwh doctor # diff specs vs artefacts in ~/.claude/
32+
hwh watch <path> # incremental re-lint
33+
```
34+
35+
## Tech
36+
37+
- Bun 1.1+, TS strict bundler, ESM.
38+
- `@tecnomancy/alchemy` (Result/pipe). No try/catch in new code (alchemy-exempt: `<reason>` on same line when unavoidable).
39+
- `zod` per kind. `yaml` for frontmatter. mdast custom (Bun native + regex for mermaid blocks in PoC; replace with `unified` when deps are justified).
40+
- Biome for format + lint TS.
41+
42+
## Do not
43+
44+
- Do not emit anything outside `dist/` or `~/.claude/` (explicit codegen only).
45+
- Do not create planning markdowns (only specs and fixtures).
46+
- No comments explaining what. Only why when non-obvious.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 roxdavirox
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)