Files
fiona-assistant/SPEC.md
T
2026-09-25 22:42:14 +02:00

45 KiB

name, version, title, created, updated, type
name version title created updated type
Fiona-Assistant Specification 0.17.0 Project Spec Sheet 2026-09-23 2026-09-24 summary

Fiona-Assistant Specification

Spec sheet for the Fiona-Assistant toolkit. Derived from the current codebase state. Each feature section opens with a Status line followed by requirements and acceptance criteria. Status values: Implemented, Partially Implemented, Planned, Won't Do.

The spec is organized in three parts: llm-wiki specifications (the content system the tools operate on), Fiona tool specifications (one numbered section per src/ tool — add new tools as a new numbered section there), and project infrastructure (cross-cutting concerns).


Product Overview

Fiona-Assistant is a CLI toolkit for managing, organizing, and maintaining LLM wiki content with minimal AI token dependence.

Core philosophy: use deterministic scripts for deterministic tasks, reserve LLM tokens for creative and analytical work.

Constraints that apply to every feature:

  • All tool output must be AI-friendly: parseable, consistently structured (see output format examples in README.md).
  • Interaction model — interactive by default for humans, flags for AI: when a command needs confirmation or input, prompt interactively; the same command must also run non-interactively through explicit flags (e.g. --force, --yes) so AI agents get deterministic behavior without a TTY.
  • All code changes follow TDD (tests first, python src/run_tests.py green).
  • python src/run_sanity.py must pass before any change is finalized.
  • Python code passes Ruff; markdown passes PyMarkdown lint.
  • Directory permissions are enforced: personal/ and raw/ are read-only for agents; wiki/concepts/ is read-write.

Current Capabilities

All commands below are implemented and reachable through the single fiona-assistant console script (section 2.8). Every optional [directory] argument currently defaults to the current directory; the planned wiki root discovery (2.8.1) will replace that default with the directory containing fiona-settings.json.

fiona-assistant

  • No args: print the command help and exit 0.

fiona-assistant librarian [directory]

  • No subcommand: default to list . — list all files recursively.
  • list [directory]: List all files in the directory tree.
  • toc [directory]: Generate a table_of_contents.md per folder: every md file with its frontmatter version and its headers as anchored links.

fiona-assistant mdoctor [subcommand] [directory]

  • No subcommand: default to chklint . — lint the current directory.
  • list [directory]: List all files in the directory tree.
  • chklint [directory]: Scan markdown with pymarkdown and print an AI-friendly violation report (file, line:column, rule).
  • fix [directory]: Apply pymarkdown auto-fixes in place; print the number of fixed files followed by each path.

fiona-assistant python-ruff [subcommand] [directory]

  • No subcommand: default to chklint . — lint the current directory.
  • chklint [directory]: Lint Python sources with ruff and print an AI-friendly violation report (file, line:column, rule code).

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 the packaged template; refuses with FileExistsError if an llm-wiki structure already exists.
  • check-update [directory]: Check for updates to llm-wiki core files against the packaged template version. Supports --json flag for AI-friendly output format.
  • update [directory] [-f|--force] [-y|--yes] [--dry-run]: Update core files in the wiki to the current template version. Note: the fiona-settings.json file receives special handling to preserve user customizations when updating.

Notes:

  • Invalid directories exit 1 with an error message on stderr.
  • chklint commands print violations in their report but exit 0; the violation count lives in the output, not the exit code.
  • The standalone console scripts librarian and mdoctor behave like fiona-assistant librarian list and the fiona-assistant mdoctor subcommands respectively.
  • librarian toc accepts --recursive-toc, --non-recursive, and repeatable --exclude REGEX flags (see 2.7). Depth limits come from the markdown.toc_generator section of the packaged fiona-settings.json (max_depth_from_file, max_depth_from_dir; absent or 0 = unlimited, see 2.7).

llm-wiki Specifications

1.1 llm-wiki Lifecycle Management

Status: Partially Implemented

Covers: wiki init (implemented, 1.1.1), wiki update (planned, 1.1.2), wiki sanity (planned, 1.1.3).

1.1.1 wiki init

Status: Implemented

Covers: src/wiki/wiki.py and the fiona-assistant wiki init subcommand (see 2.8).

Initialize the current or given directory as an llm-wiki directory by copying the packaged template (structure + core files) from src/llm-wiki/, replacing DATE_PLACEHOLDER with the current UTC date.

Requirements:

  • If target directory already contains an llm-wiki structure, refuse rather than silently overwriting: the command raises FileExistsError naming the conflicting indicator files (AGENTS.md, fiona-settings.json, wiki/, ingest/, README.md).
  • Copied files carry frontmatter with version and created/updated dates.
  • The template copy skips Python files and __pycache__ artifacts so only content ships to user wikis.

Acceptance criteria:

  • Running wiki init on an empty directory produces a valid llm-wiki tree that passes mdoctor chklint (and wiki sanity once 1.1.3 ships).
  • Re-running on an initialized directory fails with FileExistsError and does not clobber user content.

1.1.2 wiki update

Status: Partially Implemented

Update an existing llm-wiki directory to the current template version.

Covers: src/wiki/update_manager.py and the fiona-assistant wiki update and fiona-assistant wiki check-update subcommands.

Requirements:

  • Compare version frontmatter of each core md file/script against the packaged template; update only files whose template version is newer.
  • For files without version tagging (e.g., JSON files), compare SHA256 hashes to detect differences.
  • Update directory structure if the template structure changed (add missing directories, never delete user content).
  • Never overwrite files with local modifications (version bumped or content diverged) silently: confirm interactively when a human runs the command, and provide an explicit flag (e.g. --force or --yes) so AI agents can run it non-interactively (see Product Overview interaction model); report skipped files instead.
  • Respect read-only zones (personal/, raw/).
  • Special handling for fiona-settings.json: when updating, merge user customizations from the existing file with the new template version, giving priority to user values for user-configurable fields. This ensures user settings are preserved across updates.
  • wiki check-update command: check and report what files need updating without modifying anything. Supports --json flag for AI-friendly output format.
  • wiki update command: perform the actual updates. Supports --dry-run flag to preview changes without applying them, and --json flag for AI-friendly output format.

Acceptance criteria:

  • On a pristine wiki init output, wiki check-update reports "already up to date" and wiki update is a no-op.
  • On a wiki with outdated core files, wiki check-update identifies all files that need updates and wiki update updates only those files.
  • Settings files are updated with user customizations preserved.
  • Files in read-only zones are never modified.
  • Running with --force or --yes skips interactive confirmation.
  • Running with --dry-run shows what would be updated without making changes.

1.1.3 wiki sanity

Status: Planned

Run all validation checks over an llm-wiki directory in one command.

Requirements:

  • Runs markdown lint (mdoctor), Python lint (python-ruff), and any other registered linters (shellcheck once 2.3 ships).
  • Checks for dead links (relative and wiki-internal links resolving to existing files).
  • Aggregated, AI-friendly summary report: per-check pass/fail, violation counts, overall exit code.

Acceptance criteria:

  • Exits 0 on a clean wiki, non-zero on any violation.
  • A wiki containing a link to a deleted file is reported as a dead link.

1.2 Git Version Control for llm-wiki

Status: Planned

Local version control, snapshot, and backup of wiki content via a GitPython wrapper module (proposed: src/librarian/vcs.py or src/vcs/).

Requirements:

  • Operates on the llm-wiki directory (auto-initialize a repo on first use).
  • Never touches personal/ (leave it to user-owned git config or exclude it explicitly).
  • All operations produce concise, parseable output.

Operations:

Command Behavior
save Commit current edits with message yyyy-mm-dd HH:MM:SS <description>
snapshot save, then create an annotated git tag yyyy-mm-dd_<tag_name>
restore Restore the wiki to the state of <tag_name>
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

Acceptance criteria:

  • save on a dirty tree produces a commit with the specified message format.
  • undo on a dirty tree fails with a clear error message mentioning clean.
  • snapshot then restore <tag_name> returns file contents to the tagged state.
  • clean leaves git status empty.

1.2.1 Backup Script

Status: Planned

A user-facing backup mechanism so content can be recovered if something goes wrong.

Requirements:

  • Bundled script (llm-wiki utils/ or CLI subcommand) that creates a restorable backup of the wiki directory.
  • Backups are timestamped and stored outside the wiki tree.
  • Documented restore procedure.

Acceptance criteria:

  • A backup taken before a destructive operation can restore the wiki to the pre-operation state.

Fiona Tools Specifications

Each tool under src/ gets its own numbered section; insert new tools as the next free section number.

2.1 mdoctor (Markdown Lint)

Status: Implemented

Covers: src/mdoctor/. Wraps the pymarkdown linter over markdown sources with an AI-friendly aggregated violation report (file, line:column, rule). Also provides mdoctor list [directory], which lists all files (not only md) in a directory via the librarian (see 2.5).

2.1.1 MDoctor Auto-Fix (mdoctor fix)

Status: Implemented

Invoke the PyMarkdown auto-fix from the CLI so lint violations with fix-capable rules can be repaired deterministically.

Requirements:

  • fiona-assistant mdoctor fix [directory] and mdoctor fix [directory] run the pymarkdown auto-fix recursively over the target directory (default: current directory).
  • Only rule violations whose plugins support auto-fix are repaired; files are modified in place.
  • Output is AI-friendly and parseable: the number of fixed files followed by the path of each fixed file.
  • Invalid directories and pymarkdown API failures produce a clear error on stderr with a non-zero exit code, not a stack trace.
  • Limitation: the command does not exclude read-only zones (personal/, raw/) by itself; do not point it at a tree containing them until zone exclusion is added (future hardening).

Acceptance criteria:

  • Running mdoctor fix on a directory whose md file has an auto-fixable violation (e.g. MD047, missing trailing newline) repairs the file and lists its path.
  • A directory with nothing to fix reports 0 file(s) fixed.
  • An invalid directory exits 1 with an error message.

2.1.2 Lint Configuration (fiona-settings.json)

Status: Implemented

pymarkdown rule configuration is data-driven via fiona-settings.json (shipped with the llm-wiki template and copied into user wikis by wiki init).

Requirements:

  • The markdown.pymarkdown section supports:
    • extensions: list of pymarkdown extension identifiers to enable (e.g. front-matter, so YAML frontmatter is not parsed as setext headings)
    • respect_gitignore: bool; when true, scans and fixes skip files excluded by .gitignore (run_sanity.py relies on this to skip build artifacts)
    • <rule_id>: per-rule property maps; the JSON value type selects the API call (bool → set_boolean_property, int → set_integer_property, str → set_string_property)
  • Known limitation — tables are invisible to sanity: pymarkdown only parses pipe tables when the markdown-tables extension is enabled, and enabling it is blocked. pymarkdownlnt 0.9.40 (latest at the time of writing) crashes with BadTokenizationError on list lines that contain pipes (e.g. generated table_of_contents.md entries for headers like ## [date] create | subject), which breaks run_sanity.py on this repo. Until an upstream fix lands, no table rule (MD055/MD056/MD058/MD060) runs in sanity. The Node.js markdownlint used by IDE extensions parses tables natively, which is why table style errors (MD060) appear in the IDE but not in run_sanity.py. Enable the extension once pymarkdown is fixed.
  • MD060 (table-column-style) is explicitly disabled for when that day comes: pymarkdown's implementation (new in pymarkdownlnt 0.9.40, plugin v0.5.0) enforces different delimiter-row expectations than the Node.js markdownlint used by IDE extensions (it flags well-formed compact tables whose delimiter width differs from the cell width). Revisit once the implementations converge.
  • Project table style is "compact": one space around cell content in header, body, and delimiter rows (e.g. | --- | ------- |), which satisfies the Node.js markdownlint MD060 compact style.
  • MDoctor loads the settings file dynamically at construction (default: the packaged llm-wiki fiona-settings.json, overridable via settings_file=), so run_sanity.py and mdoctor fix apply the configured rules without code changes.
  • A missing settings file falls back to plain pymarkdown defaults.

Supported keys today (all under markdown.pymarkdown unless marked otherwise):

Key Status Effect
extensions Implemented Extension ids enabled at scan/fix time (today: front-matter)
respect_gitignore Implemented Skip files excluded by .gitignore
md025.front_matter_title Implemented no-match: frontmatter title ignored by MD025
md013 Implemented Line length 100; code blocks and tables exempt
md060.enabled Implemented False; table style rule diverges from Node.js (see above)
python.ruff Reserved Unused placeholder for future ruff config (2.2)
markdown.toc_generator.max_depth_from_file Implemented Header level cap per file in TOCs
markdown.toc_generator.max_depth_from_dir Implemented Subfolder recursion cap for TOCs

How to extend the file (no code changes required):

  1. Look up the pymarkdown rule id and its property names in the pymarkdown rule documentation (e.g. md013 owns line_length).

  2. Add a property map under markdown.pymarkdown, keyed by the rule id — the existing md013 entry shows the shape:

    "md013": {
        "line_length": 100,
        "code_blocks": false,
        "tables": false
    }
    
  3. The JSON value type selects the pymarkdown API call, applied as plugins.<rule_id>.<property>: bool → set_boolean_property, int → set_integer_property, str → set_string_property.

  4. To toggle an entire rule, set "enabled": false inside its map (see md060 above).

  5. To enable a parser extension, append its identifier to extensions (front-matter today; for markdown-tables read the known limitation above first).

  6. Verify with python src/run_sanity.py; the new configuration applies at the next scan.

  7. Caution: typos fail silently. Invalid rule ids and property names are accepted without any error and simply have no effect — pymarkdown validates neither at MDoctor construction nor during the scan. Confirm a new setting by observing its effect on scan results (e.g. a file that violates the rule just configured).

Related but separate: the sanity coverage gate lives in src/settings_dev.json (pytests.required-coverage, see 2.6.2), 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 (1.1.1) and it marks the wiki root (2.8.1).

Acceptance criteria:

  • Changing a rule in fiona-settings.json (e.g. md013.line_length) changes scan results on the next run, with no code changes.
  • Scanning a file whose only issue is a line between the default and configured md013.line_length reports no violation.
  • A table with a structural defect (e.g. missing blank line before it) is reported by run_sanity.py — blocked until the pymarkdown markdown-tables crash is fixed and the extension can be enabled (see the known limitation above).

2.1.3 Frontmatter Linter (fmlint)

Status: Planned

Covers: src/mdoctor/fmlint.py. A custom linter specifically for validating markdown file frontmatter against project requirements. This ensures all md files have the required name and version fields for source control and version tracking (see AGENTS.md Rule 8).

2.1.3.1 Frontmatter Validation

Status: Planned

Validate that all markdown files in an llm-wiki directory have proper frontmatter with required fields.

Requirements:

  • Scan all .md files in a directory tree for frontmatter presence.
  • Validate that required fields are present: name and version (minimum for source control per AGENTS.md Rule 8).
  • Support configurable required fields via fiona-settings.json for different file types (e.g., type: toc files may have different requirements).
  • Report violations in AI-friendly format: file path, missing fields, and line number (if known). Violation messages use the format <code> - <message>. For frontmatter violations, line numbers are omitted as frontmatter is always at the start of the file (line 1), so 1:1 prefix is redundant.
  • Handle files without frontmatter (report as missing all required fields).
  • Handle files with malformed YAML frontmatter (report as parse error).
  • Respect .gitignore and read-only zones (personal/, raw/).

Acceptance criteria:

  • A md file missing name field is reported with file path and missing field.
  • A md file missing version field is reported with file path and missing field.
  • A md file with no frontmatter at all is reported as missing all required fields.
  • A md file with malformed YAML frontmatter is reported with parse error details.
  • Running on a directory with all valid frontmatter reports no violations.
  • The linter integrates with wiki sanity (1.1.3) and run_sanity.py (2.6).

2.1.3.2 CLI Integration

Status: Planned

Provide CLI access to the frontmatter linter via fiona-assistant.

Requirements:

  • fiona-assistant fmlint chklint [directory] scans for frontmatter violations.
  • fiona-assistant fmlint with no subcommand defaults to chklint ..
  • Output format matches other linters: AI-friendly violation report with file paths, line numbers, and rule codes.
  • Exit code 0 even with violations (consistent with other linters).

Acceptance criteria:

  • Running fiona-assistant fmlint on a directory with invalid frontmatter produces a structured violation report.
  • Running on a clean directory reports no violations.

2.1.3.3 Settings Integration

Status: Planned

Configure frontmatter linter behavior via fiona-settings.json.

Requirements:

  • Load required fields from markdown.frontmatter.required_fields in fiona-settings.json (default: ['name', 'version']).
  • Support per-type requirements: markdown.frontmatter.type_requirements maps file types to their specific required fields.
  • Allow disabling the linter via markdown.frontmatter.enabled (default: true).
  • Support ignoring specific violation rules via markdown.frontmatter.ignore_rules (e.g., ['FML002'] to ignore missing frontmatter).
  • Support ignoring specific file patterns via markdown.frontmatter.ignore_file (e.g., ['*/AGENTS.md', '*/README.md'] to skip certain files).

Acceptance criteria:

  • Changing required fields in fiona-settings.json changes validation behavior on the next run.
  • Disabling the linter via settings skips frontmatter validation.
  • Rules listed in ignore_rules are not reported as violations.
  • Files matching patterns in ignore_file are skipped during linting.

2.1.3.4 SKILL.md Validation

Status: Implemented

Special validation for files named SKILL.md to ensure skill name conventions and required fields.

Requirements:

  • For any file named SKILL.md (case-sensitive), validate the name field in frontmatter.
  • Skill name must only contain lowercase letters, numbers, and hyphens (regex: ^[a-z0-9-]+$).
  • Skill name must match the parent folder name (e.g., SKILL.md in folder python-tdd/ must have name: python-tdd).
  • SKILL.md files must have a description field in frontmatter.
  • Report violations with rule code FML005 for invalid characters, FML006 for folder name mismatch, and FML004 for missing description.

Acceptance criteria:

  • A SKILL.md file with name: Python TDD is reported with FML005 violation.
  • A SKILL.md file in folder python-tdd/ with name: python-tdd passes validation.
  • A SKILL.md file in folder python-tdd/ with name: other-name is reported with FML006 violation.
  • A SKILL.md file with valid lowercase name matching folder passes validation.
  • A SKILL.md file without a description field is reported with FML004 violation.

2.2 python-ruff (Python Lint)

Status: Implemented

Covers: src/python_ruff/. Wraps the external ruff linter over Python sources, mirroring the mdoctor report pattern.

Requirements:

  • Violations report file, line:column, and rule code in an AI-friendly aggregated report.
  • Integrated into the sanity runner (2.6).
  • The library supports auto-fix: PythonRuff.lint(target, fix=True) passes --fix through to the ruff binary and modifies files in place. Limitation: the capability is not yet exposed as a CLI subcommand (future: python-ruff fix, mirroring 2.1.1).

Acceptance criteria:

  • A file with a lint violation (e.g. an unused import) is reported with file, position, and rule code.

2.3 Shellcheck Library

Status: Planned

Lint bash/shell scripts in the wiki and project.

Requirements:

  • Wrap shellcheck following the same pattern as python_ruff (external linter, AI-friendly aggregated violation report).
  • Graceful error when shellcheck is not installed on the system.
  • Integrated into wiki sanity (1.1.3).

Acceptance criteria:

  • Running against a directory with a shell script containing a known shellcheck violation reports file, line, and rule code.
  • Missing binary produces a clear install-hint message, not a stack trace.

2.4 MD Code Block Linting

Status: Planned

Lint fenced code blocks inside markdown files for quality.

Requirements:

  • Extract fenced code blocks from md files and lint them by language: python blocks via Ruff, shell blocks via shellcheck, others skipped.
  • Report violations with the md file path and the position inside the code block (block index and line within block, plus md line offset).
  • Integrated into wiki sanity (1.1.3).

Acceptance criteria:

  • A md file whose python code block has an unused import is reported.
  • Non-code md content produces no false positives.

2.5 librarian (Content Management)

Status: Implemented

Covers: src/librarian/ (librarian.py, md_frontmatter). Wiki content operations: file listing, frontmatter parsing, validation, and version tracking.

2.5.1 Non-MD File Support

Status: Planned

Extend frontmatter-style tracking beyond md files.

  • Python files: TBD — likely version header/docstring-based tracking.
  • Bash scripts: TBD — likely comment-based version tags.

Acceptance criteria: TBD once the format is decided. Blocked on a design decision; do not implement until the tagging format is specified.


2.6 Test and Sanity Runners

Status: Implemented

Covers: src/run_tests.py (TestRunner) and src/run_sanity.py (parallel pytests with a coverage gate, markdownlint, and ruff checks; see 2.6.1 and 2.6.2).

2.6.1 Failure Reporting

Status: Implemented

The sanity runner names every failing test and its assert explanation without depending on pytest's terminal formatting.

Requirements:

  • The pytest report in run_sanity.py lists per-file pass/fail counts with each failing test nested under its file entry as Class : test_name, followed by the assert explanation (or the raw exception message when no assert line exists).
  • The Sanity Failed verdict lists only the failing test names; the assert details live in the report body, not the verdict.
  • run_tests.py runs pytest with a temporary JUnit XML report (junit_family=xunit1) and parses failure ids, locations, and messages from it, so details survive terminal formatting quirks (missing short summary, colors, plugin output).
  • Regex-parsed pytest output stays the preferred source for displayed messages; junit entries fill missing fields, replace entries without a real message, and never duplicate entries across path forms (matched by file basename and test name).
  • The pytest command pins --color=no; a missing short summary logs a WARNING naming the likely causes (PYTEST_ADDOPTS, --no-summary, plugin output).
  • Logging is configured from the LOG_LEVEL environment variable (default WARNING); module loggers carry the level explicitly because pymarkdown resets the root logger to WARNING mid-run.

Acceptance criteria:

  • A failing test appears under its file entry with name and assert even when pytest's short summary is suppressed (e.g. PYTEST_ADDOPTS=--no-summary).
  • The full suite passes in environments with a suppressed short summary or forced colors (PY_COLORS=1).
  • LOG_LEVEL=DEBUG shows the pytest command, return code, parsed failure details, and the raw pytest output on parse mismatches.

2.6.2 Coverage Gate

Status: Implemented

The sanity runner enforces a minimum test coverage threshold loaded from src/settings_dev.json.

Requirements:

  • run_sanity.py loads pytests.required-coverage from src/settings_dev.json (currently 96%) and fails the pytests check when the total coverage is below it, even if every test passes.
  • The summary prints a separate coverage: line (PASS/FAIL - <percent>% (required <percent>%)); under Sanity Failed, a coverage shortfall is listed as its own entry.

Acceptance criteria:

  • A run with all tests passing but coverage below the requirement fails sanity.
  • Raising required-coverage in settings_dev.json changes the verdict with no code changes.

2.7 toc-generator (Table of Contents)

Status: Implemented

Covers: src/librarian/toc_generator.py. Generates a table_of_contents.md per folder, listing every md file with its frontmatter version and its headers as anchored links.

Requirements:

  • Each covered folder gets a table_of_contents.md with YAML frontmatter (title, created, updated, type: toc).
  • Entries list folders, file links, and the file's frontmatter version (shown as v<version>; v0.0.0 when missing or unreadable).
  • Headers inside each file are nested as links with GitHub-style anchors; fenced code blocks are not scanned for headers.
  • The TOC file itself, hidden folders, and exclude-pattern matches are skipped; --recursive-toc writes a TOC in every subfolder.
  • --non-recursive limits a TOC to the md files directly in the folder (default: recursive file collection within the folder).
  • --exclude REGEX (repeatable) excludes matching files and folders from the TOC and from recursion.
  • Files are read BOM-tolerantly (utf-8-sig) so a leading BOM does not hide the first header.
  • Depth limits are data-driven from the markdown.toc_generator section of fiona-settings.json (loaded from the packaged llm-wiki template, see 2.1.2):
    • max_depth_from_file caps the header level listed per file (e.g. 3 lists h1 through h3; deeper headers are omitted)
    • max_depth_from_dir caps how deep a TOC recurses into subfolders (e.g. 1 lists files in the folder and its direct subfolders)
    • An absent key or 0 means unlimited (today's behavior); any other value must be a non-negative integer, otherwise the command exits 1 with a clear error naming the offending key
    • --non-recursive still forces direct files only regardless of max_depth_from_dir

Acceptance criteria:

  • A folder with two md files gets a TOC listing both files with their versions and headers.
  • A header inside a fenced code block does not appear in the TOC.
  • An md file matching an exclude pattern is not listed.
  • With max_depth_from_file: 3, a file's #### header does not appear in the TOC while its ### header does; with the key absent or 0, every header level is listed.
  • With max_depth_from_dir: 1, md files two subfolder levels deep are not listed; with the key absent or 0, the whole tree is listed.

2.7.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

Requirements:

  • Frontmatter is validated by the md_frontmatter module (see 2.5).
  • New tags follow the frontmatter schema in AGENTS.md Rule 8.
  • wiki sanity warns on files missing required tags.

Acceptance criteria:

  • A concept note missing confidence is flagged by wiki sanity.

2.8 fiona (CLI Entry Point)

Status: Implemented

Covers: src/fiona/__main__.py. The fiona-assistant console script 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.

Command tree:

Command Behavior
fiona-assistant librarian [directory] List files via librarian (2.5)
fiona-assistant librarian list [directory] Same as above
fiona-assistant librarian toc [directory] Generate a TOC (2.7)
fiona-assistant mdoctor [args] Delegate to the mdoctor CLI; defaults to chklint .
fiona-assistant python-ruff [args] Delegate to the python-ruff CLI; defaults to chklint .
fiona-assistant wiki init [directory] Initialize an llm-wiki (1.1.1)

Requirements:

  • With no subcommand, print help and exit 0.
  • Delegation rewrites sys.argv and calls the target tool's argparse CLI, so behavior matches the standalone tools.

Acceptance criteria:

  • Each subcommand behaves identically to the corresponding standalone CLI (covered by src/tests/test_fiona_main.py).

2.8.1 Wiki Root Discovery (fiona-settings.json)

Status: Planned

fiona-settings.json marks the root of an llm-wiki. When it is present, commands should target the wiki root instead of the current directory.

Current behavior: every command's optional [directory] argument defaults to the current directory; the dispatcher does not consult fiona-settings.json when picking a target.

Planned behavior:

  • When fiona-assistant is invoked, locate the nearest fiona-settings.json: first in the current directory, then in its subdirectories.
  • The directory containing that file is the llm-wiki root and becomes the default directory for every command that accepts an optional [directory] (librarian list/toc, mdoctor list/chklint/fix, python-ruff chklint, wiki init).
  • An explicit [directory] argument always overrides the discovered root.
  • When no fiona-settings.json is found, commands keep the current directory as the default (today's behavior).
  • The settings file is loaded once per invocation and shared by all tools; mdoctor already consumes it for lint rules (see 2.1.2).

Acceptance criteria:

  • Running fiona-assistant mdoctor from inside a wiki subdirectory lints the wiki root, not the subdirectory.
  • Running fiona-assistant librarian inside a wiki lists the wiki root's files.
  • With no fiona-settings.json in or below the current directory, behavior is unchanged from today.

2.9 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).

2.9.1 JSON Syntax Validation

Status: Planned

Validate that JSON files have correct syntax and are parseable.

Requirements:

  • Use Python's standard json module for syntax validation.
  • Check that all JSON files in the target directory tree are valid JSON.
  • Report syntax errors with file path, line number, and column position.
  • Handle files with .json extension by default; support configurable extensions via settings.
  • Respect .gitignore and read-only zones (personal/, raw/).

Acceptance criteria:

  • A JSON file with a syntax error (e.g., missing comma, unquoted key) is reported with file path and error location.
  • A JSON file with valid syntax but no style violations reports no errors.
  • Running on a directory with no JSON files produces no errors.

2.9.2 JSON Style Rules

Status: Planned

Apply configurable style rules to JSON files.

Requirements:

  • Check indentation: tabs should be converted to spaces, with configurable indent length (default: 2 spaces per the project standard).
  • Check trailing commas (optional based on settings).
  • Check key ordering (optional based on settings).
  • Check for duplicate keys in objects.
  • 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.
  • A missing json section in settings uses sensible defaults.

Acceptance criteria:

  • A JSON file with tab indentation when indent: "space" and indent_len: 2 is configured reports a style violation.
  • A JSON file with 4-space indentation when indent_len: 2 is configured reports a style violation.
  • A JSON file with duplicate keys is reported as a violation.

2.9.3 CLI Integration

Status: Planned

Provide CLI access to the JSON linter via fiona-assistant.

Requirements:

  • fiona-assistant json-lint chklint [directory] scans for JSON violations.
  • fiona-assistant json-lint with no subcommand defaults to chklint ..
  • Output format matches other linters: AI-friendly violation report with file paths, line numbers, column numbers, and rule codes.
  • Exit code 0 even with violations (consistent with other linters).
  • Support --fix flag to auto-fix certain violations (indentation, trailing commas) in place.

Acceptance criteria:

  • Running fiona-assistant json-lint on a directory with invalid JSON produces a structured violation report.
  • Running on a clean directory reports no violations.
  • Running with --fix on a file with fixable violations corrects the file and reports the number of fixed files.

2.9.4 Sanity Integration

Status: Planned

Integrate the JSON linter into the sanity checker.

Requirements:

  • run_sanity.py runs json-lint chklint on the codebase.
  • wiki sanity (1.1.3) runs json-lint chklint on the wiki directory.
  • JSON lint violations are reported in the aggregated sanity output.

Acceptance criteria:

  • A JSON file with violations causes run_sanity.py to report JSON lint failures.
  • wiki sanity reports JSON violations alongside other linter violations.

2.10 settings_manager (Settings Management)

Status: Planned

Covers: src/fiona/settings_manager.py. Provides interactive and non-interactive settings management for fiona-assistant.

2.10.1 Interactive Setup (fiona-assistant setup)

Status: Planned

Run an interactive setup utility to configure fiona-assistant settings.

Requirements:

  • Present all configurable settings from fiona-settings.json to the user
  • Allow user to enable/disable boolean settings by checking or unchecking
  • Allow user to add custom values for string/integer settings where applicable
  • Provide a complete path where user can press Enter through all prompts to accept all defaults without modification
  • Display current values for each setting before prompting
  • Support non-interactive mode via flags (e.g., --yes, --default) for AI agents to run deterministically
  • Validate all inputs before saving
  • Write validated settings to fiona-settings.json in the wiki root
  • Handle missing or corrupted settings files gracefully

Acceptance criteria:

  • Running fiona-assistant setup with no arguments starts the interactive flow
  • User can navigate through all settings with Enter to accept defaults
  • User can toggle boolean settings (check/uncheck)
  • User can input custom values for string/integer settings
  • All inputs are validated before saving to settings file
  • Non-interactive mode applies all defaults without prompts
  • Exit code 0 on successful completion, non-zero on validation error or failure
  • Running fiona-assistant setup in a directory without fiona-settings.json creates one with defaults

2.10.2 Contrast with fiona-assistant init

Status: Planned

Clarify the difference between init and setup commands.

Requirements:

  • fiona-assistant init [directory]: Initializes an llm-wiki directory with default settings applied automatically without user interaction (see 1.1.1)
  • fiona-assistant setup: Runs interactive review of all possible settings, allowing user to customize each setting before applying
  • init is designed for quick bootstrap with sensible defaults
  • setup is designed for users who want to review and customize settings before initialization or update existing settings
  • init creates the wiki structure; setup configures settings in an existing wiki
  • Both commands respect the wiki root discovery mechanism (2.8.1)

Acceptance criteria:

  • Documentation clearly distinguishes the two commands and their use cases
  • init remains non-interactive and applies all defaults automatically
  • setup provides full interactive review of all configurable settings
  • setup can be run on an existing wiki to modify settings

Project Infrastructure

3.1 Logging Library

Status: Partially Implemented

Replace print-based output with a logging library across the codebase.

Progress note: run_sanity.py and run_tests.py log diagnostics via the standard logging module, with levels controlled by LOG_LEVEL (see 2.6.1); CLI-facing reports intentionally remain stdout prints.

Requirements:

  • Standard logging module (or agreed equivalent); no new hard dependency.
  • CLI-facing output stays stdout; diagnostics go to stderr with levels.
  • Existing AI-friendly output format is preserved for consumers.

Acceptance criteria:

  • No direct print calls in src/ production modules.
  • Tool output consumed by tests/scripts is unchanged.

3.2 Documentation (medium priority)

Status: Partially Implemented

Progress note: src/README.md, src/librarian/README.md, and src/mdoctor/README.md exist with a project description, pip install -e . setup instructions, and basic usage examples; all three are stale relative to the current CLIs.

Remaining work:

  • Document the actual subcommands in librarian/README.md (list, toc) and mdoctor/README.md (list, chklint, fix) — both READMEs predate those subcommands.
  • Refresh the src/README.md project structure (omits wiki/, python_ruff/, run_tests.py, run_sanity.py, settings_dev.json).
  • Link SPEC.md from README.md related documentation.

Acceptance criteria:

  • A new contributor can install, run, and use each tool using only READMEs.
  • All markdown documentation passes mdoctor chklint.

3.3 Project Clarification (low priority)

Status: Planned

Define the role of each src/ tool in the wiki workflow.

Requirements:

  • Document the purpose of every tool under src/.
  • Classify tools by role:
    • Ingestion: moving files from ingest/ to raw/.
    • Processing: converting raw/ to wiki/concepts/.
    • Maintenance: updating index.md / log.md.
  • Where gaps exist, add utility scripts to llm-wiki utils/ (e.g. ingest.py, process.py).

Acceptance criteria:

  • The classification table exists in this spec or the README and every src/ tool has exactly one assigned role.

Non-Goals

  • No LLM/API integration: Fiona-Assistant is deterministic tooling only.
  • No modification of personal/ or raw/ content by any automated tool.
  • No cloud sync or remote backup; version control is local-first.

Priority Order

Priority Feature Section
P1 wiki update / wiki check-update 1.1.2
P1 Git wrapper (save/snapshot/restore/clean/undo) 1.2
P1 wiki sanity incl. dead-link check 1.1.3
P2 Frontmatter linter (fmlint) 2.1.3
P2 Shellcheck library 2.3
P2 MD code block linting 2.4
P2 JSON linter (json-lint) 2.9
P2 Logging library 3.1
P3 Frontmatter tags (date, confidence, contested) 2.7.1
P3 Backup script 1.2.1
P3 Documentation 3.2
P4 Non-MD file tracking (py/bash) 2.5.1
P4 Project clarification 3.3
P2 MDoctor auto-fix (mdoctor fix) 2.1.1
P2 Lint configuration (fiona-settings.json) 2.1.2
P2 Sanity runner failure reporting 2.6.1
P2 Wiki root discovery via fiona-settings.json 2.8.1
P2 Settings manager (fiona-assistant setup) 2.10

Open Questions

  • Tagging format for python files and bash scripts (2.5.1) is undecided.
  • Git wrapper location and naming (src/vcs/ vs src/librarian/vcs.py).
  • Wiki root discovery (2.8.1): 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?
    • the one nearest wins, or throw an error if the subdir is same level