[AIT-9] ascii-guard linting #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

fxstein merged 8 commits into main from fxstein/AIT-9-ascii-guard-linting

Jan 31, 2026

.ai-todo/.ai-todo.log

-Original file line number
+Diff line change
@@ Expand Up / @@ -4080,3 +4080,34 @@ main-3 | - [D] **#fxstein-25** Test @@
 -01-31 02:48:30 | oratzes | CLI | UPDATE |  | 44012105 |
 -01-31 02:50:03 | oratzes | CLI | UPDATE |  | a469e776 |
 -01-31 02:50:35 | oratzes | CLI | UPDATE |  | ed917836 |
+-01-31 03:27:13 | oratzes | CLI | UPDATE |  | c991d3a4 |
+-01-31 03:27:13 | oratzes | CLI | UPDATE |  | 677f01d6 |
+-01-31 03:27:17 | oratzes | CLI | UPDATE |  | c6e12795 |
+-01-31 03:27:17 | oratzes | CLI | UPDATE |  | 4b9f447f |
+-01-31 03:27:19 | oratzes | CLI | UPDATE |  | 726c4b52 |
+-01-31 03:27:19 | oratzes | CLI | UPDATE |  | 1847083a |
+-01-31 03:27:20 | oratzes | CLI | UPDATE |  | b1a75f21 |
+-01-31 03:27:20 | oratzes | CLI | UPDATE |  | 2f540b25 |
+-01-31 03:27:21 | oratzes | CLI | UPDATE |  | 9e19420d |
+-01-31 03:27:21 | oratzes | CLI | UPDATE |  | 1234f1b9 |
+-01-31 03:27:22 | oratzes | CLI | UPDATE |  | 202ac510 |
+-01-31 03:27:22 | oratzes | CLI | UPDATE |  | 1fd61014 |
+-01-31 03:27:24 | oratzes | CLI | UPDATE |  | 84c11afb |
+-01-31 03:27:24 | oratzes | CLI | UPDATE |  | 9f3f78cd |
+-01-31 03:27:25 | oratzes | CLI | UPDATE |  | b1efd551 |
+-01-31 03:27:25 | oratzes | CLI | UPDATE |  | 73a23605 |
+-01-31 03:27:55 | oratzes | CLI | UPDATE |  | 59bc811d |
+-01-31 03:29:49 | oratzes | CLI | UPDATE |  | 45a6416b |
+-01-31 03:29:52 | oratzes | CLI | UPDATE |  | ffa48408 |
+-01-31 03:30:35 | oratzes | CLI | UPDATE |  | 08ed1c73 |
+-01-31 03:38:54 | oratzes | CLI | UPDATE |  | c77a5577 |
+-01-31 03:38:54 | oratzes | CLI | UPDATE |  | 1f8d0ae7 |
+-01-31 03:39:29 | oratzes | CLI | UPDATE |  | 474721eb |
+-01-31 03:39:30 | oratzes | CLI | UPDATE |  | 32d37811 |
+-01-31 03:39:55 | oratzes | CLI | UPDATE |  | d49d46e9 |
+-01-31 03:39:55 | oratzes | CLI | UPDATE |  | f87fe106 |
+-01-31 03:41:38 | oratzes | CLI | UPDATE |  | 663ba9be |
+-01-31 03:41:38 | oratzes | CLI | UPDATE |  | 43e2b403 |
+-01-31 03:42:12 | oratzes | CLI | UPDATE |  | ce9e5358 |
+-01-31 03:42:13 | oratzes | CLI | UPDATE |  | 0845cef5 |
+-01-31 03:42:50 | oratzes | CLI | UPDATE |  | 1a7a0d24 |

.ai-todo/.ai-todo.serial

Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		271
		272

.ai-todo/state/TODO.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -4,6 +4,40 @@ @@
     ## Tasks
