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

67 KiB

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

Fiona-Assistant Specification

This document is the build contract for Fiona-Assistant. A reader with this file, and no source tree, must be able to produce the same observable software. Status values are Implemented, Partially Implemented, Planned, and Won't Do.

Revision 0.40.0 reorganizes the sheet into contracts. Revision 0.40.1 numbers nested requirements such as 7.16.1.1. Revision 0.40.4 adds the PYC001 exception in 6.4.2.. Revision 0.41.0 installs one fiona package and keeps tests and repo scripts outside it.

Each feature section starts with a Status line. Requirements use - *N.M.K.*. Each *acceptance* sits under the requirement it tests. NOT_IMPLEMENTED marks work that is specified and not built yet. Class names, file paths, and history live in Appendix A.


1. Product Overview

Fiona-Assistant is a CLI toolkit that manages, organizes, and checks LLM wiki content with deterministic scripts. Reserve LLM tokens for creative and analytical work.

1.1. Document Conventions

Status: Implemented

  • 1.1.1. Main sections use ## N. Title. Subsections use ### N.M. Title. Deeper headings use #### N.M.K. Title.
    • acceptance: Every heading follows that numbering.
  • 1.1.2. A requirement is - *N.M.K.* <text>. A group is numbered the same way, and each item under it adds one segment, for example *7.16.1.* then *7.16.1.1.*. Its acceptance is the next nested - *acceptance*: <text>, and that acceptance describes this requirement only.
    • acceptance: No acceptance describes a neighboring requirement.
    • acceptance: The shared-engine bullets in section 7.16 are numbered 7.16.1 and 7.16.1.1, not plain dashes.
  • 1.1.3. Unbuilt requirements start with `NOT_IMPLEMENTED`.
    • acceptance: Every planned item carries that tag.
  • 1.1.4. The block between <!-- toc-start: headings 2..6 --> and <!-- toc-end --> is generated by librarian toc file. Leave that block to the generator.

1.2. Constraints

These apply to every feature.

  • 1.2.1. Tool reports are parseable and use the shared shapes in sections 4, 6, and 7.
    • acceptance: Two linters that find violations print the same section order from section 6.1.
  • 1.2.2. A command that needs a human decision prompts on a TTY. The same command accepts an explicit flag (--force, --yes, or --non-interactive) and then runs without a prompt.
    • acceptance: wiki update on a non-TTY declines unless --force or --yes is set.
  • 1.2.3. personal/ and raw/ are read-only for every automated tool. Tools may resolve links that point into those zones.
    • acceptance: wiki update leaves every file under personal/ and raw/ byte-for-byte unchanged.
  • 1.2.4. Code changes follow test-first development. python scripts/run_tests.py is green, then python scripts/run_sanity.py is green, before a change is finished.
    • acceptance: A sanity run below the coverage gate in section 5.2 fails even when every test passes.
  • 1.2.5. Python passes Ruff. Markdown passes PyMarkdown with the rules in section 5.1.
    • acceptance: An unused import is reported by python-ruff chklint with file, line, column, and rule code.

2. Package and Runtime

Status: Implemented

Python >= 3.11 (also 3.12 and 3.13). Install with pip install -e . from the repository root. The build requires setuptools 61 or newer. Runtime dependencies:

Package Minimum
pymarkdownlnt 0.9.0
ruff 0.16.8
pyyaml 6.0.3
GitPython 3.1.0

Development extras: pytest>=7.0, pytest-cov>=4.0, pytest-mock, pylint. html5validator is not a dependency until section 7.17 is implemented.

One importable package, fiona, lives under src/fiona/. Its subpackages are librarian, mdoctor, customlinter, python_ruff, gittool, sanity_runner, and wiki. The wiki template is package data at src/fiona/data/llm_wiki/ and is loaded with importlib.resources. It is not an importable module. Tests live in repo-root tests/ and are not installed. scripts/ holds settings_dev.json, shell helpers, and the launchers scripts/run_tests.py and scripts/run_sanity.py.

Console scripts:

Script Entry
fiona-assistant fiona.__main__:main
librarian fiona.librarian.librarian:main
mdoctor fiona.mdoctor.mdoctor:main

python-ruff, fmlint, json-lint, and git are reached only through fiona-assistant. html-js-lint is not installed until section 7.17 is implemented.

Coverage measures src/fiona, omitting tests. The config lives in pyproject.toml. The gate percentage is section 5.2.

Logging: every CLI entry calls setup_logging() before work. Level order is LOG_LEVEL environment variable, then fiona.log_level in fiona-settings.json, then WARNING. Records go to stderr. When fiona.file_log_location is set, a file handler writes lines %(asctime)s %(levelname)s %(name)s: %(message)s at or above fiona.file_log_level (fallback: fiona.log_level). A relative path is resolved from the current working directory. An unopenable path logs a warning and keeps stderr logging. Human reports stay on stdout. Package loggers set their level explicitly because pymarkdown resets the root logger mid-run.

  • 2.1. The three console scripts above are installed by pip install -e ..
    • acceptance: fiona-assistant with no arguments prints help and exits 0.
  • 2.2. html-js-lint is not an installed script until section 7.17 exists.
    • acceptance: A fresh install does not fail at import because of a missing html_js_lint package.

3. llm-wiki Template

Status: Implemented

wiki init copies this tree from the packaged template. Text files replace every DATE_PLACEHOLDER with the current UTC date YYYY-MM-DD. Binary files are copied unchanged. A glob in fiona.llm-wiki.ignore_files skips that file, or that directory and its subtree. A missing settings file or a missing key copies everything. A non-list ignore_files value raises ValueError with the text fiona.llm-wiki.ignore_files must be a list of strings.

AGENTS.md
README.md
fiona-settings.json
table_of_contents.md
ingest/README.md
personal/README.md
raw/README.md
wiki/schema.md
wiki/index.md
wiki/log.md
utils/README.md
utils/scripts/example.py
utils/scripts/map.md
utils/skills/README.md
utils/skills/fiona/SKILL.md
utils/skills/fiona/markdown_rules.md
utils/skills/fiona/llm-wiki-mod.md
utils/skills/obsidian/SKILL.md
utils/skills/python-tdd/SKILL.md
utils/personas/default/SOUL.md
utils/personas/template/SOUL.md
utils/skills_local/README.md

The shipped fiona-settings.json is the default document in section 5.1. wiki/schema.md is the page-type and tag taxonomy. This spec's frontmatter table in section 6.2 is the field contract; where the two disagree, this spec wins.

3.1. What Counts as a Wiki

A directory is an llm-wiki when it contains fiona-settings.json. wiki init refuses when any of these already exist: AGENTS.md, fiona-settings.json, wiki/, ingest/, README.md.

3.2. Core Files and Read-only Zones

Core files, matched by name at the wiki root:

  • AGENTS.md
  • fiona-settings.json
  • README.md
  • table_of_contents.md

Core directories (every file under them is core):

  • wiki/
  • ingest/
  • personal/
  • raw/
  • utils/

Read-only zones, including the zone directory itself:

  • personal/
  • raw/

wiki update adds missing core files and directories. It never deletes user files. It never writes inside a read-only zone, so a missing file under personal/ or raw/ is not added back.

After the copy, wiki init creates a git repository, writes .gitignore containing a comment line and personal/, stages everything, and commits Initial llm-wiki commit. If git init fails, the copy still counts as success and stdout adds Note: Git repository initialization failed: <error>.

  • 3.2.1. An empty directory becomes the tree above, with dates substituted, and a git commit that does not track personal/.
    • acceptance: personal/ is absent from git ls-files after wiki init.
  • 3.2.2. A second wiki init raises FileExistsError whose message names each conflicting indicator, and writes nothing.
    • acceptance: An existing README.md alone is enough to refuse, and that file's bytes are unchanged.

