Skip to content

Commit 97b5a79

Browse files
refactor(standards): remove duplicate docs/standards, load from ~/.claude/rules (#320)
docs/standards/ duplicated the Claude rules in ~/.claude/rules/ and had drifted (8 files older than the live rules, 6 files repo-only). The global location is now the single source: - the 6 repo-only standards (java, csharp, django, flask, spring-boot, TOOL-OPTIMIZATION) moved to ~/.claude/rules/ with paths frontmatter - load_framework_standards() and load_language_standards() read ~/.claude/rules/ via _STANDARD_SELECTOR_RULES_DIR - TestRuleFilePaths reads ~/.claude/rules/ and skips where absent - CLAUDE.md, README.md, docs/README.md, ADR-006, orchestration_prompt.md and CHANGELOG.md updated; README docs/ count 253 -> 201 Supersedes the repo-side part of #319 (06-10 paths frontmatter now lives only in ~/.claude/rules). Closes #320 Refs #319 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013u46KPovSoGvJBAxyJiFoX
1 parent 9e1c804 commit 97b5a79

60 files changed

Lines changed: 33 additions & 26203 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.

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
99

1010
## [Unreleased]
1111

12+
### Removed
13+
- **`docs/standards/` (52 files).** It duplicated the Claude rules in `~/.claude/rules/` and had drifted: 8 files were older than the live rules, and 6 existed only in the repo. The 6 repo-only files (java, csharp, django, flask, spring-boot, TOOL-OPTIMIZATION) moved to `~/.claude/rules/` with `paths:` frontmatter. `load_framework_standards()` and `load_language_standards()` in `standards/selector.py` now read `~/.claude/rules/`, and `TestRuleFilePaths` reads it too, skipping where it is not installed. (#320)
14+
1215
## [2.1.0] - 2026-08-07
1316

1417
**Step 1 emits its prompt instead of executing it, and three things that were only

‎CLAUDE.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -152,12 +152,11 @@ Level 2: SDLC Execution Core (9 active steps: Steps 0-8)
152152
| +-- architecture/ # generate_system_diagram.py (shared utility)
153153
| +-- setup/ bin/ tools/ # env setup; Windows .bat launchers; dev utilities (release.py, sync-version.py, etc.)
154154
| +-- github_operations/ github_pr_workflow/ helpers/ # GitHub + PR workflow helpers
155-
+-- policies/03-execution-system/failure-prevention/ # failure-kb.json only (read by hooks/pre_tool_enforcer/policies/failure_kb.py); the historical 00-auto-fix/01-sync/02-standards/testing subtrees do not exist on disk -- see docs/ for standards content instead
155+
+-- policies/03-execution-system/failure-prevention/ # failure-kb.json only (read by hooks/pre_tool_enforcer/policies/failure_kb.py); the historical 00-auto-fix/01-sync/02-standards/testing subtrees do not exist on disk -- standards live only in ~/.claude/rules/ (no repo copy, #320)
156156
+-- src/mcp/ # In-engine copy of session-mgr + bridge (session_hooks, base/)
157157
+-- k8s/ # Kubernetes manifests (deployment, service, hpa, configmap, secret)
158158
+-- tests/ # 45 test files (37 unit, 4 integration, 3 e2e, 1 load)
159159
+-- docs/ # ALL documentation, segregated by kind -- see docs/README.md for the index
160-
| +-- standards/ (52) # numbered rules 01-46 + per-language standards; the loaded copy is ~/.claude/rules/, NOT this one
161160
| +-- policies/ (46) # pipeline policy documentation. NOT a mirror of ~/.claude/policies/ -- see the note below
162161
| +-- architecture/ (17) # ADRs, pipeline/level design, flow diagrams, orchestration prompt
163162
| +-- guides/ (14) # getting started, deployment, testing, troubleshooting, runbooks
@@ -202,7 +201,7 @@ unversioned: if that machine is lost, so are they.
202201
| Integrations Package | langgraph_engine/integrations/ | Abstract Factory + Lifecycle: GitHub/Jira/Figma/Jenkins |
203202
| Level 0 | langgraph_engine/preflight_guard/ | Pre-Flight Sanity Guard -- auto-fix enforcement (canonical) |
204203
| Level 1 | langgraph_engine/context_sync/ | Session & Context Synchronization (canonical). Outputs: `complexity_score` [1-10] (simple heuristic), `combined_complexity_score` [1-25] (simple x 0.3 + graph x 0.7 after linear scaling). **Note: `combined_complexity_score` is on a 1-25 scale -- do NOT treat it as 1-10.** |
205-
| Standards (non-numbered) | docs/ (standards) + langgraph_engine/standards/ (selector + library_adapter) | Standards policies (.md files, no pipeline nodes) -- always-on, loaded from disk; retired from the level count since it has never had pipeline nodes |
204+
| Standards (non-numbered) | ~/.claude/rules/ (the only copy; no repo docs/standards/) + langgraph_engine/standards/ (selector + library_adapter) | Standards policies (.md files, no pipeline nodes) -- always-on, loaded from disk; retired from the level count since it has never had pipeline nodes |
206205
| Level 2 | langgraph_engine/sdlc_pipeline/subgraph.py | SDLC Execution Core -- 9-step active execution (Steps 0-8) -- ACTIVE (nodes in sdlc_pipeline/nodes/) |
207206
| Pre-Analysis Node | langgraph_engine/sdlc_pipeline/subgraph.py | orchestration_pre_analysis_node: CallGraph scan at Step 0; template fast-path detection |
208207
| Hooks | hooks/pre-tool-enforcer.py, post-tool-tracker.py, stop-notifier.py | Tool enforcement + session maintenance |

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -475,7 +475,7 @@ claude-workflow-engine/ # 369 Python files total
475475
│ ├── e2e/ # 3 end-to-end scenario tests
476476
│ └── load/ # 1 concurrency / load test
477477
│
478-
├── docs/ # 253 files — architecture docs, ADRs, runbooks, ALL policy/rule
478+
├── docs/ # 201 files — architecture docs, ADRs, runbooks, ALL policy/rule
479479
│ # .md files (flattened here, no subfolders), CONTRIBUTING.md,
480480
│ # CODE_OF_CONDUCT.md, and the GitHub issue/PR templates
481481
├── uml/ # Regenerated per pipeline run (13 types, Mermaid/PlantUML)
@@ -814,7 +814,7 @@ See [CHANGELOG.md](CHANGELOG.md) for the complete version history.
814814

815815
**Complexity score is not ground truth:** `combined_complexity_score` is a heuristic: `simple_score × 0.3 + graph_score × 0.7`. It is on a 1-25 scale and correlates with effort, but it does not map to story points and should not be treated as precise.
816816

817-
**Framework-specific standards cover only Flask, Django, and Spring Boot so far.** `load_framework_standards()` in `standards/selector.py` looks in `docs/standards/` for a `{framework}-standards.md` file; `docs/standards/flask-standards.md`, `docs/standards/django-standards.md`, and `docs/standards/spring-boot-standards.md` are bundled. `detect_framework()` also recognizes FastAPI, Pyramid, Tornado, Celery, Scrapy, plain Spring, Quarkus, Micronaut, and the common JS/TS frameworks (React, Angular, Vue, Express, etc.) — none of those have a bundled doc yet, so detection succeeds but the framework tier returns empty for them. `load_language_standards()` has full coverage: all 6 project types `detect_project_type()` recognizes except `unknown` resolve real content (`docs/standards/02-backend-standards.md` python, `docs/standards/06-typescript-standards.md` javascript/typescript, `docs/standards/07-go-standards.md` go, `docs/standards/08-rust-standards.md` rust, `docs/standards/java-standards.md` java, `docs/standards/csharp-standards.md` csharp).
817+
**Framework-specific standards cover only Flask, Django, and Spring Boot so far.** `load_framework_standards()` in `standards/selector.py` looks in `~/.claude/rules/` (the only copy of the Claude rules; the repo no longer keeps one) for a `{framework}-standards.md` file; `flask-standards.md`, `django-standards.md`, and `spring-boot-standards.md` exist there. `detect_framework()` also recognizes FastAPI, Pyramid, Tornado, Celery, Scrapy, plain Spring, Quarkus, Micronaut, and the common JS/TS frameworks (React, Angular, Vue, Express, etc.) — none of those have a bundled doc yet, so detection succeeds but the framework tier returns empty for them. `load_language_standards()` has full coverage: all 6 project types `detect_project_type()` recognizes except `unknown` resolve real content (all under `~/.claude/rules/`: `02-backend-standards.md` python, `06-typescript-standards.md` javascript/typescript, `07-go-standards.md` go, `08-rust-standards.md` rust, `java-standards.md` java, `csharp-standards.md` csharp). On a machine without `~/.claude/rules/` both tiers return empty and fall through to the library-skill tiers.
818818

819819
### Trade-offs by Design
820820

‎docs/README.md‎

Lines changed: 2 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -22,70 +22,10 @@ permits: `README.md`, `CLAUDE.md`, `SRS.md`, `CHANGELOG.md` and `VERSION`.
2222
| [`policies/`](policies/) | Pipeline policies | 44 |
2323
| [`releases/`](releases/) | Per-release design notes | 7 |
2424
| [`reports/`](reports/) | Investigations and audits | 26 |
25-
| [`standards/`](standards/) | Coding and testing standards | 52 |
2625

27-
---
28-
29-
## `standards/` -- Coding and testing standards
30-
31-
Numbered rules 01-46 plus per-language standards. These mirror `~/.claude/rules/`, which is what the Standards mechanism loads at runtime; the copies here are for reading, not execution.
32-
33-
<details><summary>52 file(s)</summary>
34-
35-
- [01-common-standards.md](standards/01-common-standards.md)
36-
- [02-backend-standards.md](standards/02-backend-standards.md)
37-
- [03-microservices-standards.md](standards/03-microservices-standards.md)
38-
- [04-frontend-standards.md](standards/04-frontend-standards.md)
39-
- [05-security-standards.md](standards/05-security-standards.md)
40-
- [06-typescript-standards.md](standards/06-typescript-standards.md)
41-
- [07-go-standards.md](standards/07-go-standards.md)
42-
- [08-rust-standards.md](standards/08-rust-standards.md)
43-
- [09-swift-standards.md](standards/09-swift-standards.md)
44-
- [10-kotlin-standards.md](standards/10-kotlin-standards.md)
45-
- [11-documentation-files.md](standards/11-documentation-files.md)
46-
- [12-docstrings-only.md](standards/12-docstrings-only.md)
47-
- [13-spring-cloud-infrastructure.md](standards/13-spring-cloud-infrastructure.md)
48-
- [14-entity-design-patterns.md](standards/14-entity-design-patterns.md)
49-
- [15-dto-form-separation.md](standards/15-dto-form-separation.md)
50-
- [16-validation-sequence-pattern.md](standards/16-validation-sequence-pattern.md)
51-
- [17-api-response-wrapper.md](standards/17-api-response-wrapper.md)
52-
- [18-service-layer-conventions.md](standards/18-service-layer-conventions.md)
53-
- [19-exception-handling-hierarchy.md](standards/19-exception-handling-hierarchy.md)
54-
- [20-inter-service-communication.md](standards/20-inter-service-communication.md)
55-
- [21-caching-strategy.md](standards/21-caching-strategy.md)
56-
- [22-common-library-design.md](standards/22-common-library-design.md)
57-
- [23-enum-as-domain-model.md](standards/23-enum-as-domain-model.md)
58-
- [24-constants-organization.md](standards/24-constants-organization.md)
59-
- [25-jpa-auditing-pattern.md](standards/25-jpa-auditing-pattern.md)
60-
- [26-openapi-documentation.md](standards/26-openapi-documentation.md)
61-
- [27-centralized-logging.md](standards/27-centralized-logging.md)
62-
- [28-test-coverage-enforcement.md](standards/28-test-coverage-enforcement.md)
63-
- [29-container-deployment.md](standards/29-container-deployment.md)
64-
- [30-maven-build-conventions.md](standards/30-maven-build-conventions.md)
65-
- [31-security-authentication.md](standards/31-security-authentication.md)
66-
- [32-repository-conventions.md](standards/32-repository-conventions.md)
67-
- [33-test-case-roadmap.md](standards/33-test-case-roadmap.md)
68-
- [34-frontend-package-structure.md](standards/34-frontend-package-structure.md)
69-
- [35-positive-testing-standards.md](standards/35-positive-testing-standards.md)
70-
- [36-negative-testing-standards.md](standards/36-negative-testing-standards.md)
71-
- [37-edge-case-testing-standards.md](standards/37-edge-case-testing-standards.md)
72-
- [38-test-mocking-strategy.md](standards/38-test-mocking-strategy.md)
73-
- [39-cross-cutting-test-patterns.md](standards/39-cross-cutting-test-patterns.md)
74-
- [40-universal-test-patterns-abstract.md](standards/40-universal-test-patterns-abstract.md)
75-
- [41-testing-standards-python-fastapi.md](standards/41-testing-standards-python-fastapi.md)
76-
- [42-testing-standards-nodejs-express.md](standards/42-testing-standards-nodejs-express.md)
77-
- [43-testing-standards-go.md](standards/43-testing-standards-go.md)
78-
- [44-srs-lifecycle.md](standards/44-srs-lifecycle.md)
79-
- [45-uml-diagram-lifecycle.md](standards/45-uml-diagram-lifecycle.md)
80-
- [46-architecture-documentation.md](standards/46-architecture-documentation.md)
81-
- [TOOL-OPTIMIZATION-LEVEL2-STANDARD.md](standards/TOOL-OPTIMIZATION-LEVEL2-STANDARD.md)
82-
- [csharp-standards.md](standards/csharp-standards.md)
83-
- [django-standards.md](standards/django-standards.md)
84-
- [flask-standards.md](standards/flask-standards.md)
85-
- [java-standards.md](standards/java-standards.md)
86-
- [spring-boot-standards.md](standards/spring-boot-standards.md)
26+
Coding and testing standards (numbered rules 01-46 plus per-language standards) are not kept in this repository. They live only in `~/.claude/rules/`, which is what Claude Code and `standards/selector.py` load (#320).
8727

88-
</details>
28+
---
8929

9030
## `policies/` -- Pipeline policies
9131

‎docs/architecture/ADR-006-hook-free-execution.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -204,7 +204,7 @@ not recomputed here and is owned elsewhere (PRD NFR-4).
204204
that a blocking policy returns exit code 2 from the `PreToolUse` hook so the tool call does not
205205
proceed. Deleting `PreToolUse` and `PostToolUse` falsifies this for two of the four events.
206206

207-
Per `rules/44` (mirrored in this repo at `docs/standards/44-srs-lifecycle.md`) the SRS is
207+
Per `rules/44` (`~/.claude/rules/44-srs-lifecycle.md`; the repo copy was removed in #320) the SRS is
208208
append-only, so FR-9 cannot be quietly edited in place. The
209209
required handling is a superseding append that retires FR-9's four-event guarantee, states the v2.0.0
210210
replacement guarantee, and adds a Change Log row. An agent that silently rewrites FR-9 in place is in

‎docs/orchestration_prompt.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ actually enforced at runtime and which are prose only.
4242

4343
Corpus to read in full:
4444
- `docs/policies/` — 46 markdown policy documents (the authored corpus)
45-
- `docs/standards/` — 52 files: numbered rules 01–46 plus per-language standards
45+
- `~/.claude/rules/` — numbered rules 01–46 plus per-language standards (the only copy; no repo `docs/standards/` since #320)
4646
- `~/.claude/policies/` — 5 directories: `01-sync-system`, `02-standards-system`,
4747
`03-execution-system`, `failure-prevention`, `testing` (this is what `get_policies_dir()` reads today)
4848
- `policies/` in-repo — contains **only** `03-execution-system/failure-prevention/failure-kb.json`
@@ -1716,7 +1716,7 @@ AGREED CONTRACTS
17161716

17171717
INPUT CONTEXT
17181718
- `structural_inventory.json`, `ast_call_graph.json`, `audit_surface.json`.
1719-
- `docs/policies/` — 46 files. `docs/standards/` — 52 files (numbered rules 01–46 + language standards).
1719+
- `docs/policies/` — 46 files. `~/.claude/rules/` — numbered rules 01–46 + language standards (no repo copy).
17201720
- Known enforcement readers to check: `hooks/pre_tool_enforcer/policies/failure_kb.py` reads
17211721
`policies/03-execution-system/failure-prevention/failure-kb.json`; `get_policies_dir()` resolves
17221722
`~/.claude/policies/`.

0 commit comments

Comments
 (0)