+    - [x] **#272** [AIT-9] ascii-guard linting `#documentation` `#tooling` `#urgent` (2026-01-31)
+      > Add fxstein/ascii-guard linting to pre-commit and CICD workflows. Need to make sure all documents are cleaned - especially documentation, and various documents created during analysis and design reviews.
+      > Linear Issue: https://linear.app/fxstein/issue/AIT-9/ascii-guard-linting
+      - [x] **#272.7** Verify and document ascii-guard integration `#documentation` `#validation` (2026-01-31)
+        > Final verification:
+        > - Test pre-commit hook locally
+        > - Verify CI/CD workflow runs successfully
+        > - Update relevant documentation
+        > - Ensure all documents are clean
+      - [x] **#272.6** Clean existing documentation files `#cleanup` `#documentation` (2026-01-31)
+        > Run ascii-guard on all existing documents and clean up any non-ASCII characters:
+        > - Documentation in docs/
+        > - Analysis and design documents
+        > - README and other markdown files
+        > - Any other documentation artifacts
+      - [x] **#272.5** Create tests for ascii-guard integration `#testing` `#validation` (2026-01-31)
+        > Create unit and integration tests to verify ascii-guard correctly identifies non-ASCII characters in documents and that the integration works in both pre-commit and CI/CD contexts.
+      - [x] **#272.4** Add ascii-guard to CI/CD workflows `#ci-cd` `#implementation` (2026-01-31)
+        > Integrate ascii-guard linting into GitHub Actions CI/CD pipeline (.github/workflows/ci-cd.yml).
+      - [x] **#272.3** Implement ascii-guard in pre-commit configuration `#implementation` `#pre-commit` (2026-01-31)
+        > Add ascii-guard hook to .pre-commit-config.yaml with appropriate configuration for the repository.
+      - [x] **#272.2** Human review of design document `#checkpoint` `#review` (2026-01-31)
+        > Pause for human review and approval of the design document before proceeding with implementation.
+        > This is a checkpoint to ensure the approach is correct.
+      - [x] **#272.1** Create design document for ascii-guard integration `#design` `#documentation` (2026-01-31)
+        > Research fxstein/ascii-guard tool and create a comprehensive design document covering:
+        > - How ascii-guard works and its purpose
+        > - Integration points (pre-commit, CI/CD workflows)
+        > - Configuration requirements
+        > - Document cleanup strategy
+        > - Testing approach
+        > Document location: docs/design/ascii-guard-integration.md
+        > ✅ Design document created: docs/design/ascii-guard-integration.md
     - [ ] **#271** [AIT-15] Incorrect branch names for linear issue
       > When starting to work on a new linear issue, the branch that gets created has the wrong user id as the prefix. The cursor rule needs to explicitly use the GitHub userid and not any name Linear provides in its suggested branch name.
       > Linear: https://linear.app/fxstein/issue/AIT-15/incorrect-branch-names-for-linear-issue
@@ Expand Down Expand Up / @@ -1350,6 +1384,11 @@ @@
     ---
+    ## Task Metadata
+    Task relationships and dependencies (managed by ai-todo).
+    View with: `ai-todo show <task-id>`
     <!-- TASK_METADATA
     # Format: task_id:created_at[:updated_at]
 :2026-01-27T23:50:41.505242:2026-01-27T23:51:37.635568
@@ Expand Down Expand Up / @@ -2097,6 +2136,14 @@ @@
 .1:2026-01-31T02:48:27.516905:2026-01-31T02:50:03.561272
 .2:2026-01-31T02:48:28.906966:2026-01-31T02:50:03.561274
 .3:2026-01-31T02:48:30.471793:2026-01-31T02:50:35.741187
+:2026-01-31T03:27:13.275650:2026-01-31T03:42:50.364981
+.1:2026-01-31T03:27:17.810592:2026-01-31T03:29:52.114908
+.2:2026-01-31T03:27:19.023195:2026-01-31T03:38:54.198980
+.3:2026-01-31T03:27:20.050615:2026-01-31T03:39:29.983224
+.4:2026-01-31T03:27:21.336450:2026-01-31T03:39:55.033984
+.5:2026-01-31T03:27:22.712250:2026-01-31T03:41:38.413677
+.6:2026-01-31T03:27:24.206296:2026-01-31T03:42:12.881908
+.7:2026-01-31T03:27:25.691111:2026-01-31T03:42:50.364979
 :2026-01-27T23:50:41.502304:2026-01-27T23:51:37.630894
 .1:2026-01-27T23:50:41.502320:2026-01-27T23:50:41.502321
 .2:2026-01-27T23:50:41.502315:2026-01-27T23:51:37.630903
