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
- Current Capabilities
- Feature Specifications
- 2.1 llm-wiki Lifecycle Management
- 2.2 Git Version Control for llm-wiki
- 2.3 Shellcheck Library
- 2.4 MD Code Block Linting
- 2.5 MD Frontmatter Tagging
- 2.6 Librarian: Non-MD File Support
- 2.7 Logging Library
- 2.8 Documentation (medium priority)
- 2.9 Project Clarification (low priority)
- 2.10 MDoctor Auto-Fix (
mdoctor fix) - 2.11 Lint Configuration (
fiona-settings.json)
- Non-Goals
- Priority Order
- Open Questions
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.pygreen). python src/run_sanity.pymust pass before any change is finalized.- Python code passes Ruff; markdown passes PyMarkdown lint.
- Directory permissions are enforced:
personal/andraw/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
versionandcreated/updateddates.
Acceptance criteria:
- Running
wiki initon an empty directory produces a valid llm-wiki tree that passeswiki sanity(once 2.1.3 ships; passesmdoctor chklinttoday). - 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
versionfrontmatter 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 initoutput,wiki updateis 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:
saveon a dirty tree produces a commit with the specified message format.undoon a dirty tree fails with a clear error message mentioningclean.snapshotthenrestore <tag_name>returns file contents to the tagged state.cleanleavesgit statusempty.
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
shellcheckfollowing the same pattern aspython_ruff(external linter, AI-friendly aggregated violation report). - Graceful error when
shellcheckis 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_frontmattermodule. - New tags follow the frontmatter schema in
AGENTS.mdRule 8. wiki sanitywarns on files missing required tags.
Acceptance criteria:
- A concept note missing
confidenceis flagged bywiki 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
loggingmodule (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
printcalls insrc/production modules. - Tool output consumed by tests/scripts is unchanged.
2.8 Documentation (medium priority)
Status: Planned
- Write
src/README.mdwith project description. - Setup instructions (
pip install -e .). - Usage examples for librarian and mdoctor.
- Update
librarian/README.mdwith actual usage info. - Add
mdoctor/README.md. - Link
SPEC.mdfromREADME.mdrelated 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/toraw/. - Processing: converting
raw/towiki/concepts/. - Maintenance: updating
index.md/log.md.
- Ingestion: moving files from
- 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]andmdoctor 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 fixon 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.pymarkdownsection 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 viasettings_file=), sorun_sanity.pyandmdoctor fixapply 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_lengthreports no violation.
Non-Goals
- No LLM/API integration: Fiona-Assistant is deterministic tooling only.
- No modification of
personal/orraw/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/vssrc/librarian/vcs.py). - Whether
wiki updateshould support a--forceflag or interactive confirmation for locally-modified core files.