4. Command Catalog

Status: Implemented

One command tree. Optional [directory] defaults to . today. Wiki-root discovery (section 7.23) is not built. An invalid directory prints Error: '<path>' is not a valid directory. on stderr and exits 1, unless a command below states a different message.

fiona-assistant with no command prints help and exits 0. fiona-assistant git with no subcommand prints git help and exits 1. fiona-assistant wiki with no subcommand prints wiki help and exits 1.

4.1. librarian

fiona-assistant librarian and librarian with no subcommand list the current directory.

list [directory] stdout:

Found <N> files in '<directory>':
  - <path>

mdoctor list uses the same listing with the prefix MDoctor: Found <N> files in '<directory>':.

4.2. librarian toc

toc [directory] [flags] writes table_of_contents.md in the target folder. Flags: --recursive-toc, --non-recursive, and repeatable --exclude REGEX. Depth comes from section 5.1.

A path that is a file or missing exits 1 on stderr and names librarian toc file <path>. A folder with no markdown prints no markdown files found on stdout and writes nothing. In --recursive-toc mode that message is a log line at INFO instead.

toc file <path> writes an in-file TOC in that markdown file. toc file * does that for every markdown file under the wiki root found by section 7.15. --sectionized forces section numbering for that run. Status lines:

wrote toc in <path>
toc already up to date in <path>
skipped <path> (<reason>)
generated toc for <N> file(s), skipped <M>

The summary line is bulk mode only. A file with no H1 is skipped <path> (no H1 heading) and is not rewritten.

4.3. mdoctor

No subcommand means chklint ..

chklint [directory] prints the shared report (section 6.1) with header PyMarkdownlint Violations and exits 0 even when violations exist.

fix [directory] runs pymarkdown auto-fix in place. Stdout:

PyMarkdownFix: <N> file(s) fixed
  - <path>

A pymarkdown API failure prints Error: pymarkdown fix failed: <error> on stderr and exits 1. The command does not skip personal/ or raw/.

4.4. fmlint

fiona-assistant fmlint with no subcommand means chklint .. chklint [directory] prints the shared report with header Frontmatter Lint Violations and exits 0 even when violations exist. A missing directory exits 1.

4.5. python-ruff

No subcommand means chklint .. The report header is Ruff Violations. Exit code is 0 when the ruff process itself succeeds, including when violations are listed. lint(path, fix=True) passes --fix to the ruff binary. There is no fix subcommand yet.

4.6. json-lint

No subcommand means chklint .. Header is JSONLint Violations.

chklint [directory] exits 1 when the report contains violations and exits 0 when it reports no violations. This differs from mdoctor, fmlint, and python-ruff, which exit 0 either way.

chklint --fix and fix [directory] rewrite indentation and trailing commas in place, skip personal/ and raw/, and print:

JSONLintFix: <N> file(s) fixed
  - <path>

A missing directory on fix prints Error: '<path>' does not exist. on stderr and exits 1.

4.7. git

Operates on the git repository at the current directory. Timestamps are UTC.

Command Stdout on success
save --description TEXT Committed: <full sha>
snapshot <tag_name> --description TEXT Snapshot created: commit=<sha>, tag=<tag>
restore <tag_name> Restored to: <sha>
clean Working tree cleaned. All changes discarded.
undo Undo to: <sha>
status Status: clean or Status: dirty, then git status

On failure the tool prints Error: <message> and exits 1.

Commit message: <YYYY-MM-DD HH:MM:SS> <description>. save runs git add --all and commits. A clean tree, including no untracked files, raises Working tree is clean. Nothing to commit.

snapshot commits, then creates an annotated tag <YYYY-MM-DD_HH-MM-SS>_<tag_name> with message Snapshot: <description>.

restore requires a clean tree (Working tree is dirty. Use 'clean' to discard current edits first.). It accepts the full tag or the user tag suffix. The latest tag whose name equals the argument or ends with _<argument> wins. It checks that commit's tree into the index and working tree and adds a new commit <timestamp> Restore to <full tag>. History before that commit stays.

clean requires a dirty tree (Working tree is already clean. Nothing to discard.), then git reset --hard HEAD and git clean -fd.

undo requires a clean tree and at least two commits (Cannot undo: only one commit exists in the repository.), then git reset --hard HEAD~1.

4.8. wiki init

fiona-assistant wiki init [directory]. Success stdout:

Successfully initialized llm-wiki directory at: <resolved path>

Rules are section 3.

4.9. wiki check-update

fiona-assistant wiki check-update [directory] [--json]. The directory must contain fiona-settings.json, else stderr Error: Directory '<path>' is not an llm-wiki directory and exit 1. A missing directory is Error: Directory not found: <path> and exit 1. A successful check exits 0 whether or not updates exist.

Human stdout when current:

Wiki is up to date.

When something differs, the lines that apply:

Files to update: <N>
  - <relative path> (<current> -> <template>)
Directories to add: <N>
  - <relative path>
Files to add: <N>
  - <relative path>

Total: <N> file(s) need attention
Files skipped (locally modified): <N>
  - <relative path>

The version parenthesis appears only when both versions exist. --json prints one JSON object:

{
  "files_to_update": [
    {
      "path": "<path>",
      "current_version": "<version or null>",
      "template_version": "<version or null>",
      "is_settings_file": false
    }
  ],
  "files_to_add": [],
  "directories_to_add": [],
  "files_skipped": [
    {"path": "<path>", "reason": "locally modified"}
  ],
  "total": 0,
  "has_updates": false
}

4.10. wiki update

fiona-assistant wiki update [directory] [-f|--force] [-y|--yes] [--dry-run] [--json].

Without --force and --yes, stdout shows the check-update text and the prompt Proceed with update? [y/N] followed by a space. y and yes proceed. Any other answer, and a non-TTY, exit 1 with stderr Error: Update requires confirmation. Use --force or --yes to proceed without prompting.

--dry-run prints Dry run - no files will be modified: and the check-update text, writes nothing, and exits 0.

Success stdout:

Update complete: <U> file(s) updated, <A> added, <S> skipped.

--json suppresses the plan and prints:

{
  "files_updated": [],
  "files_added": [],
  "directories_added": [],
  "files_skipped": [],
  "total": 0
}

Comparison and merge rules are section 7.2.

4.11. wiki sanity

fiona-assistant wiki sanity [directory] [--json] [--non-interactive]. Requires fiona-settings.json. Exit 0 when every check is clean, exit 1 otherwise.

Checks, in this order, one thread each: markdownlint, frontmatter_lint, python-ruff, mdlinter, jsonlint.

Human report:

Wiki Sanity Report
TARGET: <path>

<failing check reports, omitted when clean>

Results:
<name padded>: PASS - <N> violations (MM:SS)

SANITY PASSED (MM:SS)

A failure ends with Sanity Failed - <N> checks need attention: and one detail line per failing check. The pass banner carries the total wall time. The failure verdict does not. Per-check times may overlap and need not sum to the total. Rows stay in registry order.

--json skips the progress display and prints:

{
  "target": "<path>",
  "checks": {
    "markdownlint": {
      "result": 0,
      "violation_count": 0,
      "duration_seconds": 0.0,
      "violations": []
    }
  },
  "total_violations": 0,
  "passed": true
}