@@ Expand Down Expand Up / @@ -2164,4 +2211,4 @@ @@
     -->
     ---
-    **ai-todo** | Last Updated: 2026-01-31 02:50:35
+    **ai-todo** | Last Updated: 2026-01-31 03:42:50

.ai-todo/state/checksum

Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		ed9178366908bf798d7ab54c2c7b01633bc80a6e4389ab778eef37e58593493a
		1a7a0d24d203b498b6d52230691a1ac58220cce93217e167092517ba5b0412cf

.ascii-guard.toml

-Original file line number
+Diff line change
@@ -0,0 +1,44 @@
+    # .ascii-guard.toml
+    # Configuration for ascii-guard linter
+    [files]
+    # Scan all text files (empty = all)
+    extensions = []
+    # Exclude patterns (gitignore-style)
+    exclude = [
+        ".git/",
+        "node_modules/",
+        "__pycache__/",
+        ".venv/",
+        "venv/",
+        ".tox/",
+        "build/",
+        "dist/",
+        ".mypy_cache/",
+        ".pytest_cache/",
+        ".ruff_cache/",
+        "*.egg-info/",
+        # Project-specific excludes:
+        ".ai-todo/",           # ai-todo state directory
+        "htmlcov/",
+        ".coverage",
+        "uv.lock",
+    ]
+    # Follow symbolic links when scanning
+    follow_symlinks = false
+    # Maximum file size to scan in MB
+    max_file_size = 10
+    [rules]
+    # Phase 2: Enable/disable specific validation rules (future)
+    # check_alignment = true
+    # check_corners = true
+    # check_width = true
+    [output]
+    # Phase 2: Output customization (future)
+    # color = "auto"
+    # verbose = false

.github/workflows/ci-cd.yml

-Original file line number
+Diff line change
@@ Expand Up / @@ -156,6 +156,9 @@ jobs: @@
           - name: Install dependencies
             run: uv sync --all-extras
+          - name: Lint ASCII art boxes
+            run: uv run ascii-guard lint .
           - name: Lint TODO.md
             run: uv run ai-todo lint
@@ Expand Down @@

.pre-commit-config.yaml

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -61,14 +61,14 @@ repos:
  
            pass_filenames: true

            files: ^(release/|\.github/|scripts/)

          # Temporarily disabled due to pipx environment issues

          # - id: ascii-guard

          #   name: ascii-guard

          #   entry: ascii-guard lint

          #   language: system

          #   types: [markdown]

          #   pass_filenames: true

          #   files: \.(md|mdc)$

          - id: ascii-guard

            name: ascii-guard

            entry: uv run ascii-guard lint

            language: system

            types: [markdown]

            pass_filenames: true

            files: \.(md|mdc)$

            exclude: ^\.ai-todo/

          - id: todo-ai-lint

            name: ai-todo lint

CONTRIBUTING.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -56,6 +56,32 @@ If you are not using Cursor: @@
        - Example: `git checkout -b jdoe/AIT-12-fix-login`.
 . Open a PR from that branch to `main`. The branch name will be checked by the Linear PR Check workflow.
