update the spec
This commit is contained in:
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: Fiona-Assistant Specification
|
||||
version: 0.38.0
|
||||
version: 0.39.0
|
||||
title: Project Spec Sheet
|
||||
created: 2026-09-23
|
||||
updated: 2026-09-28
|
||||
updated: 2026-09-29
|
||||
type: summary
|
||||
---
|
||||
|
||||
@@ -18,8 +18,10 @@ type: summary
|
||||
- [2.2. `fiona-assistant librarian [directory]`](#22-fiona-assistant-librarian-directory)
|
||||
- [2.3. `fiona-assistant mdoctor [subcommand] [directory]`](#23-fiona-assistant-mdoctor-subcommand-directory)
|
||||
- [2.4. `fiona-assistant python-ruff [subcommand] [directory]`](#24-fiona-assistant-python-ruff-subcommand-directory)
|
||||
- [2.5. `fiona-assistant html-js-lint [subcommand] [directory]`](#25-fiona-assistant-html-js-lint-subcommand-directory)
|
||||
- [2.6. `fiona-assistant wiki [subcommand] [directory]`](#26-fiona-assistant-wiki-subcommand-directory)
|
||||
- [2.5. `fiona-assistant fmlint [subcommand] [directory]`](#25-fiona-assistant-fmlint-subcommand-directory)
|
||||
- [2.6. `fiona-assistant json-lint [subcommand] [directory]`](#26-fiona-assistant-json-lint-subcommand-directory)
|
||||
- [2.7. `fiona-assistant git [subcommand]`](#27-fiona-assistant-git-subcommand)
|
||||
- [2.8. `fiona-assistant wiki [subcommand] [directory]`](#28-fiona-assistant-wiki-subcommand-directory)
|
||||
- [3. llm-wiki Specifications](#3-llm-wiki-specifications)
|
||||
- [3.1. llm-wiki Lifecycle Management](#31-llm-wiki-lifecycle-management)
|
||||
- [3.1.1. `wiki init`](#311-wiki-init)
|
||||
@@ -55,24 +57,24 @@ type: summary
|
||||
- [4.9.5. Shared Sanity Runner Engine](#495-shared-sanity-runner-engine)
|
||||
- [4.9.6. Progress Display](#496-progress-display)
|
||||
- [4.10. toc-generator (Table of Contents)](#410-toc-generator-table-of-contents)
|
||||
- [4.10.1. MD Frontmatter Tagging](#4101-md-frontmatter-tagging)
|
||||
- [4.10.2. Per-File TOC Generation (`librarian toc file`)](#4102-per-file-toc-generation-librarian-toc-file)
|
||||
- [4.10.3. MD Frontmatter Tagging](#4103-md-frontmatter-tagging)
|
||||
- [4.11. fiona (CLI Entry Point)](#411-fiona-cli-entry-point)
|
||||
- [4.11.1. Wiki Root Discovery (`fiona-settings.json`)](#4111-wiki-root-discovery-fiona-settingsjson)
|
||||
- [4.10. json-lint (JSON Linter)](#410-json-lint-json-linter)
|
||||
- [4.10.1. JSON Syntax Validation](#4101-json-syntax-validation)
|
||||
- [4.10.2. JSON Style Rules](#4102-json-style-rules)
|
||||
- [4.10.3. CLI Integration](#4103-cli-integration)
|
||||
- [4.10.4. Sanity Integration](#4104-sanity-integration)
|
||||
- [4.12. html-js-lint (HTML and JavaScript Linter)](#412-html-js-lint-html-and-javascript-linter)
|
||||
- [4.12.1. HTML Validation](#4121-html-validation)
|
||||
- [4.12.2. JavaScript Linting](#4122-javascript-linting)
|
||||
- [4.12.3. CLI Integration](#4123-cli-integration)
|
||||
- [4.12.4. Configuration](#4124-configuration)
|
||||
- [4.12.5. Sanity Integration](#4125-sanity-integration)
|
||||
- [4.11. settings_manager (Settings Management)](#411-settings_manager-settings-management)
|
||||
- [4.11.1. Interactive Setup (`fiona-assistant setup`)](#4111-interactive-setup-fiona-assistant-setup)
|
||||
- [4.11.2. Contrast with `fiona-assistant init`](#4112-contrast-with-fiona-assistant-init)
|
||||
- [4.13. json-lint (JSON Linter)](#413-json-lint-json-linter)
|
||||
- [4.13.1. JSON Syntax Validation](#4131-json-syntax-validation)
|
||||
- [4.13.2. JSON Style Rules](#4132-json-style-rules)
|
||||
- [4.13.3. CLI Integration](#4133-cli-integration)
|
||||
- [4.13.4. Sanity Integration](#4134-sanity-integration)
|
||||
- [4.14. settings_manager (Settings Management)](#414-settings_manager-settings-management)
|
||||
- [4.14.1. Interactive Setup (`fiona-assistant setup`)](#4141-interactive-setup-fiona-assistant-setup)
|
||||
- [4.14.2. Contrast with `fiona-assistant init`](#4142-contrast-with-fiona-assistant-init)
|
||||
- [5. Project Infrastructure](#5-project-infrastructure)
|
||||
- [5.1. Logging Library](#51-logging-library)
|
||||
- [5.2. Documentation (medium priority)](#52-documentation-medium-priority)
|
||||
@@ -160,10 +162,10 @@ reserve LLM tokens for creative and analytical work.
|
||||
## 2. Current Capabilities
|
||||
|
||||
All commands below are implemented and reachable through the single
|
||||
`fiona-assistant` console script (section 4.9). Every optional
|
||||
`fiona-assistant` console script (section 4.11). Every optional
|
||||
`[directory]` argument currently defaults to the current directory;
|
||||
the planned wiki root discovery [4.9.1](#491-failure-reporting)
|
||||
will replace that default with
|
||||
the planned wiki root discovery [4.11.1](#4111-wiki-root-discovery-fiona-settingsjson)
|
||||
will replace that default with
|
||||
the directory containing `fiona-settings.json`.
|
||||
|
||||
### 2.1. `fiona-assistant`
|
||||
@@ -199,14 +201,34 @@ the directory containing `fiona-settings.json`.
|
||||
- `chklint [directory]`: Lint Python sources with ruff and print an
|
||||
AI-friendly violation report (file, line:column, rule code).
|
||||
|
||||
### 2.5. `fiona-assistant html-js-lint [subcommand] [directory]`
|
||||
### 2.5. `fiona-assistant fmlint [subcommand] [directory]`
|
||||
|
||||
- No subcommand: print the help and exit 1.
|
||||
- `chklint [directory]`: Check HTML and JavaScript files for lint violations.
|
||||
Supports `--json` flag for AI-friendly output format.
|
||||
- `--fix`: Auto-fix certain violations where supported by underlying linters.
|
||||
- No subcommand: default to `chklint .`.
|
||||
- `chklint [directory]`: Validate markdown frontmatter
|
||||
([4.2](#42-frontmatter-linter-fmlint)). The report lists violations
|
||||
and the command exits 0.
|
||||
|
||||
### 2.6. `fiona-assistant wiki [subcommand] [directory]`
|
||||
### 2.6. `fiona-assistant json-lint [subcommand] [directory]`
|
||||
|
||||
- No subcommand: default to `chklint .`.
|
||||
- `chklint [directory]`: Validate JSON syntax and style
|
||||
([4.13](#413-json-lint-json-linter)).
|
||||
- `fix [directory]`: Auto-fix indentation and trailing commas in place.
|
||||
|
||||
### 2.7. `fiona-assistant git [subcommand]`
|
||||
|
||||
Local git operations on an llm-wiki
|
||||
([3.2](#32-git-version-control-for-llm-wiki)).
|
||||
|
||||
- No subcommand: print the git help and exit 1.
|
||||
- `save --description TEXT`: Commit current edits.
|
||||
- `snapshot <tag_name> --description TEXT`: Save, then create a tag.
|
||||
- `restore <tag_name>`: New commit restoring the tagged tree.
|
||||
- `clean`: Discard uncommitted edits.
|
||||
- `undo`: Move back one commit. Fails when the working tree is dirty.
|
||||
- `status`: Print a short git status.
|
||||
|
||||
### 2.8. `fiona-assistant wiki [subcommand] [directory]`
|
||||
|
||||
- No subcommand: print the wiki help and exit 1.
|
||||
- `init [directory]`: Initialize the directory as an llm-wiki by copying
|
||||
@@ -242,10 +264,10 @@ Notes:
|
||||
|
||||
### 3.1. llm-wiki Lifecycle Management
|
||||
|
||||
> Status: Partially Implemented
|
||||
> Status: Implemented
|
||||
>
|
||||
> Covers: `wiki init` (implemented, 3.1.1), `wiki update` (implemented,
|
||||
> 3.1.2), `wiki sanity` (implemented, 3.1.3), `wiki graph` (planned, 3.1.4).
|
||||
> 3.1.2), `wiki sanity` (implemented, 3.1.3), `wiki graph` (implemented, 3.1.4).
|
||||
|
||||
#### 3.1.1. `wiki init`
|
||||
|
||||
@@ -344,8 +366,8 @@ Run all validation checks over an llm-wiki directory in one command.
|
||||
|
||||
- *3.1.3.1.* Runs markdown lint (`mdoctor`), frontmatter lint (`fmlint`, 4.2),
|
||||
Python lint (`python-ruff`), the custom markdown linter
|
||||
(`mdlinter`, 4.3.3), and any other registered linters
|
||||
(shellcheck once 4.4 ships).
|
||||
(`mdlinter`, 4.3.3), JSON lint (`jsonlint`, 4.13), and any other
|
||||
registered linters (shellcheck once 4.6 ships).
|
||||
- *acceptance*: Exits 0 on a clean wiki, non-zero on any violation.
|
||||
- *3.1.3.2.* Checks for dead links (relative and wiki-internal links resolving
|
||||
to
|
||||
@@ -386,7 +408,7 @@ violation
|
||||
[4.2](#42-frontmatter-linter-fmlint)
|
||||
— required `name`/`version` frontmatter per
|
||||
[project agent rule 10.1](AGENTS.md#101-md-file-frontmatter)), `python-ruff`,
|
||||
`mdlinter`.
|
||||
`mdlinter`, `jsonlint` ([4.13](#413-json-lint-json-linter)).
|
||||
- *3.1.3.10.* The report mirrors run_sanity [4.9.3](#493-linter-report-format)/
|
||||
[4.9.4](#494-run-timing): failing checks' linter reports first (clean runs
|
||||
print no report), a `Results:`
|
||||
@@ -399,16 +421,14 @@ violation
|
||||
|
||||
#### 3.1.4. `wiki graph`
|
||||
|
||||
> Status: Partially Implemented
|
||||
> Status: Implemented
|
||||
>
|
||||
> Covers: New module `src/wiki/graph_generator.py` and the
|
||||
> Covers: `src/wiki/graph_generator.py`,
|
||||
> `src/wiki/templates/graph_template.html`, and the
|
||||
> `fiona-assistant wiki graph` subcommand.
|
||||
>
|
||||
> Phase 1 (Core): Link parser + graph builder + basic HTML output + basic CLI
|
||||
> Phase 2 (CLI): Command integration with existing wiki subcommands
|
||||
> Phase 3 (Features): Color spectrum, edge coloring, gravity force, click handlers
|
||||
> Phase 4 (Polish): BFS layout + animated appearance + 360deg separation + clustering
|
||||
> Status: Implemented
|
||||
> Phases 1-4 are in that module and template: link parser, CLI,
|
||||
> color and physics, and the BFS layout.
|
||||
|
||||
Generate an interactive Obsidian-style graph visualization showing connections between
|
||||
markdown files based on internal links. The graph helps users visualize knowledge
|
||||
@@ -648,6 +668,7 @@ Operations:
|
||||
| `restore` | Create a new commit restoring to `<tag_name>` state; does NOT modify history |
|
||||
| `clean` | Discard current uncommitted edits; `git status` must be clean afterwards |
|
||||
| `undo` | Move back one commit. Error if the working tree is dirty; run `clean` first |
|
||||
| `status` | Print a short git status. Does not change the repository |
|
||||
|
||||
#### 3.2.1. Backup Script
|
||||
|
||||
@@ -785,7 +806,7 @@ ignored by MD025 |
|
||||
| `md060.enabled` | Implemented | False; table style rule diverges from Node.js
|
||||
|
|
||||
| `python.ruff` | Reserved | Unused placeholder for future ruff config
|
||||
[4.3](#43-custom-linter-framework) |
|
||||
[4.5](#45-python-ruff-python-lint) |
|
||||
| `markdown.toc_generator.max_depth_from_file` | Implemented | Header level cap
|
||||
per file in TOCs |
|
||||
| `markdown.toc_generator.max_depth_from_dir` | Implemented | Subfolder
|
||||
@@ -827,13 +848,13 @@ Related but separate: the sanity coverage gate lives in
|
||||
not in `fiona-settings.json`. The template copy shipped with the
|
||||
package is `src/llm-wiki/fiona-settings.json`; `wiki init` copies it
|
||||
into user wikis [3.1.1](#311-wiki-init)
|
||||
and it marks the wiki root [4.9.1](#491-failure-reporting).
|
||||
and it marks the wiki root [4.11.1](#4111-wiki-root-discovery-fiona-settingsjson).
|
||||
|
||||
---
|
||||
|
||||
### 4.2. Frontmatter Linter (fmlint)
|
||||
|
||||
> Status: Planned
|
||||
> Status: Implemented
|
||||
>
|
||||
> Covers: `src/customlinter/fmlint.py`. A custom linter specifically for
|
||||
> validating markdown file frontmatter against project requirements.
|
||||
@@ -842,7 +863,7 @@ into user wikis [3.1.1](#311-wiki-init)
|
||||
|
||||
#### 4.2.1. Frontmatter Validation
|
||||
|
||||
> Status: Planned
|
||||
> Status: Implemented
|
||||
|
||||
Validate that all markdown files in an llm-wiki directory have proper
|
||||
frontmatter with required fields.
|
||||
@@ -865,22 +886,22 @@ editing |
|
||||
| `sources` | No | Source file references (e.g. `raw/articles/source-name.md`) |
|
||||
| `confidence` / `contested` / `contradictions` | No | Quality signals |
|
||||
|
||||
- *4.2.1.1.* `NOT_IMPLEMENTED` Scan all `.md` files in a directory tree for frontmatter presence.
|
||||
- *4.2.1.1.* Scan all `.md` files in a directory tree for frontmatter presence.
|
||||
- *acceptance*: A md file missing `name` field is reported with file path and
|
||||
missing field.
|
||||
- *4.2.1.2.* `NOT_IMPLEMENTED` Validate that the required fields `name` and `version` are present
|
||||
- *4.2.1.2.* Validate that the required fields `name` and `version` are present
|
||||
(the minimum for source control per
|
||||
[project agent rule 10.1](AGENTS.md#101-md-file-frontmatter)). All other
|
||||
fields, including `title`, are optional.
|
||||
- *acceptance*: A md file missing `version` field is reported with file path
|
||||
and missing field.
|
||||
- *4.2.1.3.* `NOT_IMPLEMENTED` Support configurable required fields via `fiona-settings.json` for
|
||||
- *4.2.1.3.* Support configurable required fields via `fiona-settings.json` for
|
||||
different file types (e.g., `type: toc` files may have different requirements
|
||||
.
|
||||
- *acceptance*: A md file with `name` and `version` but no `title` passes
|
||||
validation
|
||||
(`title` is optional).
|
||||
- *4.2.1.4.* `NOT_IMPLEMENTED` Report violations in AI-friendly format: file path, missing fields
|
||||
- *4.2.1.4.* Report violations in AI-friendly format: file path, missing fields
|
||||
and
|
||||
line number (if known). Violation messages use the format `<code> -
|
||||
<message>`.
|
||||
@@ -888,62 +909,62 @@ validation
|
||||
at the start of the file (line 1), so `1:1` prefix is redundant.
|
||||
- *acceptance*: A md file with no frontmatter at all is reported as missing
|
||||
all required fields.
|
||||
- *4.2.1.5.* `NOT_IMPLEMENTED` Handle files without frontmatter (report as missing all required
|
||||
- *4.2.1.5.* Handle files without frontmatter (report as missing all required
|
||||
fields).
|
||||
- *acceptance*: A md file with malformed YAML frontmatter is reported with
|
||||
parse error details.
|
||||
- *4.2.1.6.* `NOT_IMPLEMENTED` Handle files with malformed YAML frontmatter (report as parse
|
||||
- *4.2.1.6.* Handle files with malformed YAML frontmatter (report as parse
|
||||
error).
|
||||
- *acceptance*: Running on a directory with all valid frontmatter reports no
|
||||
violations.
|
||||
- *4.2.1.7.* `NOT_IMPLEMENTED` Respect `.gitignore` and read-only zones (`personal/`, `raw/`).
|
||||
- *4.2.1.7.* Respect `.gitignore` and read-only zones (`personal/`, `raw/`).
|
||||
- *acceptance*: The linter integrates with `wiki sanity`
|
||||
[3.1.3](#313-wiki-sanity) and `run_sanity.py` [4.9](#49-test-and-sanity-runners).
|
||||
|
||||
#### 4.2.2. CLI Integration
|
||||
|
||||
> Status: Planned
|
||||
> Status: Implemented
|
||||
|
||||
Provide CLI access to the frontmatter linter via `fiona-assistant`.
|
||||
|
||||
- *4.2.2.1.* `NOT_IMPLEMENTED` `fiona-assistant fmlint chklint [directory]` scans for frontmatter
|
||||
- *4.2.2.1.* `fiona-assistant fmlint chklint [directory]` scans for frontmatter
|
||||
violations.
|
||||
- *acceptance*: Running `fiona-assistant fmlint` on a directory with invalid
|
||||
frontmatter
|
||||
produces a structured violation report.
|
||||
- *4.2.2.2.* `NOT_IMPLEMENTED` `fiona-assistant fmlint` with no subcommand defaults to `chklint`.
|
||||
- *4.2.2.2.* `fiona-assistant fmlint` with no subcommand defaults to `chklint`.
|
||||
|
||||
- *acceptance*: Running on a clean directory reports no violations.
|
||||
- *4.2.2.3.* `NOT_IMPLEMENTED` Output format matches other linters: AI-friendly violation report
|
||||
- *4.2.2.3.* Output format matches other linters: AI-friendly violation report
|
||||
with
|
||||
file paths, line numbers, and rule codes.
|
||||
- *4.2.2.4.* `NOT_IMPLEMENTED` Exit code 0 even with violations (consistent with other linters).
|
||||
- *4.2.2.4.* Exit code 0 even with violations (consistent with other linters).
|
||||
|
||||
#### 4.2.3. Settings Integration
|
||||
|
||||
> Status: Planned
|
||||
> Status: Implemented
|
||||
|
||||
Configure frontmatter linter behavior via `fiona-settings.json`.
|
||||
|
||||
- *4.2.3.1.* `NOT_IMPLEMENTED` Load required fields from `markdown.frontmatter.required_fields` in
|
||||
- *4.2.3.1.* Load required fields from `markdown.frontmatter.required_fields` in
|
||||
`fiona-settings.json` (default: `['name', 'version']`).
|
||||
- *acceptance*: Changing required fields in `fiona-settings.json` changes
|
||||
validation
|
||||
behavior on the next run.
|
||||
- *4.2.3.2.* `NOT_IMPLEMENTED` Support per-type requirements: `markdown.frontmatter
|
||||
- *4.2.3.2.* Support per-type requirements: `markdown.frontmatter
|
||||
type_requirements`
|
||||
maps file types to their specific required fields.
|
||||
- *acceptance*: Disabling the linter via settings skips frontmatter
|
||||
validation.
|
||||
- *4.2.3.3.* `NOT_IMPLEMENTED` Allow disabling the linter via `markdown.frontmatter.enabled`
|
||||
- *4.2.3.3.* Allow disabling the linter via `markdown.frontmatter.enabled`
|
||||
(default: true).
|
||||
- *acceptance*: Rules listed in `ignore_rules` are not reported as violations.
|
||||
- *4.2.3.4.* `NOT_IMPLEMENTED` Support ignoring specific violation rules via `markdown
|
||||
- *4.2.3.4.* Support ignoring specific violation rules via `markdown
|
||||
frontmatter.ignore_rules`
|
||||
(e.g., `['FML002']` to ignore missing frontmatter).
|
||||
- *acceptance*: Files matching patterns in `ignore_file` are skipped during
|
||||
linting.
|
||||
- *4.2.3.5.* `NOT_IMPLEMENTED` Support ignoring specific file patterns via `markdown.frontmatter
|
||||
- *4.2.3.5.* Support ignoring specific file patterns via `markdown.frontmatter
|
||||
ignore_file`
|
||||
(e.g., `['*/AGENTS.md', '*/README.md']` to skip certain files).
|
||||
|
||||
@@ -1187,7 +1208,7 @@ decision; do not implement until the tagging format is specified.
|
||||
>
|
||||
> Covers: `src/run_tests.py` (TestRunner) and `src/run_sanity.py`
|
||||
> (parallel pytests with a coverage gate, markdownlint, frontmatter,
|
||||
> ruff, and pycustomlint checks; see 4.9.1 to 4.9.6).
|
||||
> ruff, pycustomlint, and jsonlint checks; see 4.9.1 to 4.9.6).
|
||||
|
||||
#### 4.9.1. Failure Reporting
|
||||
|
||||
@@ -1257,8 +1278,8 @@ the verdict
|
||||
> Status: Implemented
|
||||
>
|
||||
> Every linter check in the sanity runner (markdownlint, frontmatter_lint,
|
||||
> pycustomlint, mdlinter) prints the same AI-friendly report structure so the
|
||||
> reports are diffable across linters.
|
||||
> pycustomlint, mdlinter, jsonlint) prints the same AI-friendly report
|
||||
> structure so the reports are diffable across linters.
|
||||
|
||||
- *4.9.3.1.* The report starts with a `<Linter Name> Violations` header followed
|
||||
by `TARGET: <scanned path>`.
|
||||
@@ -1452,32 +1473,6 @@ section of
|
||||
- `--non-recursive` still forces direct files only regardless of
|
||||
`max_depth_from_dir`
|
||||
|
||||
#### 4.10.1. MD Frontmatter Tagging
|
||||
|
||||
> Status: Partially Implemented
|
||||
|
||||
Tag md files with metadata used for version control and quality
|
||||
signals; the `version` tag feeds the TOC entries above.
|
||||
|
||||
| Tag | Status | Purpose |
|
||||
| --- | ------ | ------- |
|
||||
| `version` | Implemented | Source control, `wiki update` change detection, TOC
|
||||
display |
|
||||
| `date` | Planned | Creation/last-update timestamps maintained by tooling |
|
||||
| `confidence` | Planned | Quality signal (e.g. high/medium/low) on concept
|
||||
notes |
|
||||
| `contested` | Planned | Boolean flag marking notes with disputed claims |
|
||||
|
||||
- *4.10.1.1.* Frontmatter is validated by the `md_frontmatter` module (see
|
||||
[4.8](#48-librarian-content-management)).
|
||||
- *acceptance*: A concept note missing `confidence` is flagged by `wiki sanity`
|
||||
[3.1.3](#313-wiki-sanity).
|
||||
- *4.10.1.2.* Tags follow the canonical frontmatter schema (see
|
||||
[4.2.1](#421-frontmatter-validation)): `name` and
|
||||
`version` are required, `title` and all other fields are optional.
|
||||
- *4.10.1.3.* `wiki sanity` [3.1.3](#313-wiki-sanity)
|
||||
warns on files missing required tags.
|
||||
|
||||
#### 4.10.2. Per-File TOC Generation (`librarian toc file`)
|
||||
|
||||
> Status: Implemented
|
||||
@@ -1576,6 +1571,30 @@ reports an
|
||||
A file without an H1 is skipped with `skipped ... (no H1 heading)`
|
||||
and left unmodified.
|
||||
|
||||
#### 4.10.3. MD Frontmatter Tagging
|
||||
|
||||
> Status: Partially Implemented
|
||||
|
||||
Tag md files with metadata used for version control and quality
|
||||
signals; the `version` tag feeds the TOC entries above.
|
||||
|
||||
| Tag | Status | Purpose |
|
||||
| --- | ------ | ------- |
|
||||
| `version` | Implemented | Source control, `wiki update` change detection, TOC display |
|
||||
| `date` | Planned | Creation/last-update timestamps maintained by tooling |
|
||||
| `confidence` | Planned | Quality signal (e.g. high/medium/low) on concept notes |
|
||||
| `contested` | Planned | Boolean flag marking notes with disputed claims |
|
||||
|
||||
- *4.10.3.1.* Frontmatter is validated by the `md_frontmatter` module (see
|
||||
[4.8](#48-librarian-content-management)).
|
||||
- *acceptance*: A concept note missing `confidence` is flagged by `wiki sanity`
|
||||
[3.1.3](#313-wiki-sanity).
|
||||
- *4.10.3.2.* Tags follow the canonical frontmatter schema (see
|
||||
[4.2.1](#421-frontmatter-validation)): `name` and
|
||||
`version` are required, `title` and all other fields are optional.
|
||||
- *4.10.3.3.* `wiki sanity` [3.1.3](#313-wiki-sanity)
|
||||
warns on files missing required tags.
|
||||
|
||||
---
|
||||
|
||||
### 4.11. fiona (CLI Entry Point)
|
||||
@@ -1586,15 +1605,17 @@ reports an
|
||||
> dispatches to the tool modules so every tool is reachable through one
|
||||
> command. Each tool also keeps its standalone CLI; `librarian` and
|
||||
> `mdoctor` are installed as console scripts, while `python-ruff` is
|
||||
> available only through `fiona-assistant`. All dispatch modules
|
||||
> (`fiona`, `python_ruff`) ship in the wheel.
|
||||
> available only through `fiona-assistant`. `fmlint`, `json-lint`, and
|
||||
> the `git` subcommands are also only through `fiona-assistant`.
|
||||
> Dispatch modules `fiona`, `python_ruff`, `customlinter`, `wiki`, and
|
||||
> `gittool` ship in the wheel.
|
||||
|
||||
Command tree:
|
||||
|
||||
| Command | Behavior |
|
||||
| ------- | -------- |
|
||||
| `fiona-assistant librarian [directory]` | List files via librarian
|
||||
[4.6](#46-shellcheck-library) |
|
||||
[4.8](#48-librarian-content-management) |
|
||||
| `fiona-assistant librarian list [directory]` | Same as above |
|
||||
| `fiona-assistant librarian toc [directory]` | Generate a TOC
|
||||
[4.10](#410-toc-generator-table-of-contents) |
|
||||
@@ -1604,8 +1625,14 @@ Command tree:
|
||||
[4.10.2](#4102-per-file-toc-generation-librarian-toc-file) |
|
||||
| `fiona-assistant mdoctor [args]` | Delegate to the mdoctor CLI; defaults to
|
||||
`chklint .` |
|
||||
| `fiona-assistant fmlint [args]` | Frontmatter lint; defaults to `chklint .`
|
||||
[4.2](#42-frontmatter-linter-fmlint) |
|
||||
| `fiona-assistant python-ruff [args]` | Delegate to the python-ruff CLI;
|
||||
defaults to `chklint .` |
|
||||
| `fiona-assistant json-lint [args]` | JSON lint; defaults to `chklint .`
|
||||
[4.13](#413-json-lint-json-linter) |
|
||||
| `fiona-assistant git save/snapshot/restore/clean/undo/status` | Wiki git
|
||||
operations [3.2](#32-git-version-control-for-llm-wiki) |
|
||||
| `fiona-assistant wiki init [directory]` | Initialize an llm-wiki
|
||||
[3.1.1](#311-wiki-init) |
|
||||
| `fiona-assistant wiki check-update [directory]` | Check for core-file updates
|
||||
@@ -1614,6 +1641,8 @@ defaults to `chklint .` |
|
||||
[3.1.2](#312-wiki-update) |
|
||||
| `fiona-assistant wiki sanity [directory]` | Run all sanity checks
|
||||
[3.1.3](#313-wiki-sanity) |
|
||||
| `fiona-assistant wiki graph [directory]` | Write the link graph
|
||||
[3.1.4](#314-wiki-graph) |
|
||||
|
||||
- *4.11.1.* With no subcommand, print help and exit 0.
|
||||
- *acceptance*: Each subcommand behaves identically to the corresponding
|
||||
@@ -1660,112 +1689,14 @@ directory,
|
||||
|
||||
---
|
||||
|
||||
### 4.10. json-lint (JSON Linter)
|
||||
|
||||
> Status: Planned
|
||||
>
|
||||
> Covers: `src/json_lint/`. A JSON linter and checker that validates
|
||||
> JSON syntax and applies configurable style rules. Uses existing Python
|
||||
> libraries (`json` module for parsing, potentially `json5` or similar for
|
||||
> extended syntax support).
|
||||
|
||||
#### 4.10.1. JSON Syntax Validation
|
||||
|
||||
> Status: Planned
|
||||
|
||||
Validate that JSON files have correct syntax and are parseable.
|
||||
|
||||
- *4.10.1.1.* `NOT_IMPLEMENTED` Use Python's standard `json` module for syntax validation.
|
||||
- *acceptance*: A JSON file with a syntax error (e.g., missing comma,
|
||||
unquoted key) is
|
||||
reported with file path and error location.
|
||||
- *4.10.1.2.* `NOT_IMPLEMENTED` Check that all JSON files in the target directory tree are valid
|
||||
JSON.
|
||||
- *acceptance*: A JSON file with valid syntax but no style violations reports
|
||||
no errors.
|
||||
- *4.10.1.3.* `NOT_IMPLEMENTED` Report syntax errors with file path, line number, and column
|
||||
position.
|
||||
- *acceptance*: Running on a directory with no JSON files produces no errors.
|
||||
- *4.10.1.4.* `NOT_IMPLEMENTED` Handle files with `.json` extension by default; support
|
||||
configurable
|
||||
extensions via settings.
|
||||
- *4.10.1.5.* `NOT_IMPLEMENTED` Respect `.gitignore` and read-only zones (`personal/`, `raw/`).
|
||||
|
||||
#### 4.10.2. JSON Style Rules
|
||||
|
||||
> Status: Planned
|
||||
|
||||
Apply configurable style rules to JSON files.
|
||||
|
||||
- *4.10.2.1.* `NOT_IMPLEMENTED` Check indentation: tabs should be converted to spaces, with
|
||||
configurable
|
||||
indent length (default: 2 spaces per the project standard).
|
||||
- *acceptance*: A JSON file with tab indentation when `indent: "space"` and
|
||||
`indent_len: 2`
|
||||
is configured reports a style violation.
|
||||
- *4.10.2.2.* `NOT_IMPLEMENTED` Check trailing commas (optional based on settings).
|
||||
- *4.10.2.3.* `NOT_IMPLEMENTED` Check key ordering (optional based on settings).
|
||||
- *acceptance*: A JSON file with 4-space indentation when `indent_len: 2` is
|
||||
configured
|
||||
reports a style violation.
|
||||
- *4.10.2.4.* `NOT_IMPLEMENTED` Check for duplicate keys in objects.
|
||||
- *acceptance*: A JSON file with duplicate keys is reported as a violation.
|
||||
- *4.10.2.5.* `NOT_IMPLEMENTED` Load style rules from the `json` section of `fiona-settings.json`:
|
||||
- `indent`: `"space"` or `"tab"` (default: `"space"`)
|
||||
- `indent_len`: number of spaces for indentation (default: 2)
|
||||
- `trailing_commas`: bool, whether to allow trailing commas (default: false)
|
||||
- `require_key_order`: bool, whether object keys must be sorted
|
||||
(default: false)
|
||||
- Additional rules can be added without code changes via configuration.
|
||||
- *4.10.2.6.* `NOT_IMPLEMENTED` A missing `json` section in settings uses sensible defaults.
|
||||
|
||||
#### 4.10.3. CLI Integration
|
||||
|
||||
> Status: Planned
|
||||
|
||||
Provide CLI access to the JSON linter via `fiona-assistant`.
|
||||
|
||||
- *4.10.3.1.* `NOT_IMPLEMENTED` `fiona-assistant json-lint chklint [directory]` scans for JSON
|
||||
violations.
|
||||
- *acceptance*: Running `fiona-assistant json-lint` on a directory with
|
||||
invalid JSON
|
||||
produces a structured violation report.
|
||||
- *4.10.3.2.* `NOT_IMPLEMENTED` `fiona-assistant json-lint` with no subcommand defaults to
|
||||
`chklint .`.
|
||||
- *acceptance*: Running on a clean directory reports no violations.
|
||||
- *4.10.3.3.* `NOT_IMPLEMENTED` Output format matches other linters: AI-friendly violation report
|
||||
with
|
||||
file paths, line numbers, column numbers, and rule codes.
|
||||
- *4.10.3.4.* `NOT_IMPLEMENTED` Exit code 0 even with violations (consistent with other linters).
|
||||
- *4.10.3.5.* `NOT_IMPLEMENTED` Support `--fix` flag to auto-fix certain violations (indentation,
|
||||
trailing
|
||||
commas) in place.
|
||||
- *acceptance*: Running with `--fix` on a file with fixable violations
|
||||
corrects the file
|
||||
and reports the number of fixed files.
|
||||
|
||||
#### 4.10.4. Sanity Integration
|
||||
|
||||
> Status: Planned
|
||||
|
||||
Integrate the JSON linter into the sanity checker.
|
||||
|
||||
- *4.10.4.1.* `NOT_IMPLEMENTED` `run_sanity.py` runs `json-lint chklint` on the codebase.
|
||||
- *acceptance*: A JSON file with violations causes `run_sanity.py` to report
|
||||
JSON lint
|
||||
failures.
|
||||
- *4.10.4.2.* `NOT_IMPLEMENTED` `wiki sanity` [3.1.3](#313-wiki-sanity)
|
||||
runs `json-lint chklint` on the wiki directory.
|
||||
- *acceptance*: `wiki sanity` [3.1.3](#313-wiki-sanity)
|
||||
reports JSON violations alongside other linter violations.
|
||||
- *4.10.4.3.* `NOT_IMPLEMENTED` JSON lint violations are reported in the aggregated sanity output.
|
||||
|
||||
---
|
||||
|
||||
### 4.12. html-js-lint (HTML and JavaScript Linter)
|
||||
|
||||
> Status: Planned
|
||||
>
|
||||
> `pyproject.toml` still lists package `html_js_lint` and a
|
||||
> `html-js-lint` console script. That directory does not exist.
|
||||
> Remove both entries until this section is implemented.
|
||||
>
|
||||
> Covers: `src/html_js_lint/`. An HTML and JavaScript linter that validates
|
||||
> HTML syntax and structure, and JavaScript code quality. Uses existing Python
|
||||
> libraries where available: `html5validator` for HTML validation (W3C standard,
|
||||
@@ -1875,78 +1806,181 @@ Integrate the HTML and JavaScript linter into the sanity checker.
|
||||
|
||||
---
|
||||
|
||||
### 4.11. settings_manager (Settings Management)
|
||||
|
||||
### 4.13. json-lint (JSON Linter)
|
||||
|
||||
> Status: Implemented
|
||||
>
|
||||
> Covers: `src/customlinter/jsonlint.py`. A JSON linter and checker that validates
|
||||
> JSON syntax and applies configurable style rules. Uses existing Python
|
||||
> libraries (`json` module for parsing, potentially `json5` or similar for
|
||||
> extended syntax support).
|
||||
|
||||
#### 4.13.1. JSON Syntax Validation
|
||||
|
||||
> Status: Implemented
|
||||
|
||||
Validate that JSON files have correct syntax and are parseable.
|
||||
|
||||
- *4.13.1.1.* Use Python's standard `json` module for syntax validation.
|
||||
- *acceptance*: A JSON file with a syntax error (e.g., missing comma,
|
||||
unquoted key) is
|
||||
reported with file path and error location.
|
||||
- *4.13.1.2.* Check that all JSON files in the target directory tree are valid
|
||||
JSON.
|
||||
- *acceptance*: A JSON file with valid syntax but no style violations reports
|
||||
no errors.
|
||||
- *4.13.1.3.* Report syntax errors with file path, line number, and column
|
||||
position.
|
||||
- *acceptance*: Running on a directory with no JSON files produces no errors.
|
||||
- *4.13.1.4.* Handle files with `.json` extension by default; support
|
||||
configurable
|
||||
extensions via settings.
|
||||
- *4.13.1.5.* Respect `.gitignore` and read-only zones (`personal/`, `raw/`).
|
||||
|
||||
#### 4.13.2. JSON Style Rules
|
||||
|
||||
> Status: Implemented
|
||||
|
||||
Apply configurable style rules to JSON files.
|
||||
|
||||
- *4.13.2.1.* Check indentation: tabs should be converted to spaces, with
|
||||
configurable
|
||||
indent length (default: 2 spaces per the project standard).
|
||||
- *acceptance*: A JSON file with tab indentation when `indent: "space"` and
|
||||
`indent_len: 2`
|
||||
is configured reports a style violation.
|
||||
- *4.13.2.2.* Check trailing commas (optional based on settings).
|
||||
- *4.13.2.3.* Check key ordering (optional based on settings).
|
||||
- *acceptance*: A JSON file with 4-space indentation when `indent_len: 2` is
|
||||
configured
|
||||
reports a style violation.
|
||||
- *4.13.2.4.* Check for duplicate keys in objects.
|
||||
- *acceptance*: A JSON file with duplicate keys is reported as a violation.
|
||||
- *4.13.2.5.* Load style rules from the `json` section of `fiona-settings.json`:
|
||||
- `indent`: `"space"` or `"tab"` (default: `"space"`)
|
||||
- `indent_len`: number of spaces for indentation (default: 2)
|
||||
- `trailing_commas`: bool, whether to allow trailing commas (default: false)
|
||||
- `require_key_order`: bool, whether object keys must be sorted
|
||||
(default: false)
|
||||
- Additional rules can be added without code changes via configuration.
|
||||
- *4.13.2.6.* A missing `json` section in settings uses sensible defaults.
|
||||
|
||||
#### 4.13.3. CLI Integration
|
||||
|
||||
> Status: Implemented
|
||||
|
||||
Provide CLI access to the JSON linter via `fiona-assistant`.
|
||||
|
||||
- *4.13.3.1.* `fiona-assistant json-lint chklint [directory]` scans for JSON
|
||||
violations.
|
||||
- *acceptance*: Running `fiona-assistant json-lint` on a directory with
|
||||
invalid JSON
|
||||
produces a structured violation report.
|
||||
- *4.13.3.2.* `fiona-assistant json-lint` with no subcommand defaults to
|
||||
`chklint .`.
|
||||
- *acceptance*: Running on a clean directory reports no violations.
|
||||
- *4.13.3.3.* Output format matches other linters: AI-friendly violation report
|
||||
with
|
||||
file paths, line numbers, column numbers, and rule codes.
|
||||
- *4.13.3.4.* Exit code 0 even with violations (consistent with other linters).
|
||||
- *4.13.3.5.* Support `--fix` flag to auto-fix certain violations (indentation,
|
||||
trailing
|
||||
commas) in place.
|
||||
- *acceptance*: Running with `--fix` on a file with fixable violations
|
||||
corrects the file
|
||||
and reports the number of fixed files.
|
||||
|
||||
#### 4.13.4. Sanity Integration
|
||||
|
||||
> Status: Implemented
|
||||
|
||||
Integrate the JSON linter into the sanity checker.
|
||||
|
||||
- *4.13.4.1.* `run_sanity.py` runs `json-lint chklint` on the codebase.
|
||||
- *acceptance*: A JSON file with violations causes `run_sanity.py` to report
|
||||
JSON lint
|
||||
failures.
|
||||
- *4.13.4.2.* `wiki sanity` [3.1.3](#313-wiki-sanity)
|
||||
runs `json-lint chklint` on the wiki directory.
|
||||
- *acceptance*: `wiki sanity` [3.1.3](#313-wiki-sanity)
|
||||
reports JSON violations alongside other linter violations.
|
||||
- *4.13.4.3.* JSON lint violations are reported in the aggregated sanity output.
|
||||
|
||||
---
|
||||
|
||||
### 4.14. settings_manager (Settings Management)
|
||||
|
||||
> Status: Planned
|
||||
|
||||
Covers: `src/fiona/settings_manager.py`. Provides interactive and
|
||||
non-interactive settings management for fiona-assistant.
|
||||
|
||||
#### 4.11.1. Interactive Setup (`fiona-assistant setup`)
|
||||
#### 4.14.1. Interactive Setup (`fiona-assistant setup`)
|
||||
|
||||
> Status: Planned
|
||||
|
||||
Run an interactive setup utility to configure fiona-assistant settings.
|
||||
|
||||
- *4.11.1.1.* `NOT_IMPLEMENTED` Present all configurable settings from `fiona-settings.json` to
|
||||
- *4.14.1.1.* `NOT_IMPLEMENTED` Present all configurable settings from `fiona-settings.json` to
|
||||
the user
|
||||
- *acceptance*: Running `fiona-assistant setup` with no arguments starts the
|
||||
interactive flow
|
||||
- *4.11.1.2.* `NOT_IMPLEMENTED` Allow user to enable/disable boolean settings by checking or
|
||||
- *4.14.1.2.* `NOT_IMPLEMENTED` Allow user to enable/disable boolean settings by checking or
|
||||
unchecking
|
||||
- *acceptance*: User can navigate through all settings with Enter to accept
|
||||
defaults
|
||||
- *4.11.1.3.* `NOT_IMPLEMENTED` Allow user to add custom values for string/integer settings where
|
||||
- *4.14.1.3.* `NOT_IMPLEMENTED` Allow user to add custom values for string/integer settings where
|
||||
applicable
|
||||
- *acceptance*: User can toggle boolean settings (check/uncheck)
|
||||
- *4.11.1.4.* `NOT_IMPLEMENTED` Provide a complete path where user can press Enter through all
|
||||
- *4.14.1.4.* `NOT_IMPLEMENTED` Provide a complete path where user can press Enter through all
|
||||
prompts to
|
||||
accept all defaults without modification
|
||||
- *acceptance*: User can input custom values for string/integer settings
|
||||
- *4.11.1.5.* `NOT_IMPLEMENTED` Display current values for each setting before prompting
|
||||
- *4.11.1.6.* `NOT_IMPLEMENTED` Support non-interactive mode via flags (e.g., `--yes`,
|
||||
- *4.14.1.5.* `NOT_IMPLEMENTED` Display current values for each setting before prompting
|
||||
- *4.14.1.6.* `NOT_IMPLEMENTED` Support non-interactive mode via flags (e.g., `--yes`,
|
||||
`--default`) for
|
||||
AI agents to run deterministically
|
||||
- *acceptance*: All inputs are validated before saving to settings file
|
||||
- *4.11.1.7.* `NOT_IMPLEMENTED` Validate all inputs before saving
|
||||
- *4.14.1.7.* `NOT_IMPLEMENTED` Validate all inputs before saving
|
||||
- *acceptance*: Non-interactive mode applies all defaults without prompts
|
||||
- *4.11.1.8.* `NOT_IMPLEMENTED` Write validated settings to `fiona-settings.json` in the wiki root
|
||||
- *4.14.1.8.* `NOT_IMPLEMENTED` Write validated settings to `fiona-settings.json` in the wiki root
|
||||
- *acceptance*: Exit code 0 on successful completion, non-zero on validation
|
||||
error or failure
|
||||
- *4.11.1.9.* `NOT_IMPLEMENTED` Handle missing or corrupted settings files gracefully
|
||||
- *4.14.1.9.* `NOT_IMPLEMENTED` Handle missing or corrupted settings files gracefully
|
||||
- *acceptance*: Running `fiona-assistant setup` in a directory without
|
||||
`fiona-settings.json`
|
||||
creates one with defaults
|
||||
|
||||
#### 4.11.2. Contrast with `fiona-assistant init`
|
||||
#### 4.14.2. Contrast with `fiona-assistant init`
|
||||
|
||||
> Status: Planned
|
||||
|
||||
Clarify the difference between `init` and `setup` commands.
|
||||
|
||||
- *4.11.2.1.* `NOT_IMPLEMENTED` `fiona-assistant init [directory]`: Initializes an llm-wiki
|
||||
- *4.14.2.1.* `NOT_IMPLEMENTED` `fiona-assistant init [directory]`: Initializes an llm-wiki
|
||||
directory with
|
||||
default settings applied automatically without user interaction (see
|
||||
[3.1.1](#311-wiki-init))
|
||||
- *acceptance*: Documentation clearly distinguishes the two commands and
|
||||
their use cases
|
||||
- *4.11.2.2.* `NOT_IMPLEMENTED` `fiona-assistant setup`: Runs interactive review of all possible
|
||||
- *4.14.2.2.* `NOT_IMPLEMENTED` `fiona-assistant setup`: Runs interactive review of all possible
|
||||
settings,
|
||||
allowing user to customize each setting before applying
|
||||
- *acceptance*: `init` remains non-interactive and applies all defaults
|
||||
automatically
|
||||
- *4.11.2.3.* `NOT_IMPLEMENTED` `init` is designed for quick bootstrap with sensible defaults
|
||||
- *4.14.2.3.* `NOT_IMPLEMENTED` `init` is designed for quick bootstrap with sensible defaults
|
||||
- *acceptance*: `setup` provides full interactive review of all configurable
|
||||
settings
|
||||
- *4.11.2.4.* `NOT_IMPLEMENTED` `setup` is designed for users who want to review and customize
|
||||
- *4.14.2.4.* `NOT_IMPLEMENTED` `setup` is designed for users who want to review and customize
|
||||
settings
|
||||
before initialization or update existing settings
|
||||
- *acceptance*: `setup` can be run on an existing wiki to modify settings
|
||||
- *4.11.2.5.* `NOT_IMPLEMENTED` `init` creates the wiki structure; `setup` configures settings in
|
||||
- *4.14.2.5.* `NOT_IMPLEMENTED` `init` creates the wiki structure; `setup` configures settings in
|
||||
an
|
||||
existing wiki
|
||||
- *4.11.2.6.* `NOT_IMPLEMENTED` Both commands respect the wiki root discovery mechanism
|
||||
[4.9.1](#491-failure-reporting)
|
||||
- *4.14.2.6.* `NOT_IMPLEMENTED` Both commands respect the wiki root discovery mechanism
|
||||
[4.11.1](#4111-wiki-root-discovery-fiona-settingsjson)
|
||||
|
||||
---
|
||||
|
||||
@@ -1983,12 +2017,16 @@ resolve against the current working directory; dropping
|
||||
`file_log_location` disables file logging; an unopenable location
|
||||
logs a warning and keeps console logging.
|
||||
|
||||
- *5.1.1.* `NOT_IMPLEMENTED` Standard `logging` module (or agreed equivalent); no new hard
|
||||
dependency.
|
||||
- *acceptance*: No direct `print` calls in `src/` production modules.
|
||||
- *5.1.2.* `NOT_IMPLEMENTED` CLI-facing output stays stdout; diagnostics go to stderr with levels.
|
||||
- *acceptance*: Tool output consumed by tests/scripts is unchanged.
|
||||
- *5.1.3.* `NOT_IMPLEMENTED` Existing AI-friendly output format is preserved for consumers.
|
||||
- *5.1.1.* The standard `logging` module is the diagnostics channel,
|
||||
configured by `fiona.logging_config.setup_logging()`. No new hard
|
||||
dependency.
|
||||
- *acceptance*: CLI entry points call `setup_logging()`.
|
||||
- *5.1.2.* `NOT_IMPLEMENTED` Error and warning diagnostics go to stderr
|
||||
through the logging module. CLI-facing reports stay stdout prints.
|
||||
- *acceptance*: Production modules do not `print` errors. Reports
|
||||
may still print.
|
||||
- *5.1.3.* Existing AI-friendly report format is preserved for consumers.
|
||||
- *acceptance*: Tool output consumed by tests and scripts is unchanged.
|
||||
|
||||
---
|
||||
|
||||
@@ -2010,7 +2048,9 @@ only READMEs.
|
||||
`python_ruff/`, `run_tests.py`, `run_sanity.py`,
|
||||
`settings_dev.json`).
|
||||
- *acceptance*: All markdown documentation passes `mdoctor chklint`.
|
||||
- *5.2.3.* `NOT_IMPLEMENTED` Link `SPEC.md` from `README.md` related documentation.
|
||||
- *5.2.3.* The root `README.md` links this spec under related
|
||||
documentation.
|
||||
- *acceptance*: `README.md` contains a markdown link to `SPEC.md`.
|
||||
|
||||
---
|
||||
|
||||
@@ -2043,36 +2083,37 @@ and every
|
||||
|
||||
## 7. Priority Order
|
||||
|
||||
| Priority | Feature | Section |
|
||||
| -------- | ------- | ------- |
|
||||
| P1 | `wiki update` / `wiki check-update` | 3.1.2 |
|
||||
| P1 | Git wrapper (`save`/`snapshot`/`restore`/`clean`/`undo`) | 3.2 |
|
||||
| P1 | `wiki sanity` incl. dead-link check | 3.1.3 |
|
||||
| P2 | Frontmatter linter (fmlint) | 4.2 |
|
||||
| P2 | Shellcheck library | 4.4 |
|
||||
| P2 | MD code block linting | 4.5 |
|
||||
| P2 | JSON linter (json-lint) | 4.10 |
|
||||
| P2 | HTML/JS linter (html-js-lint) | 4.12 |
|
||||
| P2 | Logging library | 5.1 |
|
||||
| P3 | Frontmatter tags (`date`, `confidence`, `contested`) | 4.8.1 |
|
||||
| P3 | Backup script | 3.2.1 |
|
||||
| P3 | Documentation | 5.2 |
|
||||
| P4 | Non-MD file tracking (py/bash) | 4.6.1 |
|
||||
| P4 | Project clarification | 5.3 |
|
||||
| P2 | MDoctor auto-fix (`mdoctor fix`) | 4.1.1 |
|
||||
| P2 | Lint configuration (`fiona-settings.json`) | 4.1.2 |
|
||||
| P2 | Sanity runner failure reporting | 4.7.1 |
|
||||
| P2 | Wiki root discovery via `fiona-settings.json` | 4.9.1 |
|
||||
| P2 | Settings manager (`fiona-assistant setup`) | 4.11 |
|
||||
| Priority | Feature | Section | Status |
|
||||
| -------- | ------- | ------- | ------ |
|
||||
| P1 | `wiki update` / `wiki check-update` | 3.1.2 | Implemented |
|
||||
| P1 | Git wrapper (`save`/`snapshot`/`restore`/`clean`/`undo`/`status`) | 3.2 | Implemented |
|
||||
| P1 | `wiki sanity` incl. dead-link check | 3.1.3 | Implemented |
|
||||
| P1 | `wiki graph` | 3.1.4 | Implemented |
|
||||
| P2 | Frontmatter linter (fmlint) | 4.2 | Implemented |
|
||||
| P2 | JSON linter (json-lint) | 4.13 | Implemented |
|
||||
| P2 | MDoctor auto-fix (`mdoctor fix`) | 4.1.1 | Implemented |
|
||||
| P2 | Lint configuration (`fiona-settings.json`) | 4.1.2 | Implemented |
|
||||
| P2 | Sanity runner failure reporting | 4.9.1 | Implemented |
|
||||
| P2 | Shellcheck library | 4.6 | Planned |
|
||||
| P2 | MD code block linting | 4.7 | Planned |
|
||||
| P2 | HTML/JS linter (html-js-lint) | 4.12 | Planned |
|
||||
| P2 | Logging library | 5.1 | Partial |
|
||||
| P2 | Wiki root discovery via `fiona-settings.json` | 4.11.1 | Planned |
|
||||
| P2 | Settings manager (`fiona-assistant setup`) | 4.14 | Planned |
|
||||
| P3 | Frontmatter tags (`date`, `confidence`, `contested`) | 4.10.3 | Planned |
|
||||
| P3 | Backup script | 3.2.1 | Planned |
|
||||
| P3 | Documentation | 5.2 | Partial |
|
||||
| P4 | Non-MD file tracking (py/bash) | 4.8.1 | Planned |
|
||||
| P4 | Project clarification | 5.3 | Planned |
|
||||
|
||||
---
|
||||
|
||||
## 8. Open Questions
|
||||
|
||||
- Tagging format for python files and bash scripts [4.6](#46-shellcheck-library)
|
||||
is undecided.
|
||||
- Tagging format for python files and bash scripts [4.8.1](#481-non-md-file-support)
|
||||
is undecided.
|
||||
- Git wrapper location: implemented at `src/gittool/git_tool.py`.
|
||||
- Wiki root discovery [4.9.1](#491-failure-reporting)
|
||||
- Wiki root discovery [4.11.1](#4111-wiki-root-discovery-fiona-settingsjson)
|
||||
: which `fiona-settings.json` wins when
|
||||
several subdirectories contain one, and should ancestor directories be
|
||||
searched as a fallback before falling back to the current directory?
|
||||
|
||||
@@ -18,6 +18,8 @@ Ordered by priority. Each item references its section in [SPEC.md](./SPEC.md)
|
||||
- [x] `version` tag support
|
||||
- [x] `fiona-assistant wiki init` — copy packaged template into a target
|
||||
directory (basic flow; hardening tracked under P1)
|
||||
- [x] Windows PowerShell bootstrap (`bootstrap.ps1`): repo-local venv under
|
||||
`.venvs\<name>`, same flags as the bash `bootstrap`
|
||||
|
||||
## P0 — Packaging and Structure Fixes
|
||||
|
||||
@@ -75,6 +77,9 @@ block a correct install or make the docs contradict the code.
|
||||
- [x] pytests should show which test are failing,
|
||||
- [x] markdownlint should show which files are in violation , what line
|
||||
- [x] same thing for ruff
|
||||
- [ ] Remove the phantom `html_js_lint` package and `html-js-lint` console
|
||||
script from `pyproject.toml` until SPEC 4.12 is implemented. The
|
||||
directory `src/html_js_lint/` does not exist
|
||||
|
||||
## P1 — Wiki Lifecycle and Version Control
|
||||
|
||||
@@ -115,11 +120,12 @@ block a correct install or make the docs contradict the code.
|
||||
WAITING lines, assigned via a carriage-return constant); wiki
|
||||
sanity output unchanged
|
||||
- [x] Frontmatter linter (fmlint) (SPEC 4.2)
|
||||
- [x] Implement `src/mdoctor/fmlint.py` module
|
||||
- [x] Implement `src/customlinter/fmlint.py`
|
||||
- [x] Write TDD tests for fmlint
|
||||
- [x] Add CLI integration: `fiona-assistant fmlint chklint [directory]`
|
||||
- [x] Integrate into `run_sanity.py`
|
||||
- [x] Integrate into `run_sanity.py` and `wiki sanity`
|
||||
- [x] Add settings support via `fiona-settings.json`
|
||||
- [x] SKILL.md name, folder, and description checks (FML004-FML006)
|
||||
- [x] Generalize compress and format violations for all linters
|
||||
(SPEC 4.3.1, 4.9.3)
|
||||
- [x] `BaseLinter` provides `compress_violations()` and
|
||||
@@ -133,23 +139,25 @@ block a correct install or make the docs contradict the code.
|
||||
`dict[rel_path, list[dict]]`) onto the shared base format
|
||||
- [x] Keep all linter reports diffable: same sections, same order
|
||||
(update SPEC 4.1/4.5 and tests together)
|
||||
- [ ] JSON linter (json-lint) (SPEC 4.10)
|
||||
- [ ] Implement `src/json_lint/json_lint.py` module
|
||||
- [ ] Write TDD tests for json-lint
|
||||
- [ ] JSON syntax validation using standard `json` module
|
||||
- [ ] JSON style rules (indentation, trailing commas, key ordering)
|
||||
- [ ] Add CLI integration: `fiona-assistant json-lint chklint [directory]`
|
||||
- [ ] Support `--fix` flag for auto-fixing certain violations
|
||||
- [ ] Add settings support via `fiona-settings.json` (json section)
|
||||
- [ ] Integrate into `run_sanity.py`
|
||||
- [ ] Shellcheck library (SPEC 4.4)
|
||||
- [x] JSON linter (json-lint) (SPEC 4.13)
|
||||
- [x] Implement `src/customlinter/jsonlint.py`
|
||||
- [x] Write TDD tests for json-lint
|
||||
- [x] JSON syntax validation using the standard `json` module
|
||||
- [x] JSON style rules (indentation, trailing commas, key ordering)
|
||||
- [x] CLI: `fiona-assistant json-lint chklint` and `fix`
|
||||
- [x] Settings via the `json` section of `fiona-settings.json`
|
||||
- [x] Integrated into `run_sanity.py` and `wiki sanity`
|
||||
- [ ] Shellcheck library (SPEC 4.6)
|
||||
- [ ] add shellcheck to toml
|
||||
- [ ] Wrap shellcheck like `python_ruff` (AI-friendly violation report)
|
||||
- [ ] Clear install-hint error when shellcheck is missing
|
||||
- [ ] Lint fenced code blocks inside MD files (SPEC 4.5)
|
||||
- [ ] Lint fenced code blocks inside MD files (SPEC 4.7)
|
||||
- [ ] Python blocks via Ruff, shell blocks via shellcheck
|
||||
- [ ] Logging library instead of `print` across the codebase (SPEC 5.1)
|
||||
- [ ] Diagnostics to stderr with levels; preserve tool output format
|
||||
- [ ] Logging library instead of `print` for diagnostics (SPEC 5.1)
|
||||
- [x] Shared `fiona.logging_config.setup_logging()` on CLI entry points
|
||||
- [ ] Error and warning diagnostics go to stderr through logging.
|
||||
CLI reports stay stdout prints. `git_tool`, `graph_generator`,
|
||||
and several CLIs still `print` errors
|
||||
- [x] Clear existing lint violations (SPEC 1 constraint: Ruff and
|
||||
PyMarkdown must pass)
|
||||
- [x] Ruff: 0 violations — removed unused imports and unnecessary
|
||||
@@ -161,10 +169,7 @@ block a correct install or make the docs contradict the code.
|
||||
`front-matter` extension (files with frontmatter no longer raise
|
||||
phantom MD003/MD022/MD041) and ignores the frontmatter `title`
|
||||
for MD025
|
||||
- [ ] Make a framework, so that when `fiona-assistant` is called
|
||||
`fiona-settings.json` is read and all tools can see it
|
||||
(SPEC 4.9.1)
|
||||
- [ ] it signifies that is the root of the llm-wiki
|
||||
- [ ] Settings manager, `fiona-assistant setup` (SPEC 4.14)
|
||||
- [x] When running sanity, make sure that markdownlint tests also include
|
||||
outer dir of the src/ because there are markdown files there
|
||||
- [x] in `run_sanity.py`, show the failing test function and assert ex.
|
||||
@@ -232,11 +237,11 @@ WARNING run_tests: pytest short summary missing from output; failure details com
|
||||
environment in `_sanitize_pytest_env` (pytest skips summary
|
||||
trimming when `CI` is set); keep junit parsing as the safety net
|
||||
|
||||
- [ ] in toc generator settings, add a per file rule, (TBD: put in spec)
|
||||
- [ ] when a rule matches a file, it will follow the defined settings in the dictionari
|
||||
- [x] in toc generator settings, per-file glob overrides in the `file`
|
||||
section (SPEC 4.10.2)
|
||||
- [ ] instead of current directory as default, find a fiona-settings.json
|
||||
in the current directory / subdirectory, that will be the llm-wiki
|
||||
root and default directory for commands (SPEC 4.9.1)
|
||||
root and default directory for commands (SPEC 4.11.1)
|
||||
- [ ] Enable the pymarkdown `markdown-tables` extension in
|
||||
`fiona-settings.json` so table rules (MD055/MD056/MD058) run in
|
||||
`run_sanity.py` (SPEC 4.1.2 known limitation)
|
||||
@@ -249,25 +254,26 @@ WARNING run_tests: pytest short summary missing from output; failure details com
|
||||
|
||||
- [ ] Backup script for llm-wiki so users can recover if something goes
|
||||
wrong (SPEC 3.2.1)
|
||||
- [ ] Frontmatter tags on MD files (SPEC 4.8.1)
|
||||
- [ ] Frontmatter tags on MD files (SPEC 4.10.3)
|
||||
- [x] `version`
|
||||
- [ ] `date` tag
|
||||
- [ ] Quality signal: `confidence`
|
||||
- [ ] `contested` flag (true if claims are disputed)
|
||||
- [ ] Project documentation (SPEC 5.2)
|
||||
- [ ] Write `src/README.md` with project description
|
||||
- [ ] Setup instructions (`pip install -e .`)
|
||||
- [ ] Usage examples for librarian and mdoctor
|
||||
- [ ] Update `librarian/README.md` with actual usage info
|
||||
- [ ] Add `mdoctor/README.md`
|
||||
- [x] Root `README.md` links `SPEC.md`
|
||||
- [x] Root README and `AGENTS.md` document `bootstrap` and `bootstrap.ps1`
|
||||
- [ ] Refresh `librarian/README.md` and `mdoctor/README.md` for the
|
||||
current subcommands (`list`, `toc`, `chklint`, `fix`)
|
||||
- [ ] Refresh `src/README.md` structure (`wiki/`, `python_ruff/`,
|
||||
`run_tests.py`, `run_sanity.py`, `settings_dev.json`)
|
||||
- [ ] Process hygiene: use semantic commit prefixes
|
||||
(`feat:`, `fix:`, `docs:`, ...) per project agent rule 8.1
|
||||
- [ ] `fiona-assistant wiki graph` make a class that can generate the obsidian style
|
||||
graph/link for md files association in html format (SPEC 3.1.4.)
|
||||
- [x] `fiona-assistant wiki graph` (SPEC 3.1.4): link parser, graph,
|
||||
HTML template, and CLI in `src/wiki/graph_generator.py`
|
||||
|
||||
## P4 — Design Decisions Needed
|
||||
|
||||
- [ ] Librarian: version tracking for non-MD files (SPEC 4.6.1)
|
||||
- [ ] Librarian: version tracking for non-MD files (SPEC 4.8.1)
|
||||
- [ ] Python files — format TBD
|
||||
- [ ] Bash scripts — format TBD
|
||||
- [ ] Decide the tagging format before implementing
|
||||
@@ -282,6 +288,8 @@ WARNING run_tests: pytest short summary missing from output; failure details com
|
||||
|
||||
## Open Questions (SPEC)
|
||||
|
||||
- Tagging format for python files and bash scripts (SPEC 4.6.1)
|
||||
- Git wrapper location: `src/vcs/` vs `src/librarian/vcs.py` (SPEC 3.2)
|
||||
- make a class for generating html graph for md linkages like obsidian
|
||||
- Tagging format for python files and bash scripts (SPEC 4.8.1)
|
||||
- Git wrapper location: implemented at `src/gittool/git_tool.py` (SPEC 3.2)
|
||||
- Wiki root discovery (SPEC 4.11.1): the nearest `fiona-settings.json`
|
||||
wins; error when two at the same depth are equally near. Ancestor
|
||||
search is still open.
|
||||
|
||||
Reference in New Issue
Block a user