docs(spec)!: reorganize repository and simplify date handling

BREAKING CHANGE: Multiple breaking changes to spec format

Date handling changes:
- Remove positional dates (bare YYYY-MM-DD after priority)
- All dates now require key:value syntax (planned:, due:, done:)
- Rename frontmatter field: date_format → datetime_format
- Add bracket syntax for optional time: %d/%m/%Y[ %H:%M]

Repository reorganization:
- Move specification from docs/ to spec/
- Move implementation docs (compatibility, libraries) to docs/
- Flatten tests/golden/ to tests/
- Remove examples/ (converted to golden tests T12-T15)

New content:
- Add golden test suite T01-T15 with full conformance coverage
- Add TESTING.md with test harness documentation
- Add CATALOG.md with detailed coverage matrix

Config updates:
- Update CI, pre-commit, and release configs for new paths
- Add docs(spec) scope rule for semantic release
- Exclude tests/ from linting (intentional edge cases)

Author: ricksaarge

.github/workflows/ci.yml

@@ -18,12 +18,12 @@ jobs:
       - name: Lint Markdown files
         uses: DavidAnson/markdownlint-cli2-action@v14
         with:
-          globs: "**/*.md"
+          globs: "**/*.md !tests/**/*.md"
 
       - name: Check spelling
         uses: streetsidesoftware/cspell-action@v5
         with:
-          files: "**/*.md"
+          files: "**/*.md !tests/**/*.md"
           config: "./cspell.json"
 
       - name: Check links
@@ -35,10 +35,10 @@ jobs:
       - name: AISD forbidden words check
         run: |
           echo "Checking for forbidden words (should/might/could/typically/usually/often)..."
-          # Exclude README.md, CHANGELOG.md, and AGENTS.md from this check
-          if find . -name "*.md" ! -name "README.md" ! -name "CHANGELOG.md" ! -name "AGENTS.md" -exec grep -l -E "\b(should|might|could|typically|usually|often)\b" {} \; | grep -q .; then
+          # Exclude README.md, CHANGELOG.md, AGENTS.md, and tests/ from this check
+          if find . -name "*.md" ! -path "./tests/*" ! -name "README.md" ! -name "CHANGELOG.md" ! -name "AGENTS.md" -exec grep -l -E "\b(should|might|could|typically|usually|often)\b" {} \; | grep -q .; then
             echo "❌ Found forbidden words in the following files:"
-            find . -name "*.md" ! -name "README.md" ! -name "CHANGELOG.md" ! -name "AGENTS.md" -exec grep -Hn -E "\b(should|might|could|typically|usually|often)\b" {} \;
+            find . -name "*.md" ! -path "./tests/*" ! -name "README.md" ! -name "CHANGELOG.md" ! -name "AGENTS.md" -exec grep -Hn -E "\b(should|might|could|typically|usually|often)\b" {} \;
             echo ""
             echo "Use MUST/REQUIRED/FORBIDDEN instead per AISD style guide."
             exit 1
@@ -47,9 +47,9 @@ jobs:
 
       - name: AISD line count check
         run: |
-          echo "Checking docs/ files for line count (max 600)..."
+          echo "Checking docs/ and spec/ files for line count (max 600)..."
           failed=0
-          for file in docs/*.md docs/**/*.md; do
+          for file in docs/*.md docs/**/*.md spec/*.md; do
             [ -f "$file" ] || continue
             lines=$(wc -l < "$file")
             if [ "$lines" -gt 600 ]; then
@@ -61,7 +61,7 @@ jobs:
             echo "Consider splitting large files."
             exit 1
           fi
-          echo "✅ All docs files within line limit"
+          echo "✅ All docs and spec files within line limit"
 
   commitlint:
     name: Commit Messages

.pre-commit-config.yaml

@@ -17,12 +17,14 @@ repos:
     hooks:
       - id: markdownlint
         args: ["--fix"]
+        exclude: ^tests/
 
   - repo: https://github.com/streetsidesoftware/cspell-cli
     rev: v8.6.0
     hooks:
       - id: cspell
         args: ["--no-progress", "--no-summary"]
+        exclude: ^tests/
 
   # Conventional commits for semver
   - repo: https://github.com/compilerla/conventional-pre-commit
@@ -39,10 +41,10 @@ repos:
         entry: bash -c 'if grep -rn -E "\b(should|might|could|typically|usually|often)\b" "$@" 2>/dev/null; then echo "❌ Found forbidden words. Use MUST/REQUIRED/FORBIDDEN instead."; exit 1; fi' --
         language: system
         files: \.(md)$
-        exclude: ^(README\.md|CHANGELOG\.md|AGENTS\.md)$
+        exclude: ^(README\.md|CHANGELOG\.md|AGENTS\.md|tests/)
 
       - id: aisd-line-count
         name: AISD line count check (max 600)
         entry: bash -c 'for file in "$@"; do lines=$(wc -l < "$file"); if [ $lines -gt 600 ]; then echo "❌ $file has $lines lines (max 600). Consider splitting."; exit 1; fi; done' --
         language: system
-        files: ^docs/.*\.md$
+        files: ^(docs|spec)/.*\.md$

.releaserc.json

@@ -6,7 +6,8 @@
       {
         "preset": "conventionalcommits",
         "releaseRules": [
-          { "type": "docs", "release": "minor" },
+          { "type": "docs", "scope": "spec", "release": "minor" },
+          { "type": "docs", "release": false },
           { "type": "fix", "release": "patch" },
           { "type": "refactor", "release": "patch" },
           { "type": "style", "release": "patch" },
@@ -25,13 +26,13 @@
     [
       "@semantic-release/exec",
       {
-        "prepareCmd": "sed -i 's/\\*\\*Version:\\*\\* [0-9]*\\.[0-9]*\\.[0-9]*/\\*\\*Version:\\*\\* ${nextRelease.version}/' docs/specification.md && sed -i 's/Draft v[0-9]*\\.[0-9]*\\.[0-9]*/Draft v${nextRelease.version}/g' README.md AGENTS.md"
+        "prepareCmd": "sed -i 's/\\*\\*Version:\\*\\* [0-9]*\\.[0-9]*\\.[0-9]*/\\*\\*Version:\\*\\* ${nextRelease.version}/' spec/specification.md && sed -i 's/Draft v[0-9]*\\.[0-9]*\\.[0-9]*/Draft v${nextRelease.version}/g' README.md AGENTS.md"
       }
     ],
     [
       "@semantic-release/git",
       {
-        "assets": ["CHANGELOG.md", "docs/specification.md", "README.md", "AGENTS.md"],
+        "assets": ["CHANGELOG.md", "spec/specification.md", "README.md", "AGENTS.md"],
         "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
       }
     ],