result is 0 for pass and 1 for fail. Progress display is section 7.16.

4.12. wiki graph

fiona-assistant wiki graph [directory] [-o FILE] [--format html|json] [--include-pattern GLOB] [--exclude-pattern GLOB] [--wikilinks|--no-wikilinks] [--json] [--external-links|--no-external-links].

Defaults: output wiki_graph.html in the current directory, format html, include **/*.md, wikilinks on, external-link nodes off. --json selects JSON format. Behavior is section 7.4.

4.13. Repository runners

python scripts/run_tests.py runs pytest with --color=no and a temporary JUnit XML report (junit_family=xunit1).

python scripts/run_sanity.py [--non-interactive] runs, in order: pytests, markdownlint, ruff, frontmatter_lint, pycustomlint, jsonlint. Same progress display, result table, and verdict shape as wiki sanity, with label Running Sanity and an extra untimed coverage: row under pytests. Details are section 7.16.


5. Settings Schema

Two files. fiona-settings.json ships in the template and marks a wiki root. scripts/settings_dev.json is repository tooling only and is not copied into a wiki.

5.1. fiona-settings.json

Absent file: pymarkdown uses its own defaults; other tools use the defaults in the table. A typo in a pymarkdown rule id or property name is accepted and has no effect. Confirm a new pymarkdown setting by its effect on a scan. TOC file settings reject unknown keys and bad types with exit 1 and the key name.

Shipped document (logical content; wiki init copies the file):

{
  "markdown": {
    "pymarkdown": {
      "extensions": ["front-matter"],
      "respect_gitignore": true,
      "md025": {"front_matter_title": "no-match"},
      "md013": {"line_length": 100, "code_blocks": false, "tables": false},
      "md060": {"enabled": false}
    },
    "frontmatter": {
      "ignore_rules": [],
      "ignore_file": [],
      "respect_gitignore": true
    },
    "toc_generator": {
      "max_depth_from_file": 3,
      "max_depth_from_dir": null,
      "file": {
        "min_heading": 2,
        "max_heading": 6,
        "sectionize": false,
        "ignore_files": [],
        "*/rules.md": {"max_heading": 2}
      }
    }
  },
  "json": {
    "indent": "space",
    "indent_len": 2,
    "trailing_commas": false,
    "require_key_order": false,
    "check_duplicate_keys": true,
    "extensions": [".json"]
  },
  "python": {"ruff": {}},
  "fiona": {
    "log_level": "INFO",
    "file_log_level": "INFO",
    "file_log_location": "fiona.log",
    "llm-wiki": {"ignore_files": []},
    "wiki": {
      "graph": {
        "node_colors": {"low": "#808080", "mid": "#ffa500", "high": "#FF0000"},
        "node_radius": {"min": 5, "max": 40},
        "hover": {
          "color": "#add8e6",
          "edge_color": "#0000ff",
          "size_multiplier": 1.3
        }
      }
    }
  }
}
Key Type Default when absent Consumer
markdown.pymarkdown.extensions list of strings none enabled mdoctor
markdown.pymarkdown.respect_gitignore bool false mdoctor
markdown.pymarkdown.<rule>.<prop> bool, int, or str pymarkdown default mdoctor
markdown.frontmatter.required_fields list of strings ["name", "version"] fmlint
markdown.frontmatter.type_requirements object of lists {} fmlint
markdown.frontmatter.enabled bool true fmlint
markdown.frontmatter.ignore_rules list of codes [] fmlint
markdown.frontmatter.ignore_file list of globs [] fmlint
markdown.frontmatter.respect_gitignore bool true fmlint
markdown.toc_generator.max_depth_from_file int unlimited (0 or absent) folder TOC
markdown.toc_generator.max_depth_from_dir int or null unlimited folder TOC
markdown.toc_generator.file.min_heading int >= 2 2 in-file TOC
markdown.toc_generator.file.max_heading int >= min 6 in-file TOC
markdown.toc_generator.file.sectionize bool false in-file TOC
markdown.toc_generator.file.ignore_files list of globs [] in-file TOC
markdown.toc_generator.file.<glob> object of file keys none per-file override
json.indent "space" or "tab" "space" json-lint
json.indent_len int 2 json-lint
json.trailing_commas bool false json-lint
json.require_key_order bool false json-lint
json.check_duplicate_keys bool true json-lint
json.extensions list of strings [".json"] json-lint
json.max_line_length int or absent no line-length check json-lint
python.ruff object {} reserved, unused
fiona.log_level level name WARNING logging
fiona.file_log_level level name fiona.log_level file log
fiona.file_log_location string or absent no file log file log
fiona.llm-wiki.ignore_files list of globs copy all wiki init, update
fiona.wiki.graph.wikilinks_enabled bool true wiki graph
fiona.wiki.graph.max_files int 5000 wiki graph
fiona.wiki.graph.node_colors.low/mid/high hex color #808080 / #ffa500 / #ff0000 wiki graph
fiona.wiki.graph.node_radius.min/max number 5 / 25 wiki graph
fiona.wiki.graph.hover.color hex color #add8e6 wiki graph
fiona.wiki.graph.hover.edge_color hex color #0000ff wiki graph
fiona.wiki.graph.hover.size_multiplier number 1.3 wiki graph

Bool pymarkdown properties use set_boolean_property, ints use set_integer_property, strings use set_string_property, applied as plugins.<rule_id>.<property>. "enabled": false inside a rule map disables that rule.

markdown-tables stays off. pymarkdownlnt 0.9.40 raises BadTokenizationError on list lines that contain pipes, which breaks sanity on generated contents files. Until that is fixed, table rules MD055, MD056, MD058, and MD060 do not run. MD060 is also disabled because pymarkdown's delimiter-width check disagrees with Node markdownlint compact tables. Project tables use compact style: one space around cell text, including the delimiter row (| --- | ------- |).

Graph color and radius keys override the code defaults. The shipped template sets node_radius.max to 40. When the key is absent the renderer uses 25. Hover radius is min(current * size_multiplier, max) and returns to the pre-hover radius when the pointer leaves.

A mapping key under toc_generator.file whose name is not one of min_heading, max_heading, sectionize, ignore_files is an fnmatch override against the file path relative to the wiki root.

On wiki update, fiona-settings.json is deep-merged. Start from the template object. For each user key, if both sides are objects, merge recursively; otherwise the user value replaces the template value. New template keys that the user does not set are kept. Write the result as JSON with indent 2 and a trailing newline.

  • 5.1.1. Changing md013.line_length changes the next mdoctor scan with no code change.
    • acceptance: A line between the old and new limit is clean after the settings change and reported before it.
  • 5.1.2. A user value nested under markdown survives wiki update when the template also has that key, and a brand-new template key appears in the merged file.
    • acceptance: markdown.pymarkdown.md013.line_length set to 120 is still 120 after update, and a new template key is present.

5.2. settings_dev.json

{
  "pytests": {"required-coverage": 96},
  "progress": {"interval": 3, "expected-seconds": 30}
}
Key Default when absent Meaning
pytests.required-coverage (required for sanity) Minimum total coverage percent
progress.interval 3 Seconds between non-interactive dots
progress.expected-seconds 30 Bar scale for a running check
  • 5.2.1. Coverage below required-coverage fails sanity when every test passed.
    • acceptance: Raising the number in this file flips a green run to failed with no code change.

6. Violation Rule Catalog

6.1. Shared Report

Status: Implemented

Custom linters and the ruff wrapper print this shape. Sanity runners omit the report for a check with zero violations; the Results: row still shows the count.