+    ## Pre-commit Hooks
+    This project uses pre-commit hooks to ensure code quality:
+    ```bash
+    # Install pre-commit hooks (one-time setup)
+    pre-commit install
+    # Run manually on all files
+    pre-commit run --all-files
+    ```
+    **ASCII Art Guidelines:**
+    We use [ascii-guard](https://github.com/fxstein/ascii-guard) to ensure consistent ASCII diagram formatting:
+    ```bash
+    # Check ASCII art in documentation
+    uv run ascii-guard lint docs/
+    # Auto-fix alignment issues
+    uv run ascii-guard fix docs/
+    ```
+    When creating diagrams, use Unicode box-drawing characters: `─ │ ┌ ┐ └ ┘`. The pre-commit hook will catch alignment issues automatically.
     ---
     For other contribution guidelines (code style, tests, release process), see the main [README](README.md) and [docs/](docs/).

TODO.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -4,6 +4,40 @@ @@
     ## Tasks
+    - [x] **#272** [AIT-9] ascii-guard linting `#documentation` `#tooling` `#urgent` (2026-01-31)
+      > Add fxstein/ascii-guard linting to pre-commit and CICD workflows. Need to make sure all documents are cleaned - especially documentation, and various documents created during analysis and design reviews.
+      > Linear Issue: https://linear.app/fxstein/issue/AIT-9/ascii-guard-linting
+      - [x] **#272.7** Verify and document ascii-guard integration `#documentation` `#validation` (2026-01-31)
+        > Final verification:
+        > - Test pre-commit hook locally
+        > - Verify CI/CD workflow runs successfully
+        > - Update relevant documentation
+        > - Ensure all documents are clean
+      - [x] **#272.6** Clean existing documentation files `#cleanup` `#documentation` (2026-01-31)
+        > Run ascii-guard on all existing documents and clean up any non-ASCII characters:
+        > - Documentation in docs/
+        > - Analysis and design documents
+        > - README and other markdown files
+        > - Any other documentation artifacts
+      - [x] **#272.5** Create tests for ascii-guard integration `#testing` `#validation` (2026-01-31)
+        > Create unit and integration tests to verify ascii-guard correctly identifies non-ASCII characters in documents and that the integration works in both pre-commit and CI/CD contexts.
+      - [x] **#272.4** Add ascii-guard to CI/CD workflows `#ci-cd` `#implementation` (2026-01-31)
+        > Integrate ascii-guard linting into GitHub Actions CI/CD pipeline (.github/workflows/ci-cd.yml).
+      - [x] **#272.3** Implement ascii-guard in pre-commit configuration `#implementation` `#pre-commit` (2026-01-31)
+        > Add ascii-guard hook to .pre-commit-config.yaml with appropriate configuration for the repository.
+      - [x] **#272.2** Human review of design document `#checkpoint` `#review` (2026-01-31)
+        > Pause for human review and approval of the design document before proceeding with implementation.
+        > This is a checkpoint to ensure the approach is correct.
+      - [x] **#272.1** Create design document for ascii-guard integration `#design` `#documentation` (2026-01-31)
+        > Research fxstein/ascii-guard tool and create a comprehensive design document covering:
+        > - How ascii-guard works and its purpose
+        > - Integration points (pre-commit, CI/CD workflows)
+        > - Configuration requirements
+        > - Document cleanup strategy
+        > - Testing approach
+        > Document location: docs/design/ascii-guard-integration.md
+        > ✅ Design document created: docs/design/ascii-guard-integration.md
     - [ ] **#271** [AIT-15] Incorrect branch names for linear issue
       > When starting to work on a new linear issue, the branch that gets created has the wrong user id as the prefix. The cursor rule needs to explicitly use the GitHub userid and not any name Linear provides in its suggested branch name.
       > Linear: https://linear.app/fxstein/issue/AIT-15/incorrect-branch-names-for-linear-issue
@@ Expand Down Expand Up / @@ -1350,6 +1384,11 @@ @@
     ---
+    ## Task Metadata
+    Task relationships and dependencies (managed by ai-todo).
+    View with: `ai-todo show <task-id>`
     <!-- TASK_METADATA
     # Format: task_id:created_at[:updated_at]
 :2026-01-27T23:50:41.505242:2026-01-27T23:51:37.635568
@@ Expand Down Expand Up / @@ -2097,6 +2136,14 @@ @@
 .1:2026-01-31T02:48:27.516905:2026-01-31T02:50:03.561272
 .2:2026-01-31T02:48:28.906966:2026-01-31T02:50:03.561274
 .3:2026-01-31T02:48:30.471793:2026-01-31T02:50:35.741187
+:2026-01-31T03:27:13.275650:2026-01-31T03:42:50.364981
+.1:2026-01-31T03:27:17.810592:2026-01-31T03:29:52.114908
+.2:2026-01-31T03:27:19.023195:2026-01-31T03:38:54.198980
+.3:2026-01-31T03:27:20.050615:2026-01-31T03:39:29.983224
+.4:2026-01-31T03:27:21.336450:2026-01-31T03:39:55.033984
+.5:2026-01-31T03:27:22.712250:2026-01-31T03:41:38.413677
+.6:2026-01-31T03:27:24.206296:2026-01-31T03:42:12.881908
+.7:2026-01-31T03:27:25.691111:2026-01-31T03:42:50.364979
 :2026-01-27T23:50:41.502304:2026-01-27T23:51:37.630894
 .1:2026-01-27T23:50:41.502320:2026-01-27T23:50:41.502321
 .2:2026-01-27T23:50:41.502315:2026-01-27T23:51:37.630903
@@ Expand Down Expand Up / @@ -2164,4 +2211,4 @@ @@
     -->
     ---
-    **ai-todo** | Last Updated: 2026-01-31 02:50:35
+    **ai-todo** | Last Updated: 2026-01-31 03:42:50

docs/archive/RELEASE_NUMBERING_MAPPING.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -44,25 +44,25 @@ The release numbering logic uses a **highest-level-first approach** to determine
  
    ```

    ┌─────────────────────────────────────────────────────────────────┐

    │ Step 1: Scan ALL commits and classify each by release level       │

    │ ─────────────────────────────────────────────────────────────  │

    │ Process each commit individually:                              │

    │ Step 1: Scan ALL commits and classify each by release level     │ │

    │ ─────────────────────────────────────────────────────────────   │

    │ Process each commit individually:                               │

    │ → Classify each commit: MAJOR > MINOR > PATCH                   │

    │ → Step down from highest to lowest level per commit             │

    │ → Track the HIGHEST level found across all commits              │

    └─────────────────────────────────────────────────────────────────┘

                              ↓

    ┌─────────────────────────────────────────────────────────────────┐

    │ Step 2: Find Highest Level Across All Commits                    │

    │ ─────────────────────────────────────────────────────────────  │

    │ Logic:                                                           │

    │ Step 2: Find Highest Level Across All Commits                   │

    │ ─────────────────────────────────────────────────────────────   │

    │ Logic:                                                          │

    │ → A single MAJOR commit makes the entire release MAJOR          │

    │ → A single MINOR commit (with no MAJOR) makes release MINOR     │

    │ → Otherwise, it's PATCH                                         │

    │                                                                  │

    │                                                                 │

    │ Priority order (highest to lowest):                             │

    │ 1. MAJOR: breaking, break, major, !:, feat!:, fix!:             │

    │ 2. MINOR: feat:, feature: (if user-facing)                     │

    │ 2. MINOR: feat:, feature: (if user-facing)                      │

    │ 3. PATCH: backend:, infra:, release:, internal:, fix:, bugfix:  │

    │ 4. MINOR: add, new, implement, create, support (if not backend) │

    │ 5. PATCH: (default for all other commits)                       │

docs/design/BUG_REPORTING_DESIGN.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -206,7 +206,7 @@ Labels are passed to `gh issue create --label` command with fallback to basic "b
  
        ▼          ▼

    ┌──────────────────┐  ┌─────────────────┐

    │ Reply to Issue   │  │ Create New Issue│

    │ - "Me too" msg  │  │ - Full report   │

    │ - "Me too" msg  │  ││- Full report    │

    │ - Attach logs    │  │ - All context   │

    └──────────────────┘  └─────────────────┘

    ```

docs/design/GIT_HOOKS_DESIGN.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -39,31 +39,31 @@ Currently, there are no automated checks before commits. This can lead to:
  
             │

             ▼

    ┌─────────────────────┐

    │ Pre-commit Hook    │

    │ Triggered          │

    └────────┬────────────┘

    │ Pre-commit Hook     │

    │ Triggered           │

    └─────────────────────┘

             │

             ▼

    ┌─────────────────────┐

    │ Get Staged Files    │

    │ - Detect file types │

    │ - Filter relevant  │

    └────────┬────────────┘

    │ - Filter relevant   │

    └─────────────────────┘

             │

             ▼

    ┌─────────────────────┐

    │ Run Validators     │

    │ ├─ Markdown linter │

    │ ├─ YAML linter     │

    │ ├─ JSON linter     │

    │ └─ TODO.md lint    │

    └────────┬────────────┘

    │ Run Validators      │

    │ ├─ Markdown linter  │

    │ ├─ YAML linter      │

    │ ├─ JSON linter      │

    │ └─ TODO.md lint     │

    └─────────────────────┘

             │

             ▼

    ┌─────────────────────┐

    │ Check Results      │

    │ - Any errors?      │

    └────────┬────────────┘

    │ Check Results       │

    │ - Any errors?       │

    └─────────────────────┘

             │

        ┌────┴────┐

        │         │

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[AIT-9] ascii-guard linting #80

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!