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
- Current Capabilities
- llm-wiki Specifications
- Fiona Tools Specifications
- 2.1 mdoctor (Markdown Lint)
- 2.2 python-ruff (Python Lint)
- 2.3 Shellcheck Library
- 2.4 MD Code Block Linting
- 2.5 librarian (Content Management)
- 2.6 Test and Sanity Runners
- 2.7 toc-generator (Table of Contents)
- 2.8 fiona (CLI Entry Point)
- 2.9 json-lint (JSON Linter)
- 2.10 settings_manager (Settings Management)
- Project Infrastructure
- 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). - 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.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
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 atable_of_contents.mdper 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 withFileExistsErrorif an llm-wiki structure already exists.check-update [directory]: Check for updates to llm-wiki core files against the packaged template version. Supports--jsonflag 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: thefiona-settings.jsonfile receives special handling to preserve user customizations when updating.
Notes:
- Invalid directories exit 1 with an error message on stderr.
chklintcommands print violations in their report but exit 0; the violation count lives in the output, not the exit code.- The standalone console scripts
librarianandmdoctorbehave likefiona-assistant librarian listand thefiona-assistant mdoctorsubcommands respectively. librarian tocaccepts--recursive-toc,--non-recursive, and repeatable--exclude REGEXflags (see 2.7). Depth limits come from themarkdown.toc_generatorsection of the packagedfiona-settings.json(max_depth_from_file,max_depth_from_dir; absent or0= 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.pyand thefiona-assistant wiki initsubcommand (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
FileExistsErrornaming the conflicting indicator files (AGENTS.md,fiona-settings.json,wiki/,ingest/,README.md). - Copied files carry frontmatter with
versionandcreated/updateddates. - The template copy skips Python files and
__pycache__artifacts so only content ships to user wikis.
Acceptance criteria:
- Running
wiki initon an empty directory produces a valid llm-wiki tree that passesmdoctor chklint(andwiki sanityonce 1.1.3 ships). - Re-running on an initialized directory fails with
FileExistsErrorand 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
versionfrontmatter 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.
--forceor--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-updatecommand: check and report what files need updating without modifying anything. Supports--jsonflag for AI-friendly output format.wiki updatecommand: perform the actual updates. Supports--dry-runflag to preview changes without applying them, and--jsonflag for AI-friendly output format.
Acceptance criteria:
- On a pristine
wiki initoutput,wiki check-updatereports "already up to date" andwiki updateis a no-op. - On a wiki with outdated core files,
wiki check-updateidentifies all files that need updates andwiki updateupdates only those files. - Settings files are updated with user customizations preserved.
- Files in read-only zones are never modified.
- Running with
--forceor--yesskips interactive confirmation. - Running with
--dry-runshows 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:
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.
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 providesmdoctor 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]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.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.pymarkdownsection 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.pyrelies 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-tablesextension is enabled, and enabling it is blocked. pymarkdownlnt 0.9.40 (latest at the time of writing) crashes withBadTokenizationErroron list lines that contain pipes (e.g. generatedtable_of_contents.mdentries for headers like## [date] create | subject), which breaksrun_sanity.pyon 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 inrun_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 viasettings_file=), sorun_sanity.pyandmdoctor fixapply 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):
-
Look up the pymarkdown rule id and its property names in the pymarkdown rule documentation (e.g.
md013ownsline_length). -
Add a property map under
markdown.pymarkdown, keyed by the rule id — the existingmd013entry shows the shape:"md013": { "line_length": 100, "code_blocks": false, "tables": false } -
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. -
To toggle an entire rule, set
"enabled": falseinside its map (seemd060above). -
To enable a parser extension, append its identifier to
extensions(front-mattertoday; formarkdown-tablesread the known limitation above first). -
Verify with
python src/run_sanity.py; the new configuration applies at the next scan. -
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_lengthreports no violation. - A table with a structural defect (e.g. missing blank line before it)
is reported by
run_sanity.py— blocked until the pymarkdownmarkdown-tablescrash 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 requirednameandversionfields 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
.mdfiles in a directory tree for frontmatter presence. - Validate that required fields are present:
nameandversion(minimum for source control per AGENTS.md Rule 8). - Support configurable required fields via
fiona-settings.jsonfor different file types (e.g.,type: tocfiles 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), so1:1prefix is redundant. - Handle files without frontmatter (report as missing all required fields).
- Handle files with malformed YAML frontmatter (report as parse error).
- Respect
.gitignoreand read-only zones (personal/,raw/).
Acceptance criteria:
- A md file missing
namefield is reported with file path and missing field. - A md file missing
versionfield 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) andrun_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 fmlintwith no subcommand defaults tochklint ..- 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 fmlinton 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_fieldsinfiona-settings.json(default:['name', 'version']). - Support per-type requirements:
markdown.frontmatter.type_requirementsmaps 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.jsonchanges validation behavior on the next run. - Disabling the linter via settings skips frontmatter validation.
- Rules listed in
ignore_rulesare not reported as violations. - Files matching patterns in
ignore_fileare 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 thenamefield 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.mdin folderpython-tdd/must havename: python-tdd). - SKILL.md files must have a
descriptionfield in frontmatter. - Report violations with rule code
FML005for invalid characters,FML006for folder name mismatch, andFML004for missing description.
Acceptance criteria:
- A
SKILL.mdfile withname: Python TDDis reported withFML005violation. - A
SKILL.mdfile in folderpython-tdd/withname: python-tddpasses validation. - A
SKILL.mdfile in folderpython-tdd/withname: other-nameis reported withFML006violation. - A
SKILL.mdfile with valid lowercase name matching folder passes validation. - A
SKILL.mdfile without adescriptionfield is reported withFML004violation.
2.2 python-ruff (Python Lint)
Status: Implemented
Covers:
src/python_ruff/. Wraps the externalrufflinter 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--fixthrough 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
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(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) andsrc/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.pylists per-file pass/fail counts with each failing test nested under its file entry asClass : test_name, followed by the assert explanation (or the raw exception message when no assert line exists). - The
Sanity Failedverdict lists only the failing test names; the assert details live in the report body, not the verdict. run_tests.pyruns 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_LEVELenvironment 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=DEBUGshows 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.pyloadspytests.required-coveragefromsrc/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>%)); underSanity 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-coverageinsettings_dev.jsonchanges the verdict with no code changes.
2.7 toc-generator (Table of Contents)
Status: Implemented
Covers:
src/librarian/toc_generator.py. Generates atable_of_contents.mdper folder, listing every md file with its frontmatter version and its headers as anchored links.
Requirements:
- Each covered folder gets a
table_of_contents.mdwith YAML frontmatter (title,created,updated,type: toc). - Entries list folders, file links, and the file's frontmatter
version(shown asv<version>;v0.0.0when 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-tocwrites a TOC in every subfolder. --non-recursivelimits 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_generatorsection offiona-settings.json(loaded from the packaged llm-wiki template, see 2.1.2):max_depth_from_filecaps the header level listed per file (e.g.3lists h1 through h3; deeper headers are omitted)max_depth_from_dircaps how deep a TOC recurses into subfolders (e.g.1lists files in the folder and its direct subfolders)- An absent key or
0means 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-recursivestill forces direct files only regardless ofmax_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 or0, every header level is listed. - With
max_depth_from_dir: 1, md files two subfolder levels deep are not listed; with the key absent or0, 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_frontmattermodule (see 2.5). - 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.8 fiona (CLI Entry Point)
Status: Implemented
Covers:
src/fiona/__main__.py. Thefiona-assistantconsole script dispatches to the tool modules so every tool is reachable through one command. Each tool also keeps its standalone CLI;librarianandmdoctorare installed as console scripts, whilepython-ruffis available only throughfiona-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.argvand 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-assistantis invoked, locate the nearestfiona-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.jsonis 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 mdoctorfrom inside a wiki subdirectory lints the wiki root, not the subdirectory. - Running
fiona-assistant librarianinside a wiki lists the wiki root's files. - With no
fiona-settings.jsonin 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 (jsonmodule for parsing, potentiallyjson5or 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
jsonmodule 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
.jsonextension by default; support configurable extensions via settings. - Respect
.gitignoreand 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
jsonsection offiona-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
jsonsection in settings uses sensible defaults.
Acceptance criteria:
- A JSON file with tab indentation when
indent: "space"andindent_len: 2is configured reports a style violation. - A JSON file with 4-space indentation when
indent_len: 2is 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-lintwith no subcommand defaults tochklint ..- 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
--fixflag to auto-fix certain violations (indentation, trailing commas) in place.
Acceptance criteria:
- Running
fiona-assistant json-linton a directory with invalid JSON produces a structured violation report. - Running on a clean directory reports no violations.
- Running with
--fixon 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.pyrunsjson-lint chklinton the codebase.wiki sanity(1.1.3) runsjson-lint chklinton the wiki directory.- JSON lint violations are reported in the aggregated sanity output.
Acceptance criteria:
- A JSON file with violations causes
run_sanity.pyto report JSON lint failures. wiki sanityreports 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.jsonto 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.jsonin the wiki root - Handle missing or corrupted settings files gracefully
Acceptance criteria:
- Running
fiona-assistant setupwith 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 setupin a directory withoutfiona-settings.jsoncreates 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 applyinginitis designed for quick bootstrap with sensible defaultssetupis designed for users who want to review and customize settings before initialization or update existing settingsinitcreates the wiki structure;setupconfigures 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
initremains non-interactive and applies all defaults automaticallysetupprovides full interactive review of all configurable settingssetupcan 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
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.
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) andmdoctor/README.md(list,chklint,fix) — both READMEs predate those subcommands. - Refresh the
src/README.mdproject structure (omitswiki/,python_ruff/,run_tests.py,run_sanity.py,settings_dev.json). - 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.
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/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.
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 / 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/vssrc/librarian/vcs.py). - Wiki root discovery (2.8.1): which
fiona-settings.jsonwins 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