From 3a6ee49c5c236f0df0d09aaf222b502ad73ac2bc Mon Sep 17 00:00:00 2001 From: Mikhail Chusavitin Date: Sat, 31 Oct 2026 11:30:13 +0300 Subject: [PATCH] docs: standardize repository helpers under tools --- AGENT-BOOTSTRAP.md | 2 +- README.md | 2 +- rules/patterns/module-structure/contract.md | 20 +++++++++++++++++++- {scripts => tools}/lint.sh | 2 +- 4 files changed, 22 insertions(+), 4 deletions(-) rename {scripts => tools}/lint.sh (97%) diff --git a/AGENT-BOOTSTRAP.md b/AGENT-BOOTSTRAP.md index 765de66..e2d991c 100644 --- a/AGENT-BOOTSTRAP.md +++ b/AGENT-BOOTSTRAP.md @@ -20,7 +20,7 @@ If you are editing this `bible/` repository itself, read the target contract and - Edit the relevant existing contract, or create a new `rules/patterns//contract.md`. - Normative rules go in `contract.md`; examples and rationale go in the pattern's `README.md`. - Do not create rules outside `rules/patterns/`. Do not expand scope beyond engineering rules and patterns. -- Run `sh scripts/lint.sh` after changes. +- Run `sh tools/lint.sh` after changes. ## Always-On Contracts diff --git a/README.md b/README.md index 9ee128f..f24e093 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ git submodule update --remote bible AGENT-BOOTSTRAP.md — first file agents should read; contains the full contract router rules/patterns// — one contract.md per topic (plus optional README.md with examples) rules/ai/AGENT.template.md — template for new projects; copy as both CLAUDE.md and AGENTS.md -scripts/lint.sh — consistency checks (router coverage, broken links) +tools/lint.sh — consistency checks (router coverage, broken links) ``` ## Project Setup diff --git a/rules/patterns/module-structure/contract.md b/rules/patterns/module-structure/contract.md index 6e614e9..8454f6d 100644 --- a/rules/patterns/module-structure/contract.md +++ b/rules/patterns/module-structure/contract.md @@ -1,6 +1,6 @@ # Contract: Module Atomicity -Version: 1.0 +Version: 1.1 ## Principle @@ -34,3 +34,21 @@ Split a file when: 3. The file has more than one reason to change independently. Do not wait until a file is "too big." Split at the moment the second responsibility appears. + +## Repository Tooling + +- Keep repository-owned helper programs and scripts under one root `tools/` + directory, regardless of language. Do not create parallel `scripts/`, `script/` + or `tool/` directories for the same purpose. +- Group a tool's supporting code, fixtures and usage notes with that tool; + use named subdirectories when several files implement one tool. +- Fixed-location integration entry points, such as Git hooks and CI workflow + files, stay where their runner requires them. Reusable helper logic belongs + in `tools/`. Application source and package-local test fixtures stay with + their owning packages. +- When moving an existing tool, update callers, CI, documentation and planned + paths together. Preserve executable permissions and repository-root resolution. +- Generated reports and logs are output artifacts, not tools. Keep them + untracked and document their output location. If the operator wants a report + beside the standalone script, ignore that report in Git. Credentials and + backup data must follow the applicable secrets and backup contracts. diff --git a/scripts/lint.sh b/tools/lint.sh similarity index 97% rename from scripts/lint.sh rename to tools/lint.sh index 3f13466..51a7390 100755 --- a/scripts/lint.sh +++ b/tools/lint.sh @@ -1,5 +1,5 @@ #!/bin/sh -# Consistency checks for the rules library. Run from the repo root: sh scripts/lint.sh +# Consistency checks for the rules library. Run from the repo root: sh tools/lint.sh set -u fail=0 -- 2.54.0