<Linter Name> Violations
TARGET: <path>

- DEFINITIONS:
  - <code>: <rule_name>, <description>

- FILE: <path>
  - <message>

- SUMMARY:
  - Total files with violations: <N>
  - Total violations: <N>

A clean standalone run that still prints a report uses - No violations found. in place of the FILE section and still prints DEFINITIONS and SUMMARY. Headers:

Tool Header name
mdoctor PyMarkdownlint
fmlint Frontmatter Lint
python-ruff Ruff
pycustomlint Python Custom Lint
mdlinter Markdown Lint
json-lint JSONLint

Frontmatter messages omit a line:column prefix. Frontmatter is always at the start of the file.

  • 6.1.1. A report with one violation contains TARGET, DEFINITIONS, one FILE entry, and SUMMARY, in that order.
    • acceptance: The three custom linters and ruff use this order.

6.2. Frontmatter Fields and FML Codes

Status: Implemented

Required on every markdown file: name, version. All other fields are optional.

Field Required Rule
name yes Document name. Wiki pages use lowercase and hyphens.
version yes Semver. Bump when the page is edited.
title no Human title.
created no YYYY-MM-DD
updated no YYYY-MM-DD. Bump when the page is edited.
type no entity, concept, comparison, query, summary, toc
tags no Taxonomy tags from wiki/schema.md
sources no Paths such as raw/articles/source-name.md
confidence no Planned quality signal. Not enforced.
contested no Planned flag. Not enforced.
contradictions no Optional list of other page slugs.
description SKILL.md only Required on a file whose name is SKILL.md.

markdown.frontmatter.type_requirements maps a type value to the field list required for that type, in addition to the global list.

Code Name Message Fails when Passes when
FML001 Frontmatter Parse Error FML001 - <error> YAML between --- markers is invalid YAML parses
FML002 Missing Frontmatter FML002 No frontmatter block A block is present
FML003 Missing Name Field FML003 name absent name present
FML004 Missing Description FML004 SKILL.md has no description description present
FML005 Invalid Skill Name FML005 SKILL.md name fails ^[a-z0-9-]+$ name: python-tdd
FML006 Skill Name Mismatch FML006 - (expected: <folder>, got: <name>) name differs from the parent folder folder python-tdd and name: python-tdd
FML007 Missing Version Field FML007 version absent version present

SKILL.md is case-sensitive. FML005 and FML006 apply only to that filename. Scan skips .gitignore matches when respect_gitignore is true, ignore_file globs, and read-only zones.

  • 6.2.1. A markdown file with name and version and no title produces no FML violation.
    • acceptance: fmlint on that file reports no violations.
  • 6.2.2. SKILL.md in python-tdd/ with name: Python TDD is FML005, and name: other-name is FML006.
    • acceptance: The report code matches the case above.

6.3. MDL Codes

Status: Implemented

mdlinter scans .md files. Fenced code, inline code, links whose target starts with http://, https://, mailto:, or #, and any target containing ://, are ignored. Sources under personal/ and raw/ are skipped. Targets inside those zones are still resolved.

Code Name Message Fails when Passes when
MDL001 Dead Link line <n>: <target> does not exist A relative ](target) does not resolve to a file The relative file exists
MDL002 Dead Wiki Link line <n>: [[<target>]] does not resolve to any page A [[wikilink]] matches no markdown stem A stem matches, case-insensitive
MDL003 Wrapped Table Row line <n>: table row continues onto the next line; keep each row on one line A line starts with |, does not end with |, and the next line is not blank and not a new row. A following line that is only | counts as a continuation The row is one line, or the next line is blank or a new row, or the split is inside a fence

