docs: per-script local specs + spec-first change order (SPEC 6.11, 6.12)

Every script gets a complete spec.md sectionized like SPEC.md
(python/src/<name>/spec.md, <name>.spec.md for shell scripts).
Change order becomes spec -> tests -> code. Specs added for
gpgtools, hello, hello_bash; CHANGELOG under Unreleased.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-11-19 00:54:03 +01:00
parent fef68a84c9
commit 85e8342a74
5 changed files with 308 additions and 5 deletions
+39 -4
View File
@@ -77,13 +77,15 @@ daedalus/
│ ├── daedalus_logging/ # File + console logging (section 11)
│ └── tests/
├── python/
│ ├── src/<name>/ # Python scripts, one folder per script
│ ├── src/<name>/ # Python scripts, one folder per script,
│ │ # holding <name>.py and spec.md (SPEC item 6.11)
│ └── tests/ # pytest tests for python/src, .ps1, .bat
├── bash/ # *.sh scripts (SPEC item 6.10 interface)
├── bash/ # *.sh scripts (SPEC item 6.10 interface),
│ # each with a <name>.spec.md sibling
│ ├── daedalus_common.sh # shared helper: daedalus_bash_dispatch, help() routing
│ └── tests/ # pytest tests that run them
├── powershell/ # *.ps1 scripts
├── batch/ # *.bat scripts (CRLF)
├── powershell/ # *.ps1 scripts, each with <name>.spec.md
├── batch/ # *.bat scripts (CRLF), each with <name>.spec.md
├── ci/ # sanity.py, checks.py, with tests
├── autotest.py # Runs every check (local and CI)
├── pyproject.toml # Package, version, entry point, package data
@@ -496,6 +498,39 @@ SCRIPTS: dict[str, Script] = {
registered `.sh` script (source line, `help()`, `main()`, the
dispatch call) and tests the helper behavior directly.
- **6.11** Every script has a local spec that completely
describes it.
- **6.11.1** A Python script's spec is `spec.md` inside its
own folder: `python/src/<name>/spec.md`.
- **6.11.2** A bash, PowerShell, or batch script's spec is a
sibling file named `<name>.spec.md`:
`bash/<name>.spec.md`, `powershell/<name>.spec.md`,
`batch/<name>.spec.md`.
- **6.11.3** The local spec follows the sectionized format of
this file: every heading and list item has a stable numbered
id (`- **N.M**`), sub-items continue the numbering
(`N.M.K`), and items are cited as
`<name> spec item N.M`.
- **6.11.4** The local spec is complete enough to rebuild the
script from it alone: purpose, commands and arguments,
observable behavior (steps, validation, output), exit
codes, files written, error handling, and testing approach.
- **6.11.5** The local spec does not repeat this file; where it
relies on a repository rule it cites the SPEC item instead.
- **6.12** The change order for script work is spec first, then
tests, then code.
- **6.12.1** Create or modify the script's local spec (SPEC
item 6.11) until it describes the intended behavior - a
change that contradicts an existing spec item updates that
item in the same change.
- **6.12.2** Add or change tests that fail without the
behavior.
- **6.12.3** Make the smallest change that makes the tests
pass, then refactor with them green.
- **6.12.4** Spec, tests, code, README, and CHANGELOG land in
the same change; the version bump follows SPEC item 9.8.
## 7. Quality gates
- **7.1** `python autotest.py [CHECK...]` runs the named checks (default: