Files
fiona-assistant/SPEC.md
T
2026-09-23 22:01:00 +02:00

14 KiB

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

Fiona-Assistant Specification

Spec sheet for the Fiona-Assistant toolkit. Derived from todo.md and 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.


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

Feature Specifications

2.1 llm-wiki Lifecycle Management

Status: Partially Implemented

Covers: fiona-assistant wiki init (exists), wiki update, wiki sanity.

2.1.1 wiki init

Status: Partially Implemented

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

Requirements:

  • If target directory already contains an llm-wiki structure, refuse or warn rather than silently overwriting.
  • Copied files carry frontmatter with version and created/updated dates.

Acceptance criteria:

  • Running wiki init on an empty directory produces a valid llm-wiki tree that passes wiki sanity (once 2.1.3 ships; passes mdoctor chklint today).
  • Idempotence: re-running on an initialized directory does not clobber user content.

2.1.2 wiki update

Status: Planned

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

Requirements:

  • Compare version frontmatter of each core md file/script against the packaged template; update only files whose template version is newer.
  • 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) without an explicit flag; report skipped files instead.
  • Respect read-only zones (personal/, raw/).

Acceptance criteria:

  • On a pristine wiki init output, wiki update is a no-op or reports "already up to date".
  • On a wiki with outdated core files, only those files are updated and the report lists each updated file with old and new version.

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

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

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

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 (2.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 (2.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 MD Frontmatter Tagging

Status: Partially Implemented

Tag md files with metadata used for version control and quality signals.

Tag Status Purpose
version Implemented Source control and wiki update change detection
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 existing md_frontmatter module.
  • 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.6 Librarian: 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.7 Logging Library

Status: Planned

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

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.

2.8 Documentation (medium priority)

Status: Planned

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

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

2.10 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.11 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)
    • <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)
  • 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.

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.

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 2.1.2
P1 Git wrapper (save/snapshot/restore/clean/undo) 2.2
P1 wiki sanity incl. dead-link check 2.1.3
P2 Shellcheck library 2.3
P2 MD code block linting 2.4
P2 Logging library 2.7
P3 Frontmatter tags (date, confidence, contested) 2.5
P3 Backup script 2.2.1
P3 Documentation 2.8
P4 Non-MD file tracking (py/bash) 2.6
P4 Project clarification 2.9
P2 MDoctor auto-fix (mdoctor fix) 2.10
P2 Lint configuration (fiona-settings.json) 2.11

Open Questions

  • Tagging format for python files and bash scripts (2.6) is undecided.
  • Git wrapper location and naming (src/vcs/ vs src/librarian/vcs.py).
  • Whether wiki update should support a --force flag or interactive confirmation for locally-modified core files.