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: .claude/rules.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,13 +14,13 @@ These rules apply to every contribution to Vernacular, whether by a human or a C
14
14
15
15
5.**30-day dependency cooldown.** No direct or transitive dependency younger than 30 days. Enforced by `.npmrc``minimum-release-age=43200`. See ADR-0010.
16
16
17
-
6.**Local knowledge graph.** Significant architectural changes are summarized as ADRs under the local `docs/knowledge/` tree (gitignored) so Claude has fast context recovery in future sessions. ADRs are a Claude-side cache, not a committed artifact; the authoritative source is the design specification.
17
+
6.**Knowledge graph.** Significant architectural changes are summarized as ADRs under `docs/knowledge/decisions/`, committed and authoritative alongside the design specification, so future sessions and contributors recover context fast. The generated indices (`INDEX.md`, `index.json`) are a gitignored local cache; regenerate them with `pnpm knowledge:index`.
18
18
19
19
7.**No Co-Authored-By trailers.** Project setting `includeCoAuthoredBy: false` is the source of truth. Commit messages should never contain `Co-Authored-By: Claude` or similar.
20
20
21
21
8.**No em-dashes (`—`) in newly composed text.** Rephrase with commas, parentheses, or colons. Downloaded canonical text (Contributor Covenant, license texts) is exempt.
10.**No cryptic internal identifiers in branch names, commit messages, file names, or persisted document text.** Use descriptive English names. Stable cross-industry conventions like `ADR-NNNN` are fine.
|`CLAUDE.md` (repo-layout section) | "The source-layer directories under the repo root are placeholders today" | All six layers carry substantial production code; `src/` is a real bootstrap. Trust `ARCHITECTURE.md`. |
112
-
|`README.md` line 8 | "Status: early development (Phase 0). Not yet usable as a floor planner." | v0.3.0 tagged 2026-06-27; package version 0.3.1; working 2D editor and 3D preview. |
113
-
|`.claude/rules.md` rule 6 | ADRs are a gitignored Claude-side cache, "not a committed artifact" | 146 ADR files are committed under `docs/knowledge/decisions/` and are authoritative alongside the spec; only the generated index files stay gitignored. `CLAUDE.md`'s knowledge-graph section has the correct story. |
114
-
|`.claude/rules.md`, `ARCHITECTURE.md` (citations) | Cite ADR-0002, ADR-0009, ADR-0010, ADR-0011, ADR-0013 | Those files are absent from `docs/knowledge/decisions/` (as are 0008, 0014, 0015), and ADR-0076 and ADR-0081 each exist twice under different slugs. See vernacular-failure-archaeology for the collision history and vernacular-docs-and-writing for numbering practice. |
115
-
| ADR-0007, "Current implementation state" | "The aggregating `AssetRegistry` ... not implemented yet" | Implemented at `storage/assets/asset-registry.ts`; the decision is unchanged, the status section predates it. |
116
-
| ADR-0012 | Boundaries lint "starts enforcing as soon as core/ and friends appear" | Superseded by ADR-0017: the config was a broken no-op until repaired and guarded by the fitness test. |
|`.claude/rules.md`, `ARCHITECTURE.md` (citations) | Cite ADR-0002, ADR-0009, ADR-0010, ADR-0011, ADR-0013 | Those files are absent from `docs/knowledge/decisions/` (as are 0008, 0014, 0015), and ADR-0076 and ADR-0081 each exist twice under different slugs. See vernacular-failure-archaeology for the collision history and vernacular-docs-and-writing for numbering practice. |
112
+
| ADR-0007, "Current implementation state" | "The aggregating `AssetRegistry` ... not implemented yet" | Implemented at `storage/assets/asset-registry.ts`; the decision is unchanged, the status section predates it. |
113
+
| ADR-0012 | Boundaries lint "starts enforcing as soon as core/ and friends appear" | Superseded by ADR-0017: the config was a broken no-op until repaired and guarded by the fitness test. |
117
114
118
115
## Common mistakes
119
116
@@ -144,4 +141,4 @@ Verified against the repo at commit 6b7d74c6 on 2026-07-05. Issue and PR states
144
141
- Reconciler parity issues: `for n in 434 437 449 469 476 479; do gh issue view $n --json number,state -q '"\(.number) \(.state)"'; done`
145
142
- Scene baseline families on disk: `ls e2e/tests/scene-visual-regression.spec.ts-snapshots/`
146
143
- Period resolution chain: `cat core/architecture-era/resolve-period.ts`
147
-
-Stale-doc claims: `grep -n placeholders CLAUDE.md`, `sed -n '8p' README.md`, and rule 6 in `.claude/rules.md`
Copy file name to clipboardExpand all lines: .claude/skills/vernacular-build-and-env/SKILL.md
-1Lines changed: 0 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -139,7 +139,6 @@ Verified precisely on 2026-07-05: `playwright.config.ts` routes specs with the u
139
139
140
140
## Stale committed docs: trust the configs, not these lines
141
141
142
-
- CLAUDE.md says the source-layer directories are "placeholders today". Stale: `core/`, `editor/`, `bridge/`, `engine/`, `storage/`, `app/` all carry substantial code as of 2026-07-05.
143
142
- CONTRIBUTING.md says "Node.js 20 or newer" and "the smoke test in src/App.test.tsx is the only test". Both stale: engines require Node >=22.18.0 and the test tree is large.
144
143
-`docs/specs/2026-06-01-vernacular-design.md` describes a 15-day cooldown (21600) with no exclusions. Superseded by `.npmrc`: 43200 minutes and 56 exclusions.
145
144
-`.npmrc` cites ADR-0013 for the exclusions; the ADR file does not exist in `docs/knowledge/decisions/` as of 2026-07-05.
Copy file name to clipboardExpand all lines: .claude/skills/vernacular-change-control/SKILL.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -89,7 +89,7 @@ Notes that matter in practice:
89
89
90
90
## Commit conventions
91
91
92
-
- Conventional Commits, enforced by commitlint via the `.husky/commit-msg` hook. Allowed types (`commitlint.config.js` type-enum, the authoritative list): `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `style`, `perf`, `build`, `ci`. Note: `.claude/rules.md`rule 9 lists only seven types; the commitlint config is what actually gates, so trust it. Subject must not be start-case, pascal-case, or upper-case. Body and footer lines over 100 characters draw a warning.
92
+
- Conventional Commits, enforced by commitlint via the `.husky/commit-msg` hook. Allowed types (`commitlint.config.js` type-enum, the authoritative list): `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `style`, `perf`, `build`, `ci`. Rule 9 in `.claude/rules.md` lists the same ten; the commitlint config is what actually gates. Subject must not be start-case, pascal-case, or upper-case. Body and footer lines over 100 characters draw a warning.
93
93
- No `Co-Authored-By` trailers, ever (`.claude/rules.md` rule 7; `/review` mechanically counts them and requires zero).
94
94
- No em-dash characters in newly composed text (rule 8).
95
95
- Subjects describe the change in plain English. No milestone codes or internal shorthand (rule 10), no third-party product names (rule 11).
@@ -118,7 +118,7 @@ An ADR is the unit of architectural memory, committed under `docs/knowledge/deci
118
118
-**Spec changes require an ADR.** Never modify `docs/specs/` without a corresponding ADR explaining the change (CLAUDE.md "Things never to do").
119
119
-**Architectural changes ship their ADR with the change**, in the same PR. `/review` flags PRs that touch architectural surfaces (new `core/` types, registries, layer-crossing patterns) without touching `docs/knowledge/`.
120
120
- Before proposing an architectural change, check for an existing ADR that already settled the question (`/knowledge <query>`, or grep `docs/knowledge/decisions/`).
121
-
-Doc staleness warning: `.claude/rules.md` rule 6 still calls ADRs an uncommitted local cache. Reality (and CLAUDE.md): `docs/knowledge/decisions/` is committed and authoritative alongside `docs/specs/`; only the generated `INDEX.md` / `index.json` stay gitignored.
121
+
-`docs/knowledge/decisions/` is committed and authoritative alongside `docs/specs/`; only the generated `INDEX.md` / `index.json` stay gitignored. Rule 6 in `.claude/rules.md` and CLAUDE.md both state this.
122
122
123
123
### ADR numbering discipline
124
124
@@ -154,7 +154,7 @@ Source: `.claude/rules.md` (17 rules). The table states each rule, why it exists
154
154
| 3 | All mutations via `dispatch(command)` at the bridge boundary | The framework captures the inverse for undo/redo (ADR-0005); a mutation outside dispatch is un-undoable state corruption |
155
155
| 4 | Asset references are content-addressed `(scope, contentHash)`| Dedupe, integrity, and cache-safety (ADR-0007) |
156
156
| 5 | 30-day dependency cooldown (`.npmrc``minimum-release-age=43200`), exact pins only, frozen lockfile | Supply-chain defense: compromised or typosquatted releases are usually caught and yanked within days, so refusing anything younger than 30 days sidesteps the window (rationale in `.npmrc` comments). Exclusions exist for coordinated-release monorepos (rollup natives, typescript-eslint, babel); the cited ADR-0013 file is absent on disk, the `.npmrc` comments carry the reasoning. Never use `^`/`~` ranges |
157
-
| 6 | Knowledge graph: architectural changes get ADRs | Fast context recovery for future sessions. The rule text in `.claude/rules.md` is stale (says gitignored cache); ADR decisions ARE committed|
157
+
| 6 | Knowledge graph: architectural changes get ADRs | Fast context recovery for future sessions. ADR decisions are committed under `docs/knowledge/decisions/`, authoritative alongside the spec |
158
158
| 7 | No `Co-Authored-By` trailers | Owner policy; `/review` counts and requires zero |
159
159
| 8 | No em-dashes in newly composed text | House language policy; also the mechanical floor of the humanizer rule. Downloaded canonical text is exempt |
160
160
| 9 | Conventional Commits | Mechanical enforcement via commitlint; the audit's commit classification depends on types being honest |
@@ -186,7 +186,7 @@ Source: `.claude/rules.md` (17 rules). The table states each rule, why it exists
186
186
7. Editing `docs/specs/` without an ADR in the same change.
187
187
8. Running `/adr` from two concurrent branches. Both compute the same next number; pre-assign instead.
188
188
9. Squash-merging a PR. It destroys the red-green-blue history the whole audit trail is built on.
189
-
10. Believing stale docs: CLAUDE.md still calls the source layers placeholders (six layers hold roughly 94K LOC as of 2026-07-05), CONTRIBUTING.md still says the App smoke test is the only test, `.claude/rules.md` rule 6 predates committed ADRs, and rule 9's type list is shorter than the commitlint enum. When a doc and a config disagree, the config gates.
189
+
10. Believing stale docs: CONTRIBUTING.md still says the App smoke test is the only test, lists 7 commit types, and claims the package version stays at 0.0.0 until 1.0. When a doc and a config disagree, the config gates.
Copy file name to clipboardExpand all lines: .claude/skills/vernacular-config-and-flags/SKILL.md
-1Lines changed: 0 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -225,7 +225,6 @@ Consumed by `.github/workflows/release-please.yml` on push to main. Release oper
225
225
- Widening a suite-level screenshot tolerance to silence one flaky capture.
226
226
- Treating the weekly Stryker `break: 50` as a PR gate (it is not), or treating Lighthouse warn-level scores as failures (only accessibility at 0.9 errors).
227
227
- Expecting crash recovery on the IndexedDB fallback: the `.house-autosave/` sidecar needs OPFS.
228
-
- Trusting CLAUDE.md's line that the source layers are placeholders: stale. All six layers are live code, and that is where these flags live.
229
228
- Citing ADR-0013 for the cooldown exclusions: the file does not exist as of 2026-07-05; the `.npmrc` comments carry the rationale.
Note on stale docs: CLAUDE.md still calls the source-layer directories placeholders. That is wrong; engine/, bridge/, editor/, storage/, app/, core/ are live code and several entries below point into them.
0 commit comments