Wikilink syntax: [[page]], [[page#heading]], [[page|alias]]. The lookup key is the text before # or |, compared to markdown file stems in the wiki, case-insensitive. Markdown links resolve against the linking file's directory.

  • 6.3.1. A link to a deleted file is MDL001 with file, line, and target. A [[missing]] wikilink is MDL002.
    • acceptance: Both codes appear in one wiki that has one of each.
  • 6.3.2. A table row split across two lines is MDL003 on the opening line. The same split inside a fence is clean.
    • acceptance: Only the unfenced split is reported.

6.4. PYC Codes

Status: Implemented

pycustomlint scans .py files with the AST, skips .gitignore matches and read-only zones, and accepts --json for a JSON list of violation objects.

Code Name Severity Message Fails when Passes when
PYC001 Inline Import error PYC001 - Inline import at line <n>: <stmt> import or from is indented inside a function, class, try, or an if that follows a function or class Every import is at column 0, or it sits in a module-level if before the first function or class
PYC002 Import After Code warning PYC002 - Import after code at line <n>: <stmt> A module-level import follows a non-import statement Imports are grouped before other module statements
  • 6.4.1. import os inside a function is PYC001.
    • acceptance: The report names the file, the line, and import os.
  • 6.4.2. An import inside a module-level if, elif, or else that appears before the first function or class is not PYC001. The same import after that first function or class is PYC001. A try does not get this exception. An import inside a function or class is PYC001.
    • acceptance: if os.name == "nt": import msvcrt before any function is clean. The same if after a function is PYC001 and the message names import msvcrt.
    • acceptance: try: import os before any function is PYC001.

6.5. JSN Codes

Status: Implemented

json-lint parses with the standard json module. Style checks use section 5.1. Duplicate-key detection uses a parse hook so the last value does not hide the earlier key.

Code Name Severity Fails when Passes when
JSN001 JSON Syntax Error error The file is not JSON, including a trailing comma when that is a syntax error json.loads succeeds
JSN002 Indentation Error error Indent differs from indent / indent_len Indent matches
JSN003 Trailing Comma error A trailing comma is present and trailing_commas is false No trailing comma, or the setting allows them
JSN004 Duplicate Keys error An object repeats a key and check_duplicate_keys is true Keys are unique
JSN005 Key Order warning require_key_order is true and keys are not sorted Keys are sorted, or the setting is false
JSN006 Line Too Long warning max_line_length is set and a line exceeds it The key is absent, or every line fits
  • 6.5.1. A file with a missing comma reports JSN001 with line and column. A file with duplicate keys reports JSN004.
    • acceptance: Both cases name the file and the code.
  • 6.5.2. Four-space indent against indent_len: 2 is JSN002. json-lint fix rewrites it to two spaces.
    • acceptance: The fixed file is clean on the next chklint.

6.6. Base Linter Contract

Status: Implemented

  • 6.6.1. Shared behavior for fmlint, pycustomlint, mdlinter, and json-lint.
    • 6.6.1.1. Recursive file collection by extension.
    • 6.6.1.2. .gitignore and read-only-zone skipping.
    • 6.6.1.3. Settings load from fiona-settings.json.
    • 6.6.1.4. A violation record has filepath, line, column, code, message, rule id, and severity, plus a dict form for JSON.
    • 6.6.1.5. Report assembly follows section 6.1. The header is the linter name.
    • 6.6.1.6. The CLI is chklint [directory] and defaults to ..
  • 6.6.2. A new rule is a new checker used by one linter. It does not require an edit to the shared collector. Codes are unique: FML, MDL, PYC, JSN, plus pymarkdown MD codes and ruff codes.
    • acceptance: Existing FML and PYC tests still pass after a new MDL checker is registered.

7. Feature Requirements

7.1. wiki init

Status: Implemented

Implements sections 3 and 4.8.

  • 7.1.1. Copy is 1:1 aside from DATE_PLACEHOLDER and ignore_files.
    • acceptance: A pattern in ignore_files omits those paths and copies every other template file.
  • 7.1.2. Copied markdown keeps version and receives created / updated dates where the template used the placeholder.
    • acceptance: After init, those fields match YYYY-MM-DD for the UTC day of the run.

7.2. wiki update

Status: Implemented

Implements sections 4.9 and 4.10.

  • 7.2.1. Markdown core files are compared as follows.
    • 7.2.1.1. Both sides have version, and the template version is greater: update. Numeric dotted versions compare segment by segment (1.2.0 vs 1.10.0). Any other string compares as text.
    • 7.2.1.2. The wiki version is greater, or the versions are equal and the body differs after expanding DATE_PLACEHOLDER in the template: skip the file and report locally modified.
    • 7.2.1.3. Either version is missing: update when the expanded text differs. Binary files compare SHA-256.
  • 7.2.2. Other core files compare SHA-256 and update when the hash differs.
  • 7.2.3. fiona-settings.json uses the hash comparison to decide that an update is needed, then writes the deep merge from section 5.1.
  • 7.2.4. Missing template directories are created. User files that are not in the template stay. Read-only zones are never in the update set.
  • 7.2.5. A pristine init reports Wiki is up to date. and wiki update writes nothing.
    • acceptance: A second check-update still reports up to date.
  • 7.2.6. An older core markdown file is listed and, after a confirmed update, matches the template. A locally modified file is listed under skipped and is not overwritten.
    • acceptance: The modified file's bytes are unchanged after wiki update --yes.
  • 7.2.7. --dry-run prints the plan and leaves the tree unchanged.
    • acceptance: File hashes before and after a dry run match.
  • 7.2.8. --force and --yes skip the prompt, including on a non-TTY.
    • acceptance: The command exits 0 on a pipe when --yes is set and updates exist.

7.3. wiki sanity

Status: Implemented

Implements section 4.11. Markdown lint uses the wiki's own fiona-settings.json. Dead links are MDL001 and MDL002 inside mdlinter, not a separate check. New checks are added by registering another (name, runner) pair in the wiki sanity list.

  • 7.3.1. A clean wiki exits 0. Any violation exits 1.
    • acceptance: One dead link makes passed false in --json and produces a non-zero exit.
  • 7.3.2. --json output contains only JSON.
    • acceptance: The stdout of a --json run parses with json.loads and contains no ANSI sequences.
  • 7.3.3. Human output uses the progress display in 7.16.2. with label Running Wiki Sanity.
    • acceptance: A piped run prints that label and dots, and no ANSI escapes.

7.4. wiki graph

Status: Implemented

The renderer is D3 v7, loaded from https://d3js.org/d3.v7.min.js, with the visualization embedded in one HTML file. vis.js is not used.

  • 7.4.1. The parser extracts links as follows.
    • 7.4.1.1. Markdown links [text](path), including ./ and ../, resolve against the source file and are stored relative to the wiki root. A path without an extension is treated as .md.
    • 7.4.1.2. Wikilinks [[file]] and [[dir/file]] are parsed when wikilinks are enabled.
    • 7.4.1.3. External URLs (http://, https://, ftp://, and any ://) are counted. They become graph nodes only with --external-links.
    • 7.4.1.4. A link whose target file is missing is recorded as broken and does not abort the run.
  • 7.4.2. The graph is built as follows.
    • 7.4.2.1. A node is a markdown file. An edge is one or more links from source to target. Weight is the link count.
    • 7.4.2.2. An orphan has in-degree 0 and out-degree 0.
  • 7.4.3. --format json and --json emit this object.
{
  "metadata": {
    "wiki_root": "<path>",
    "file_count": 1,
    "link_count": 0,
    "generated_at": "<UTC ISO-8601>"
  },
  "nodes": [
    {"id": "wiki/a.md", "name": "a.md", "in_degree": 0, "out_degree": 0}
  ],
  "edges": [
    {"source": "wiki/a.md", "target": "wiki/b.md", "weight": 2}
  ],
  "orphans": ["wiki/a.md"]
}
  • 7.4.4. When external URLs were collected, metadata also has external_links_count (total occurrences) and external_links (unique URL strings).
  • 7.4.5. HTML behavior.
    • 7.4.5.1. One self-contained file. The layout fills the viewport and follows resize.
    • 7.4.5.2. Node radius scales with in-degree from min to max in section 5.1. Color interpolates low to mid over the first half of in_degree / max_in_degree, then mid to high. In-degree 0 uses the low color and the min radius.
    • 7.4.5.3. Edges use stroke width 1. Color runs from gray (weight 1) through yellow to red (maximum weight).
    • 7.4.5.4. Hover: the node uses the hover color and the capped larger radius. Connected edges use the hover edge color while they are gray. Leaving the node restores the previous radius.
    • 7.4.5.5. Single click toggles a persistent highlight and shows that file's frontmatter card at the upper left. Another node moves the highlight. Empty space clears it.
    • 7.4.5.6. Double click opens the markdown file.
    • 7.4.5.7. Search highlights matching nodes in light blue at 1.5 times radius (capped at max), shows neighbors in gray, and hides nodes that are not reachable from a match.
    • 7.4.5.8. A button, not a checkbox, shows or hides orphans.
    • 7.4.5.9. Overwrite of an existing output file asks for confirmation on a TTY.
    • 7.4.5.10. Files above max_files are skipped after a warning. The first max_files files are drawn.
    • 7.4.5.11. The run completes in under 10 seconds for 1000 files on a current developer machine.
  • 7.4.6. Layout constants live at the top of the HTML template so they can be tuned without hunting through the script.
Constant Value Role
LINK_STRENGTH 0.2 Pull along an edge; children follow a dragged parent
BASE_LINK_DISTANCE 60 Target distance from parent to child
LINK_DISTANCE_PER_DEGREE 0 Distance does not grow with degree
CHARGE_STRENGTH -20 Repulsion between nodes
CHARGE_DISTANCE_MIN 80 Near distance for repulsion
CHARGE_DISTANCE_MAX 200 Far cutoff for repulsion
NODE_ATTRACTION_STRENGTH 0 Extra attraction is off
CENTER_STRENGTH 0.001 Weak pull toward the viewport center
COLLIDE_STRENGTH 0.9 Overlap prevention
BASE_COLLIDE_RADIUS 15 Collision base
COLLIDE_PER_DEGREE 3 Extra collision radius per degree
EDGE_PADDING_MULTIPLIER 2 Extra gap so edges cross less often
ALPHA_DECAY 0.005 How fast the simulation cools
ALPHA_MIN 0.0005 Floor so correction continues
VELOCITY_DECAY 0.4 Motion damping
NEIGHBOR_REPEL_STRENGTH 0.2 Angular spring for the circle layout
CIRCULAR_RADIUS_MULTIPLIER 1.0 Circle radius equals BASE_LINK_DISTANCE
CIRCULAR_FORCE_MULTIPLIER 0.5 Strength of the 360-degree correction
  • 7.4.7. Initial placement is a breadth-first tree rooted at the highest in-degree node. Children sit on a circle at equal angles (360 / N degrees). Nodes fade in following that order, highest connectivity first. The circular force keeps running during drag so the angles recover.
  • 7.4.8. The output path must be writable. A failure is an error message and a non-zero exit.
  • 7.4.9. A wiki with one relative link and one wikilink produces two edges, and a file with neither is listed in orphans.
    • acceptance: The JSON edges weights match the link counts.
  • 7.4.10. --no-wikilinks drops wikilink edges and keeps markdown links.
    • acceptance: The wikilink target is absent from edges.
  • 7.4.11. Opening the HTML in a current browser shows the graph, hover, click highlight, search, and the orphan button.
    • acceptance: A node hover changes its color to the hover color and restores the previous radius on exit.

7.5. Git Operations

Status: Implemented

Implements section 4.7. personal/ is listed in .gitignore at wiki init and is never staged by these commands except where git add --all respects that ignore file.

  • 7.5.1. save --description note on a dirty tree creates one commit whose message starts with the UTC timestamp and ends with note.
    • acceptance: git log -1 --format=%s matches <YYYY-MM-DD HH:MM:SS> note.
  • 7.5.2. snapshot demo --description note then restore demo returns file bytes to the tagged tree and adds a new commit. The pre-restore history is still reachable.
    • acceptance: git rev-parse HEAD~1 after restore is the snapshot commit or a descendant, and the tagged tree matches the worktree.
  • 7.5.3. undo and restore on a dirty tree exit 1 and mention clean.
    • acceptance: The HEAD sha is unchanged.
  • 7.5.4. clean leaves git status empty of changes.
    • acceptance: A following status prints Status: clean.

7.6. Backup Script

Status: Planned

  • 7.6.1. NOT_IMPLEMENTED A bundled command writes a restorable archive of the wiki.
    • acceptance: Restoring that archive reproduces the wiki tree from before the archive.
  • 7.6.2. NOT_IMPLEMENTED The archive is stored outside the wiki tree.
    • acceptance: The archive path is not under the wiki root.
  • 7.6.3. NOT_IMPLEMENTED The filename is YYYYMMDD_hhmm_<description>.zstd.
    • acceptance: The file is valid zstd and the name matches.
  • 7.6.4. NOT_IMPLEMENTED The command asks for a directory and uses ~/Downloads when the user accepts the default.
    • acceptance: Pressing Enter writes the archive under ~/Downloads.

7.7. mdoctor

Status: Implemented

Implements section 4.3 and the pymarkdown keys in section 5.1. Settings load at construction. The default settings path is the packaged template fiona-settings.json. Callers, including run_sanity.py, may pass another path. A missing file means plain pymarkdown defaults.

  • 7.7.1. mdoctor fix repairs an auto-fixable violation such as MD047 and lists the path.
    • acceptance: The file ends with a newline and stdout contains PyMarkdownFix: 1 file(s) fixed.
  • 7.7.2. A tree with nothing to fix prints PyMarkdownFix: 0 file(s) fixed.
    • acceptance: That line is the only stdout line.

7.8. fmlint

Status: Implemented

Implements sections 4.4 and 6.2.

  • 7.8.1. required_fields in settings replaces the default pair on the next run.
    • acceptance: Adding title to the list reports a file that previously passed.
  • 7.8.2. enabled: false reports no frontmatter violations.
    • acceptance: A file with no frontmatter is clean for fmlint.
  • 7.8.3. A code in ignore_rules is omitted. A glob in ignore_file skips those paths.
    • acceptance: ignore_rules: ["FML002"] hides a missing-block finding and still reports a missing name.

7.9. mdlinter

Status: Implemented

Implements section 6.3. Checks run in registry order. A new check is a method plus an entry in that registry. lint_file resolves wikilinks against the file's parent tree. lint_directory scans the wiki.

  • 7.9.1. The report header is Markdown Lint Violations and the section order matches section 6.1.
    • acceptance: DEFINITIONS lists MDL001: Dead Link when a dead markdown link exists.

7.10. pycustomlint

Status: Implemented

Implements section 6.4. The sanity runner in section 7.16 includes it as pycustomlint. There is no fiona-assistant pycustomlint command; the repository runner calls the library.

  • 7.10.1. --json prints a JSON list of violation objects.
    • acceptance: json.loads succeeds and each object has code.

7.11. python-ruff

Status: Implemented

Implements section 4.5. The sanity check name is ruff in run_sanity.py and python-ruff in wiki sanity.

  • 7.11.1. An unused import appears in DEFINITIONS, FILE, and SUMMARY.
    • acceptance: The FILE line contains the ruff rule code.
  • 7.11.2. NOT_IMPLEMENTED A python-ruff fix subcommand mirrors mdoctor fix and calls the existing fix=True path.
    • acceptance: An auto-fixable ruff finding is gone after the command and the path is listed.

7.12. Shellcheck

Status: Planned

  • 7.12.1. NOT_IMPLEMENTED Wrap the shellcheck binary and print the shared report.
    • acceptance: A known shellcheck finding shows file, line, and rule code.
  • 7.12.2. NOT_IMPLEMENTED A missing binary prints an install hint and exits non-zero, with no traceback.
    • acceptance: The message names shellcheck.
  • 7.12.3. NOT_IMPLEMENTED Wiki sanity runs this check.
    • acceptance: The Results: table includes the new check name.

7.13. Markdown Code Blocks

Status: Planned

  • 7.13.1. NOT_IMPLEMENTED Extract fenced blocks. Lint Python blocks with Ruff and shell blocks with shellcheck. Skip other languages.
    • acceptance: An unused import inside a Python fence is reported. Prose outside fences is not.
  • 7.13.2. NOT_IMPLEMENTED The finding names the markdown path, the fence index, the line inside the fence, and the markdown line number.
    • acceptance: The reported markdown line is the fence line that contains the import.
  • 7.13.3. NOT_IMPLEMENTED Wiki sanity runs this check.
    • acceptance: The check appears in the Results: table.

7.14. Non-markdown Version Tags

Status: Planned

  • 7.14.1. NOT_IMPLEMENTED Python and shell files gain a version tag. The tag format is undecided (section 10). Do not implement until that format is chosen.
    • acceptance: The format is written in this spec before any scanner ships.

7.15. Folder and In-file TOC

Status: Implemented

  • 7.15.1. Folder TOC (librarian toc).
    • 7.15.1.1. table_of_contents.md has frontmatter title, created, updated, and type: toc.
    • 7.15.1.2. Entries list subfolders, file links, and v<version>, or v0.0.0 when version is missing or unreadable.
    • 7.15.1.3. Headers become nested GitHub-style anchor links. Fenced code is not scanned. Files are read as utf-8-sig so a BOM does not hide the first header.
    • 7.15.1.4. Skip the TOC file itself, hidden folders, and --exclude matches.
    • 7.15.1.5. --recursive-toc writes a TOC in every subfolder.
    • 7.15.1.6. --non-recursive lists only markdown files directly in the folder, ignoring max_depth_from_dir.
    • 7.15.1.7. max_depth_from_file is the deepest header level (3 lists h1 through h3). max_depth_from_dir is how many subfolder levels to include (1 includes the folder and its children). Absent or 0 means unlimited. Any other non-integer or negative value exits 1 and names the key.
  • 7.15.2. In-file TOC (librarian toc file).
    • 7.15.2.1. Insert directly under the H1, after frontmatter. The H1 itself is not listed. Headings inside fences are not listed. A # inside frontmatter is not the H1.

    • 7.15.2.2. The block is wrapped in these markers. sectionized is present only when numbering was on.

      <!-- toc-start: headings 2..6 -->
      <!-- toc-end -->
      

      Example with numbering: <!-- toc-start: sectionized, headings 2..6 -->.

    • 7.15.2.3. On regeneration, marker parameters win, then --sectionized, then settings. A sectionized marker keeps numbering. The recorded heading range stays, so a later settings change does not retarget an existing TOC. A bare <!-- toc-start --> has no parameters and is upgraded on regeneration. An invalid range is ignored with a warning.

    • 7.15.2.4. The block is replaced in place. A current block is reported unchanged and not rewritten. Blank lines separate the markers from the list so MD032 passes.

    • 7.15.2.5. When sectionize is true, entries and heading lines gain numbers such as 1.1.. Existing numbers are stripped before renumbering so anchors still match.

    • 7.15.2.6. toc file * root is the nearest fiona-settings.json, current directory first, then subdirectories. Skip hidden folders and build/, dist/, __pycache__/, *.egg-info/. If none is found, use the current directory.

    • 7.15.2.7. toc file * skips read-only zones, hidden files and folders, table_of_contents.md, and ignore_files matches.

    • 7.15.2.8. toc file <explicit path> inside personal/ or raw/, or a missing or non-markdown path, exits 1 and writes nothing.

  • 7.15.3. Two markdown files in a folder produce one TOC that lists both versions and their headers, and omits a header that sits inside a fence.
    • acceptance: The fence header's anchor is absent.
  • 7.15.4. max_depth_from_file: 3 omits #### and lists ###. Absent or 0 lists every level.
    • acceptance: The #### line is absent only in the capped run.
  • 7.15.5. max_depth_from_dir: 1 omits files two levels down. Absent or 0 lists them. --non-recursive lists only the folder's own files.
    • acceptance: The deep file is absent in both limited modes.
  • 7.15.6. Re-running toc file replaces the marked block and does not append a second TOC.
    • acceptance: The file contains one toc-start marker.
  • 7.15.7. min_heading: 3 omits ##. max_heading: 3 omits ####.
    • acceptance: Each setting hides only its out-of-range level.
  • 7.15.8. An ignore_files match is not modified by toc file *. An explicit path in personal/ exits 1 and is unchanged.
    • acceptance: Both files keep their original bytes.

7.16. Test and Sanity Runners

Status: Implemented

  • 7.16.1. Shared engine, used by run_sanity.py and wiki sanity.
    • 7.16.1.1. One thread per check. Results stay in registry order.
    • 7.16.1.2. Summary line PASS/FAIL - <detail> (MM:SS). Minutes may exceed 59 and are zero-padded. A missing duration omits the suffix.
    • 7.16.1.3. SANITY PASSED (MM:SS) lists check names in registry order. Sanity Failed - N checks need attention: has no total time.
    • 7.16.1.4. A runner may add an extra result row, such as coverage, and per-check failure details.
    • 7.16.1.5. progress(name, result) runs when a check finishes. heartbeat(remaining_names) runs about every 0.5 seconds. Start and finish are logged at INFO.
  • 7.16.2. Progress display.
    • 7.16.2.1. On a TTY, one bar per check, redrawn in place with cursor-up and line clear. Example: pytests [###------------] 22% 6.5s.
    • 7.16.2.2. The bar fills as elapsed / expected-seconds, capped at 100%.
    • 7.16.2.3. A finished check shows a full bar and (MM:SS): markdownlint [###############] 100% done (00:07).
    • 7.16.2.4. The final block stays on screen above the reports.
    • 7.16.2.5. --non-interactive, also when stdout is not a TTY, prints Running Sanity or Running Wiki Sanity once, then one dot per interval seconds. A run shorter than the interval prints no dots. A newline ends the line before the report. No ANSI.
    • 7.16.2.6. --json on wiki sanity skips the display.
    • 7.16.2.7. Bar scale and dot interval come from section 5.2.
  • 7.16.3. run_tests.py and the pytests check.
    • 7.16.3.1. The command includes --color=no and JUnit XML junit_family=xunit1.
    • 7.16.3.2. Displayed messages prefer regex-parsed pytest output. JUnit fills missing fields and replaces empty messages. Match by basename plus test name so path spellings do not duplicate a failure.
    • 7.16.3.3. A missing short summary logs a WARNING that names PYTEST_ADDOPTS, --no-summary, and plugin output as likely causes.
    • 7.16.3.4. LOG_LEVEL=DEBUG logs the pytest command, return code, parsed failures, and raw output when the parse disagrees.
    • 7.16.3.5. The report nests failures as Class : test_name under the file, then the assert text, or the exception text when there is no assert line.
    • 7.16.3.6. The Sanity Failed verdict lists failing test names only. Assert text stays in the report body.
    • 7.16.3.7. The coverage: line is PASS/FAIL - <percent>% (required <percent>%) and is untimed. A shortfall is its own verdict entry.
  • 7.16.4. run_sanity.py check order is pytests, markdownlint, ruff, frontmatter_lint, pycustomlint, jsonlint.
  • 7.16.5. A failing test is listed under its file with the assert text when pytest is run with --no-summary or PY_COLORS=1.
    • acceptance: The name and assert still appear.
  • 7.16.6. A green run prints every Results: line with (MM:SS) and ends with SANITY PASSED (MM:SS).
    • acceptance: The banner time is the wall time of the whole run.
  • 7.16.7. A piped run contains no ANSI and prints one dot per interval after the label, unless the run is shorter than the interval.
    • acceptance: The captured stdout has no ESC byte.

7.17. html-js-lint

Status: Planned

The html-js-lint console script is not installed until this section is built. The intended tool validates HTML with html5validator (Java 8+) and JavaScript with eslint on PATH.

  • 7.17.1. NOT_IMPLEMENTED HTML files (default .html and .htm) are checked. Findings include path, line, and column. .gitignore and read-only zones are skipped.

    • acceptance: An unclosed tag is reported. A valid file is not. A tree with no HTML prints no HTML findings.
  • 7.17.2. NOT_IMPLEMENTED JavaScript files (default .js and .javascript) are checked with eslint, honoring .eslintrc.

    • acceptance: A syntax error names path, line, and message. A clean file produces no finding.
  • 7.17.3. NOT_IMPLEMENTED Inline <script> is linted only when html.lint_inline_js is true (default false). Findings use the HTML path and line.

    • acceptance: With the flag off, inline script is ignored.
  • 7.17.4. NOT_IMPLEMENTED CLI is fiona-assistant html-js-lint, default chklint ., shared report, exit 0 even with violations, and --fix where the underlying tool can fix.

    • acceptance: --fix reports how many files changed.
  • 7.17.5. NOT_IMPLEMENTED Settings, under a dedicated section, with defaults when the section is missing:

    Key Default
    html.extensions ["html", "htm"]
    html.ignore_patterns []
    html.lint_inline_js false
    javascript.extensions ["js", "javascript"]
    javascript.eslint_config .eslintrc
    javascript.ignore_patterns []
    • acceptance: A custom extension list is the set that is scanned.
  • 7.17.6. NOT_IMPLEMENTED Both run_sanity.py and wiki sanity run this check.

    • acceptance: A violation fails that sanity run.

7.18. json-lint

Status: Implemented

Implements sections 4.6 and 6.5. Both sanity runners include it.

  • 7.18.1. A JSON violation fails run_sanity.py and wiki sanity.
    • acceptance: The Results: row for jsonlint is FAIL and the process exit code is non-zero.
  • 7.18.2. An empty tree of JSON files prints no violations.
    • acceptance: The report says no violations were found.

7.19. settings setup

Status: Planned

fiona-assistant init remains the non-interactive wiki bootstrap (section 7.1): it copies the template and does not ask questions. fiona-assistant setup is a separate command for reviewing settings on an existing wiki. It does not create the wiki tree.

  • 7.19.1. NOT_IMPLEMENTED setup walks every configurable key in fiona-settings.json, shows the current value, and accepts Enter as "keep current".
    • acceptance: Enter through every prompt leaves the file semantically unchanged.
  • 7.19.2. NOT_IMPLEMENTED Booleans can be toggled. Strings and integers accept a typed value. Values are checked before write.
    • acceptance: A non-integer for indent_len is rejected and the file is not written.
  • 7.19.3. NOT_IMPLEMENTED --yes or --default applies defaults with no prompts.
    • acceptance: The command exits 0 on a pipe when the flag is set.
  • 7.19.4. NOT_IMPLEMENTED A missing settings file is created from the template defaults. A corrupt file is reported and not silently replaced.
    • acceptance: Exit 0 after creating a missing file. Exit non-zero on corrupt JSON, with the parse error on stderr.
  • 7.19.5. NOT_IMPLEMENTED setup can be run again later to change an existing wiki.
    • acceptance: A second run can change log_level and leave every other key as it was.

7.20. Logging

Status: Implemented

The contract is section 2. Reports stay on stdout. Diagnostics go through the logging module to stderr and, when configured, to the file sink.

  • 7.20.1. Each CLI entry calls the shared setup before doing work.
    • acceptance: LOG_LEVEL=DEBUG emits debug lines on stderr and the human report stays on stdout.
  • 7.20.2. Dropping file_log_location leaves no file handler.
    • acceptance: No log file is created for that run.

7.21. Documentation

Status: Partially Implemented

README.md links to this spec. src/README.md, src/fiona/librarian/README.md, and src/fiona/mdoctor/README.md exist and are behind the current CLIs.

  • 7.21.1. NOT_IMPLEMENTED librarian/README.md documents list and toc. mdoctor/README.md documents list, chklint, and fix.
    • acceptance: A new reader can install and run each command from those files alone.
  • 7.21.2. src/README.md describes src/fiona/ (including wiki/, python_ruff/, and data/llm_wiki/), repo-root tests/, and scripts/ (run_tests.py, run_sanity.py, settings_dev.json).
    • acceptance: Those names appear in the structure section.
  • 7.21.3. Documentation markdown passes mdoctor chklint.
    • acceptance: README.md contains a markdown link to SPEC.md and the lint report is clean.

7.22. Tool Roles

Status: Planned

  • 7.22.1. NOT_IMPLEMENTED Each src/ tool has one role: ingestion (ingest/ to raw/), processing (raw/ to wiki/concepts/), or maintenance (index.md / log.md and the linters).
    • acceptance: A table in this spec or the README assigns every tool exactly one role.
  • 7.22.2. NOT_IMPLEMENTED Missing ingestion and processing steps become scripts under the template utils/ directory, such as ingest.py and process.py.
    • acceptance: Each new script is named in the role table.

7.23. Wiki Root Discovery

Status: Planned

Today every optional directory defaults to .. toc file * already searches for fiona-settings.json as specified in section 7.15. Graph settings already walk parent directories. The dispatcher does not.

  • 7.23.1. NOT_IMPLEMENTED When the directory argument is omitted, commands use the wiki root from section 10's discovery rule.
    • acceptance: fiona-assistant mdoctor from a subdirectory lints that root, not the subdirectory.
  • 7.23.2. NOT_IMPLEMENTED An explicit directory always wins.
    • acceptance: mdoctor chklint sub/dir lints sub/dir even when a settings file exists higher up.
  • 7.23.3. NOT_IMPLEMENTED With no settings file found, the default stays ..
    • acceptance: Behavior matches today's commands.
  • 7.23.4. NOT_IMPLEMENTED The file is loaded once per process and shared. mdoctor already reads it for rules.
    • acceptance: Two tools in one invocation see the same object.

8. Non-Goals

  • 8.1. No LLM or network API inside Fiona-Assistant. The tools are deterministic.
  • 8.2. No automated edit of personal/ or raw/ content.
  • 8.3. No cloud sync and no remote backup. Version control is local. The planned archive in 7.6. is a local file.
  • 8.4. Deterministic tools make no cloud API calls. Each command uses only local files and finishes with no network access.
    • acceptance: With the network unavailable, wiki sanity and wiki graph still complete on a local wiki.
    • acceptance: Opening the generated graph HTML is the one exception: the browser loads D3 from d3js.org (7.4.). The generator itself does not call that host.

9. Priority Order

Priority Feature Section Status
P1 wiki update / check-update 7.2 Implemented
P1 Git save, snapshot, restore, clean, undo, status 7.5 Implemented
P1 wiki sanity, including dead links 7.3 Implemented
P1 wiki graph 7.4 Implemented
P2 fmlint 7.8 Implemented
P2 json-lint 7.18 Implemented
P2 mdoctor fix 7.7 Implemented
P2 Settings schema 5 Implemented
P2 Sanity reporting, coverage, progress 7.16 Implemented
P2 Shellcheck 7.12 Planned
P2 Markdown code-block lint 7.13 Planned
P2 html-js-lint 7.17 Planned
P2 python-ruff fix subcommand 7.11.2 Planned
P2 Wiki root discovery 7.23 Planned
P2 settings setup 7.19 Planned
P3 confidence and contested tags 6.2 Planned
P3 Backup archive 7.6 Planned
P3 Documentation refresh 7.21 Partially Implemented
P4 Non-markdown version tags 7.14 Planned
P4 Tool-role table 7.22 Planned

10. Open Questions

  • Python and shell version-tag format (section 7.14) is undecided. Do not build a scanner until this section names the format.
  • Wiki root discovery when several fiona-settings.json files exist under the start directory: the rule is not chosen. Candidates are "the nearest directory wins" and "error when two files sit at the same depth". Parent walk is already what graph settings do, and is a third candidate for the default directory. Section 7.23 stays planned until one rule is written here.
  • json-lint chklint exits 1 when violations exist. mdoctor, fmlint, and python-ruff exit 0. A future change may align them. Until this line changes, implement the split in section 4.

Appendix A. Maintainer Notes

These notes are not requirements. They point at the current tree.

Area Module
CLI dispatch src/fiona/__main__.py
Logging src/fiona/logging_config.py
template path src/fiona/paths.py
librarian list src/fiona/librarian/librarian.py
TOC src/fiona/librarian/toc_generator.py
mdoctor src/fiona/mdoctor/mdoctor.py
fmlint, mdlinter, pycustomlint, json-lint src/fiona/customlinter/
ruff wrapper src/fiona/python_ruff/python_ruff.py
wiki init src/fiona/wiki/wiki.py
wiki update src/fiona/wiki/update_manager.py
wiki sanity src/fiona/wiki/sanity_manager.py
wiki graph src/fiona/wiki/graph_generator.py, src/fiona/wiki/templates/graph_template.html
git src/fiona/gittool/git_tool.py
sanity engine src/fiona/sanity_runner/sanity_runner.py
runners src/fiona/run_tests.py, src/fiona/run_sanity.py
launchers scripts/run_tests.py, scripts/run_sanity.py

Known defects to avoid copying blindly:

  • json-lint fix walks the file list twice. The observable contract is one count and one path line per fixed file.
  • The previous spec's graph physics (mass = 1 + in_degree * 0.5, center 0.1, alphaMin 0.1, velocityDecay 0.6, and "D3 or vis.js") does not match the template. Section 7.4 is the contract.
  • The previous spec's external-link JSON used {url, count} objects. The implementation emits unique URL strings plus a total count.
  • pymarkdown rule typos fail silently (section 5.1).
  • mdoctor fix does not skip read-only zones (section 4.3).