update the spec

This commit is contained in:
nvaldez
2026-09-29 10:10:20 +02:00
parent e6920aa691
commit 859d2e55d7
2 changed files with 323 additions and 274 deletions
+281 -240
View File
@@ -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?
+42 -34
View File
@@ -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.