Version 1.…1.0 SPEC subsection improvement, and wiki update refinement

This commit is contained in:
nvaldez
2026-10-01 11:36:20 +02:00
parent 482b2cb2e0
commit 9e98390f2b
41 changed files with 1179 additions and 1094 deletions
+4 -4
View File
@@ -1,10 +1,10 @@
---
name: Fiona-Assistant Development Agent Rules
version: 1.9.1
version: 1.9.2
title: Agents
type: summary
created: 2025-09-23
updated: 2026-09-30
updated: 2026-10-01
tags: [agents, rules, guidelines, llm, ai]
sources: []
---
@@ -103,7 +103,7 @@ Before step 2, load the environment (project agent rule 3.1).
- Semver: patch for a clarification, minor for a new rule or
requirement, major for a breaking contract change.
- Bump [SPEC](./SPEC.md) when step 1 or step 4 changed it.
- Python and shell files have no version tag yet (SPEC 4.8.1).
- Python and shell files have no version tag yet (SPEC 7.3.2.1).
Leave them untagged.
A documentation edit that does not change product behavior still
@@ -422,7 +422,7 @@ llm:
- reasoning: high # when the model reports a level
contested: true
contradictions: [other-page-slug]
# written by wiki ingest (SPEC 7.25), optional:
# written by wiki ingest (SPEC 7.1.5), optional:
status: raw | refined
source_meta: {author: Name} # metadata read from the source
ingest: # provenance; every key always present
+883 -848
View File
File diff suppressed because it is too large Load Diff
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "fiona-assistant"
version = "0.99.0"
version = "1.1.0"
description = "Tools for managing the LLM wiki."
authors = [{name = "nvaldeziii"}]
readme = "README.md"
+1 -1
View File
@@ -2,7 +2,7 @@
Generated by AI/LLM: 2026-09-30 - local and no-env install options.
SPEC 7.24. Both ``bootstrap`` and ``bootstrap.ps1`` call this script
SPEC 7.21. Both ``bootstrap`` and ``bootstrap.ps1`` call this script
and read one pip argument per stdout line.
"""
+1 -1
View File
@@ -289,7 +289,7 @@ def main():
)
add_ingest_arguments(wiki_ingest_parser)
# AI/LLM: fiona-assistant housekeeping (SPEC 4.15)
# AI/LLM: fiona-assistant housekeeping (SPEC 4.8)
housekeeping_parser = subparsers.add_parser(
"housekeeping",
help="Run the wiki maintenance routine and report what needs work"
@@ -4,8 +4,8 @@ category: productivity
description: Operate an llm-wiki with the fiona-assistant CLI.
author: nvaldez
license: MIT
version: 1.11.0
updated: 2026-09-30
version: 1.12.0
updated: 2026-10-01
---
# Fiona
@@ -195,7 +195,7 @@ python -m pip install fiona-assistant
| Ingested pages not refined yet? | `wiki ingest --pending --json` |
| Empty directory, start a wiki? | `wiki init <dir>` |
| Template behind the installed package? | `wiki check-update`, then `wiki update --dry-run` |
| A `*-update.md` file appeared? | Merge it, section 17.1 |
| A `*-update` file appeared? | Merge it, section 17.1 |
| Ingest or housekeeping done? | `git save --description TEXT` |
Prefix every row with `fiona-assistant`.
@@ -242,7 +242,7 @@ When something differs, the lines that apply:
```text
Files to update: <N>
Conflicts (owner copy kept): <N>
- <path> (<current> -> <template>) -> <stem>-update.md
- <path> (<current> -> <template>) -> <stem>-update<suffix>
Directories to add: <N>
Files to add: <N>
Total: <N> file(s) need attention
@@ -271,11 +271,14 @@ compared.
fiona-assistant wiki update [directory] [--dry-run] [-y|--yes] [-f|--force] [--json]
```
Updates drifted non-markdown core files (settings are deep-merged,
the owner's values win) and adds missing core files. Never deletes
user files. Never writes inside `personal/` or `raw/`. Never adds
or overwrites anything under `wiki/` (seeded at init, then filled
by the LLM). Never writes a path matched by `.gitignore`.
Updates drifted non-markdown core files in place and adds missing
core files. A differing `fiona-settings.json` is a conflict: the
owner's file stays byte-for-byte, and the template is written
beside it as `fiona-settings-update.json`. You merge it during
housekeeping (section 17.1). Never deletes user files. Never writes
inside `personal/` or `raw/`. Never adds or overwrites anything
under `wiki/` (seeded at init, then filled by the LLM). Never
writes a path matched by `.gitignore`.
Never overwrites an existing markdown file. When the template has a
newer version of one, such as `AGENTS.md`, `wiki/index.md`,
@@ -295,8 +298,11 @@ Success stdout:
Update complete: <U> file(s) updated, <A> added, <C> conflict(s), <S> skipped.
```
When `<C>` is not zero, the next line tells you to run
`fiona-assistant housekeeping`.
When `<C>` is not zero, the next line is:
```text
Merge each <stem>-update<suffix> into its file: run fiona-assistant housekeeping.
```
### 4.4. sanity
@@ -902,7 +908,7 @@ your part.
| Step | Status when not clean | You do |
| --- | --- | --- |
| `check-update` | `WARN`: the template has updates, conflicts, or additions | Ask the user, then `wiki update --dry-run` and `wiki update --yes`. |
| `merge` | `FAIL`: a `*-update.md` file exists | Section 17.1. |
| `merge` | `FAIL`: a file whose stem ends with `-update` exists | Section 17.1. |
| `ingest` | `WARN`: a page under `wiki/` is at `status: raw` | Refine it, section 16.4. |
| `sanity` | `FAIL`: a `wiki sanity` violation | Fix it, section 12. |
| `graph` | `WARN`: a page under `wiki/` has no link in or out | Link it from a related page or from `wiki/index.md`. |
@@ -926,8 +932,11 @@ newer version of a markdown file the owner may have edited, such as
the owner's file stays as it is and the template is written beside
it as `<stem>-update.md`. `AGENTS-update.md` belongs to
`AGENTS.md`; `wiki/schema-update.md` belongs to `wiki/schema.md`.
The update file is the new template text, as `wiki init` would
write it. You decide how the two become one file:
A differing `fiona-settings.json` is the same kind of conflict:
the owner's file stays, and the template is
`fiona-settings-update.json`. The update file is the new template
text, as `wiki init` would write it. You decide how the two become
one file:
1. Read both files. Compare them, for example with
`git diff --no-index <file> <stem>-update.md`.
@@ -950,6 +959,15 @@ write it. You decide how the two become one file:
8. Run `fiona-assistant housekeeping` again. `merge` passes when no
update file is left.
For `fiona-settings-update.json`, merge by the settings rule. Start
from the template object. For each user key, if both sides are
objects, merge recursively; otherwise the user value replaces the
template value. Keep new template keys the user does not set. Write
the result as JSON with indent 2 and a trailing newline, then delete
`fiona-settings-update.json`. Settings have no `version` field. A
later `wiki update` conflicts again only when the owner bytes still
differ from the template. Log the merge the same way as step 7.
When you cannot tell whether an owner edit or a template change
should win, ask the user. Do not delete an update file you have not
merged unless the user says to drop it. When the target file is
+3 -3
View File
@@ -214,7 +214,7 @@ class FileTocError(Exception):
@dataclasses.dataclass(frozen=True)
class FileTocConfig:
"""Parameters for per-file TOC generation (SPEC 7.15.2).
"""Parameters for per-file TOC generation (SPEC 7.3.1.2).
Attributes:
min_heading: Smallest heading level included (never below 2;
@@ -359,7 +359,7 @@ def merge_marker_config(lines: list[str], base: FileTocConfig) -> FileTocConfig:
"""Apply the existing marker's params over the base config.
The marker records this TOC's own settings and has priority
(SPEC 7.15.2): a `sectionized` marker keeps section numbering on
(SPEC 7.3.1.2): a `sectionized` marker keeps section numbering on
and the recorded heading range sticks, so regenerations keep the
TOC's identity regardless of settings changes. Fields the marker
does not record (bare legacy markers, plain markers without
@@ -673,7 +673,7 @@ def _file_toc_star(sectionized: bool) -> None:
def file_toc_main(argv: list[str]) -> None:
"""CLI for per-file TOC generation (SPEC 7.15.2)."""
"""CLI for per-file TOC generation (SPEC 7.3.1.2)."""
parser = argparse.ArgumentParser(
prog="toc_generator file",
description="Generate an in-file table of contents below the H1 heading.",
+2 -2
View File
@@ -1,4 +1,4 @@
"""Shared logging configuration for all Fiona tools (SPEC 7.20).
"""Shared logging configuration for all Fiona tools (SPEC 7.17).
Diagnostics go through the standard `logging` module with the level
resolved from (highest precedence first):
@@ -30,7 +30,7 @@ DEFAULT_LOG_LEVEL = "WARNING"
DEFAULT_SETTINGS_FILE = llm_wiki_template() / "fiona-settings.json"
# Tool package loggers that carry the level explicitly: pymarkdown
# resets the root logger to WARNING mid-run, which would otherwise
# silence tool diagnostics (same pattern as run_sanity, see SPEC 7.20).
# silence tool diagnostics (same pattern as run_sanity, see SPEC 7.17).
TOOL_LOGGER_NAMES = ("fiona",)
LOG_FORMAT = "%(levelname)s %(name)s: %(message)s"
+3 -3
View File
@@ -1,7 +1,7 @@
"""Sanity Check Runner for Fiona-Assistant project.
Runs its checks through the shared SanityRunner engine
(src/sanity_runner, SPEC 7.16.1): concurrent execution, per-check
(src/sanity_runner, SPEC 7.14.1): concurrent execution, per-check
timings, and the common report format. This module keeps only the
repository-specific checks, their summaries, and the report
presentation.
@@ -626,7 +626,7 @@ def coverage_met(check_result: dict) -> bool:
def format_duration(seconds: float) -> str:
"""Format a duration in seconds as zero-padded MM:SS.
Delegates to the shared SanityRunner engine (SPEC 7.16.1).
Delegates to the shared SanityRunner engine (SPEC 7.14.1).
Args:
seconds: Duration in seconds.
@@ -640,7 +640,7 @@ def format_duration(seconds: float) -> str:
def format_check_summary(check_name: str, check_result: dict) -> str:
"""Format a single check result as a human/AI-friendly line.
Delegates to the shared SanityRunner engine (SPEC 7.16.1); the
Delegates to the shared SanityRunner engine (SPEC 7.14.1); the
pytests and coverage summaries plug in as formatters.
Args:
+1 -1
View File
@@ -3,7 +3,7 @@
Provides `SanityRunner`, the generalized class shared by the
repository sanity runner (run_sanity) and the wiki sanity command
(wiki.sanity_manager): concurrent check execution with per-check
timings and the common AI-friendly report format (SPEC 6.1/7.16.1).
timings and the common AI-friendly report format (SPEC 6.1/7.14.1).
"""
from fiona.sanity_runner.sanity_runner import (
+5 -5
View File
@@ -1,13 +1,13 @@
"""Shared sanity runner engine (SPEC 7.16.1).
"""Shared sanity runner engine (SPEC 7.14.1).
This module provides `SanityRunner`, the generalized class behind both
sanity runners in the project:
- the repository sanity runner (`fiona.run_sanity`, SPEC 7.16)
- the wiki sanity command (`src/wiki/sanity_manager.py`, SPEC 7.3)
- the repository sanity runner (`fiona.run_sanity`, SPEC 7.14)
- the wiki sanity command (`src/wiki/sanity_manager.py`, SPEC 7.1.3)
The class owns the common machinery: concurrent check execution with
per-check wall-clock timings (SPEC 7.16.1) and the shared AI-friendly
per-check wall-clock timings (SPEC 7.14.1) and the shared AI-friendly
report structure (SPEC 6.1) — one-line check summaries, the aligned
`Results:` table rows, the `SANITY PASSED (MM:SS)` banner, and the
`Sanity Failed` footer. Per-check specifics (summary wording, extra
@@ -111,7 +111,7 @@ class SanityRunner:
Each result carries its wall-clock `duration_seconds`; times of
parallel checks overlap and need not sum to the total
(SPEC 7.16.1). The returned mapping keeps the registry order
(SPEC 7.14.1). The returned mapping keeps the registry order
regardless of completion order. The check lifecycle (start and
completion with duration) is logged at INFO.
+36 -14
View File
@@ -1,4 +1,4 @@
"""Wiki housekeeping routine (SPEC 4.15, 7.26).
"""Wiki housekeeping routine (SPEC 4.8, 7.2).
Generated by AI/LLM: 2026-09-30 - one call for LLM wiki maintenance.
@@ -10,7 +10,7 @@ gathers what needs work; it writes only `wiki_graph.html`.
Steps, in order (`STEP_NAMES`):
- `check-update`: core files behind the packaged template (read-only).
- `merge`: `*-update.md` files that `wiki update` left for a merge.
- `merge`: files whose stem ends with `-update` that `wiki update` left for a merge.
- `ingest`: pages under `wiki/` still at `status: raw`.
- `sanity`: every `wiki sanity` check.
- `graph`: regenerate `wiki_graph.html` and list orphan pages.
@@ -59,7 +59,7 @@ def _step(name: str, status: str, summary: str, details: list[str] | None = None
next_steps: list[str] | None = None) -> dict:
"""Build one step result.
Generated by AI/LLM: 2026-09-30 - shared step shape (SPEC 4.15).
Generated by AI/LLM: 2026-09-30 - shared step shape (SPEC 4.8).
"""
return {
"name": name,
@@ -90,6 +90,28 @@ def _frontmatter(path: Path) -> dict:
return frontmatter if isinstance(frontmatter, dict) else {}
def _wiki_files(wiki_root: Path) -> list[Path]:
"""List files outside read-only zones and `.git`, sorted.
Modified by AI/LLM: 2026-10-01 - merge walks every suffix, not only markdown.
Args:
wiki_root: Root path of the wiki.
Returns:
list[Path]: Files found.
"""
found = []
for current, dirs, files in os.walk(wiki_root):
at_root = Path(current) == wiki_root
dirs[:] = [
name for name in dirs
if name != ".git" and not (at_root and name in ROOT_SKIP_DIRS)
]
found.extend(Path(current) / name for name in files)
return sorted(found)
def _markdown_files(wiki_root: Path, subdir: str = "") -> list[Path]:
"""List markdown files outside read-only zones and `.git`, sorted.
@@ -119,7 +141,7 @@ def _markdown_files(wiki_root: Path, subdir: str = "") -> list[Path]:
# =============================================================================
def check_update_step(wiki_root: Path) -> dict:
"""Report core files behind the template without writing (SPEC 7.26.2).
"""Report core files behind the template without writing (SPEC 7.2.2).
Generated by AI/LLM: 2026-09-30 - read-only wiki check-update.
"""
@@ -142,16 +164,16 @@ def check_update_step(wiki_root: Path) -> dict:
def merge_step(wiki_root: Path) -> dict:
"""List update files that wait for an LLM merge (SPEC 7.26.3).
"""List update files that wait for an LLM merge (SPEC 7.2.3).
Generated by AI/LLM: 2026-09-30 - pending *-update.md merges.
Modified by AI/LLM: 2026-10-01 - any stem ending in -update, including JSON.
"""
details, actions = [], []
for update_file in _markdown_files(wiki_root):
if not update_file.name.endswith(UPDATE_FILE_SUFFIX):
for update_file in _wiki_files(wiki_root):
if not update_file.stem.endswith(UPDATE_SUFFIX):
continue
target = update_file.with_name(
update_file.name[: -len(UPDATE_FILE_SUFFIX)] + ".md"
update_file.stem[: -len(UPDATE_SUFFIX)] + update_file.suffix
)
update_rel = _relative(update_file, wiki_root)
target_rel = _relative(target, wiki_root)
@@ -168,7 +190,7 @@ def merge_step(wiki_root: Path) -> dict:
def ingest_step(wiki_root: Path) -> dict:
"""List pages under wiki/ still at `status: raw` (SPEC 7.26.4).
"""List pages under wiki/ still at `status: raw` (SPEC 7.2.4).
Generated by AI/LLM: 2026-09-30 - pages waiting for a refine.
"""
@@ -185,7 +207,7 @@ def ingest_step(wiki_root: Path) -> dict:
def sanity_step(wiki_root: Path) -> dict:
"""Run every wiki sanity check without the progress display (SPEC 7.26.5).
"""Run every wiki sanity check without the progress display (SPEC 7.2.5).
Generated by AI/LLM: 2026-09-30 - failing check reports as details.
"""
@@ -205,7 +227,7 @@ def sanity_step(wiki_root: Path) -> dict:
def graph_step(wiki_root: Path) -> dict:
"""Write wiki_graph.html at the wiki root and list orphans (SPEC 7.26.6).
"""Write wiki_graph.html at the wiki root and list orphans (SPEC 7.2.6).
Generated by AI/LLM: 2026-09-30 - graph plus orphan pages under wiki/.
"""
@@ -241,7 +263,7 @@ def graph_step(wiki_root: Path) -> dict:
# =============================================================================
def run_housekeeping(directory: str | Path = ".") -> dict:
"""Run every housekeeping step over a wiki (SPEC 7.26.1).
"""Run every housekeeping step over a wiki (SPEC 7.2.1).
Generated by AI/LLM: 2026-09-30 - every step runs, even after a FAIL.
@@ -280,7 +302,7 @@ def run_housekeeping(directory: str | Path = ".") -> dict:
def format_housekeeping_report(results: dict) -> str:
"""Format housekeeping results for humans and LLMs (SPEC 4.15).
"""Format housekeeping results for humans and LLMs (SPEC 4.8).
Generated by AI/LLM: 2026-09-30 - step blocks, next steps, verdict.
+1 -1
View File
@@ -1,4 +1,4 @@
"""Wiki ingest package (SPEC 7.25).
"""Wiki ingest package (SPEC 7.1.5).
Generated by AI/LLM: 2026-09-30 - stage modules for wiki ingest.
"""
+2 -2
View File
@@ -1,6 +1,6 @@
"""Archive a fetched file under ``raw/``.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.3. Never edits a file already there.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.3. Never edits a file already there.
"""
from __future__ import annotations
@@ -83,7 +83,7 @@ class RawArchiver:
) -> ArchiveResult:
"""Place the source under ``raw/`` or reuse an identical copy.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.3.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.3.
Args:
source: Fetched file.
+1 -1
View File
@@ -13,7 +13,7 @@ from fiona.wiki.ingest.converters.text import TextConverter
def default_registry() -> ConverterRegistry:
"""Return the converters shipped with wiki ingest.
Generated by AI/LLM: 2026-09-30 - registration order from SPEC 7.25.
Generated by AI/LLM: 2026-09-30 - registration order from SPEC 7.1.5.
Returns:
ConverterRegistry: Markdown, text, HTML, and PDF.
+3 -3
View File
@@ -1,6 +1,6 @@
"""Converter base types and the registry.
Generated by AI/LLM: 2026-09-30 - one class per format, SPEC 7.25.1.
Generated by AI/LLM: 2026-09-30 - one class per format, SPEC 7.1.5.1.
"""
from __future__ import annotations
@@ -32,7 +32,7 @@ class ConversionError(Exception):
class SourceConverter(abc.ABC):
"""One format. Subclasses declare what they claim and implement ``convert``.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.1.2.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.1.2.
"""
name: typing.ClassVar[str]
@@ -84,7 +84,7 @@ class ConverterRegistry:
def find(self, media_type: str, extension: str) -> SourceConverter | None:
"""Pick the converter for a media type and extension.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.1 registration order.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.1 registration order.
Args:
media_type: Detected type, or empty.
+2 -2
View File
@@ -22,7 +22,7 @@ _NO_TEXT = "no text content; the page may need JavaScript or a login"
class HtmlConverter(SourceConverter):
"""Convert an HTML document to markdown.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.5.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.5.
"""
name: typing.ClassVar[str] = "html"
@@ -91,7 +91,7 @@ def _absolutize(root: bs4.element.Tag, soup: bs4.BeautifulSoup, origin: str | No
def _html_title(soup: bs4.BeautifulSoup, root: bs4.element.Tag) -> str | None:
"""Return ``<title>``, then ``og:title``, then the first ``<h1>``.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.5.1.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.5.1.
"""
if soup.title and soup.title.string and soup.title.string.strip():
return soup.title.string.strip()
+1 -1
View File
@@ -22,7 +22,7 @@ _FENCE = re.compile(r"^\s*(`{3,}|~{3,})")
class MarkdownConverter(SourceConverter):
"""Keep markdown as it is and record any source frontmatter.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.3.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.3.
The body after a frontmatter block is kept character for character.
The page writer adds the wiki frontmatter when the new page does not
+3 -3
View File
@@ -1,6 +1,6 @@
"""PDF source converter.
Generated by AI/LLM: 2026-09-30 - text layer via pypdf, SPEC 7.25.4.6.
Generated by AI/LLM: 2026-09-30 - text layer via pypdf, SPEC 7.1.5.4.6.
"""
from __future__ import annotations
@@ -20,7 +20,7 @@ _SCANNED = "no text layer; the PDF may be scanned"
class PdfConverter(SourceConverter):
"""Read a PDF text layer into markdown headings and paragraphs.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.6.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.6.
"""
name: typing.ClassVar[str] = "pdf"
@@ -167,7 +167,7 @@ def _walk_outline(
def _render(pages: list[str], outline: list[tuple[int, int, str]]) -> str:
"""Render pages with outline headings or ``## Page n`` headings.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.6.2.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.6.2.
"""
by_page: dict[int, list[str]] = {}
for page_index, level, title in outline:
+1 -1
View File
@@ -15,7 +15,7 @@ from fiona.wiki.ingest.models import ConversionResult, FetchedSource
class TextConverter(SourceConverter):
"""Turn plain text into one fenced markdown block.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.4.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.4.
The page is written at ``status: raw``. The tool does not summarize
the text. The agent rewrites the fence during refinement.
+5 -5
View File
@@ -1,6 +1,6 @@
"""Fetch a local file or an HTTP URL.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.2. No credentials are sent.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.2. No credentials are sent.
"""
from __future__ import annotations
@@ -51,7 +51,7 @@ def url_scheme(argument: str) -> str | None:
class SourceFetcher:
"""Base fetcher. Subclasses accept an argument and return a local file.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.1.3.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.1.3.
"""
settings: IngestSettings | None = None
@@ -111,7 +111,7 @@ class LocalFileFetcher(SourceFetcher):
def fetch(self, argument: str, dest_dir: pathlib.Path) -> FetchedSource:
"""Resolve a local path without copying it.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.2.1.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.2.1.
Args:
argument: Local path as given.
@@ -186,7 +186,7 @@ class UrlFetcher(SourceFetcher):
def fetch(self, argument: str, dest_dir: pathlib.Path) -> FetchedSource:
"""Download a URL into ``dest_dir`` and stop past the size limit.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.2.2 and 7.25.2.3.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.2.2 and 7.1.5.2.3.
Args:
argument: Absolute URL.
@@ -247,7 +247,7 @@ class UrlFetcher(SourceFetcher):
def _without_userinfo(url: str) -> str:
"""Drop userinfo so the request sends no credentials.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.2.2.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.2.2.
"""
parts = urllib.parse.urlsplit(url)
if parts.username is None and parts.password is None:
+1 -1
View File
@@ -1,6 +1,6 @@
"""Append one ingest line to ``wiki/log.md``.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.6. Does not edit ``index.md``.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.6. Does not edit ``index.md``.
"""
from __future__ import annotations
+1 -1
View File
@@ -1,6 +1,6 @@
"""Media-type detection and slug rules for wiki ingest.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.2.4 and 7.25.2.6.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.2.4 and 7.1.5.2.6.
"""
from __future__ import annotations
+4 -4
View File
@@ -12,7 +12,7 @@ import pathlib
class IngestError(Exception):
"""Raised when wiki ingest must stop before a page is written.
Generated by AI/LLM: 2026-09-30 - exit 1 errors from section 4.14.
Generated by AI/LLM: 2026-09-30 - exit 1 errors from section 4.7.6.
"""
def __init__(self, message: str, exit_code: int = 1) -> None:
@@ -20,7 +20,7 @@ class IngestError(Exception):
Args:
message: Text after ``Error: ``.
exit_code: Process status. Section 4.14 uses 1.
exit_code: Process status. Section 4.7.6 uses 1.
"""
super().__init__(message)
self.exit_code = exit_code
@@ -77,7 +77,7 @@ class ArchiveResult:
@dataclasses.dataclass
class IngestResult:
"""One ingest run, including the JSON object from section 4.14.
"""One ingest run, including the JSON object from section 4.7.6.
Generated by AI/LLM: 2026-09-30 - stdout facts for a finished run.
"""
@@ -101,7 +101,7 @@ class IngestResult:
messages: list[str] = dataclasses.field(default_factory=list)
def to_dict(self) -> dict:
"""Return the JSON object from section 4.14.
"""Return the JSON object from section 4.7.6.
Generated by AI/LLM: 2026-09-30 - drop CLI-only fields.
+5 -5
View File
@@ -1,6 +1,6 @@
"""Write one ``status: raw`` wiki page.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.5. The tool never sets ``refined``.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.5. The tool never sets ``refined``.
"""
from __future__ import annotations
@@ -30,7 +30,7 @@ _PROTECTED = {"index.md", "log.md", "schema.md"}
class RawPageWriter:
"""Write the raw page and run the markdown fixer on that file only.
Generated by AI/LLM: 2026-09-30 - frontmatter order from SPEC 7.25.5.3.
Generated by AI/LLM: 2026-09-30 - frontmatter order from SPEC 7.1.5.5.3.
"""
def __init__(self, wiki_root: pathlib.Path) -> None:
@@ -49,7 +49,7 @@ class RawPageWriter:
) -> pathlib.Path:
"""Resolve the page path and reject paths outside ``wiki/``.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.5.1. Does not touch the disk.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.5.1. Does not touch the disk.
Args:
slug: Page stem when ``target`` is a directory or omitted.
@@ -91,7 +91,7 @@ class RawPageWriter:
) -> tuple[str, list[str]]:
"""Write the page, fix it, and return the relative path and warnings.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.5.3 through 7.25.5.5.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.5.3 through 7.1.5.5.5.
Args:
source: Fetch facts stored in ``ingest``.
@@ -307,7 +307,7 @@ def _keeps_target(target: str, page_dir: pathlib.Path) -> bool:
def _fix(page: pathlib.Path, wiki_root: pathlib.Path) -> None:
"""Run the pymarkdown fixer on one page.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.5.5. A fixer error is logged.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.5.5. A fixer error is logged.
"""
try:
doctor = MDoctor(settings_file=wiki_root / "fiona-settings.json")
+8 -8
View File
@@ -1,6 +1,6 @@
"""Run the wiki ingest stages in order.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25. The pipeline holds no format logic.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5. The pipeline holds no format logic.
"""
from __future__ import annotations
@@ -141,7 +141,7 @@ class IngestPipeline:
def list_pending(self) -> list[dict]:
"""List wiki pages whose ``status`` is ``raw``, sorted by path.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.9.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.9.
Returns:
list[dict]: ``page_path``, ``sources``, and ``origin`` for each page.
@@ -319,7 +319,7 @@ def default_pipeline(wiki_root: pathlib.Path) -> IngestPipeline:
def render_stdout(result: IngestResult) -> str:
"""Return the human report, including the dry-run banner.
Generated by AI/LLM: 2026-09-30 - section 4.14 line order.
Generated by AI/LLM: 2026-09-30 - section 4.7.6 line order.
"""
lines: list[str] = []
if result.dry_run:
@@ -329,7 +329,7 @@ def render_stdout(result: IngestResult) -> str:
def add_ingest_arguments(parser: argparse.ArgumentParser) -> None:
"""Add the section 4.14 flags to an ingest parser.
"""Add the section 4.7.6 flags to an ingest parser.
Generated by AI/LLM: 2026-09-30 - the CLI subparser owns these flags, including --help.
@@ -376,7 +376,7 @@ def add_ingest_arguments(parser: argparse.ArgumentParser) -> None:
def ingest_main(argv: list[str] | None = None) -> int:
"""CLI entry for ``fiona-assistant wiki ingest``.
Generated by AI/LLM: 2026-09-30 - section 4.14 exit codes.
Generated by AI/LLM: 2026-09-30 - section 4.7.6 exit codes.
Args:
argv: Arguments after the subcommand. ``None`` reads the process arguments.
@@ -433,7 +433,7 @@ def execute_ingest(args: argparse.Namespace, parser: argparse.ArgumentParser) ->
def _require_wiki(directory: str) -> pathlib.Path:
"""Return the wiki root or raise when settings are missing.
Generated by AI/LLM: 2026-09-30 - section 4.14 directory error.
Generated by AI/LLM: 2026-09-30 - section 4.7.6 directory error.
"""
root = pathlib.Path(directory)
if not (root / "fiona-settings.json").is_file():
@@ -470,7 +470,7 @@ def _fetched_line(source: FetchedSource) -> list[str]:
def _citing_page(wiki_root: pathlib.Path, raw_rel: str, digest: str) -> str | None:
"""Return a page that already cites this raw path or hash.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.3.5. First path in sorted order.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.3.5. First path in sorted order.
"""
wiki = wiki_root / "wiki"
if not wiki.is_dir():
@@ -513,7 +513,7 @@ def _result(
) -> IngestResult:
"""Build an ingest result from the archive and any page that was written.
Generated by AI/LLM: 2026-09-30 - JSON fields from section 4.14.
Generated by AI/LLM: 2026-09-30 - JSON fields from section 4.7.6.
"""
return IngestResult(
source=source.argument,
+10 -10
View File
@@ -1,8 +1,8 @@
"""Wiki sanity module (SPEC 7.3).
"""Wiki sanity module (SPEC 7.1.3).
Runs all validation checks over an llm-wiki directory in one command
and prints an aggregated, AI-friendly report following the same output
structure as run_sanity (SPEC 6.1/7.16.1): each failing check's
structure as run_sanity (SPEC 6.1/7.14.1): each failing check's
linter report first, then a `Results:` table with per-check
PASS/FAIL, violation counts, and (MM:SS) timings, and finally a
`SANITY PASSED (MM:SS)` banner or a `Sanity Failed` verdict.
@@ -10,7 +10,7 @@ PASS/FAIL, violation counts, and (MM:SS) timings, and finally a
The checks live in `sanity_checks()`, a registry of (name, runner)
pairs; each runner returns the run_sanity check-result shape
(`result`, `violation_count`, `stdout`, and the raw `violations`).
Add a new check (e.g. shellcheck once 4.4 ships) by implementing a
Add a new check (e.g. shellcheck once 4.3 ships) by implementing a
runner and appending it to the registry.
"""
@@ -54,7 +54,7 @@ __all__ = [
def _outside_raw(wiki_root: Path, path: str) -> bool:
"""Return whether a reported path is outside the raw archive.
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.12. Sanity checks skip ``raw/``.
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.12. Sanity checks skip ``raw/``.
Args:
wiki_root: Wiki root directory.
@@ -213,7 +213,7 @@ def sanity_checks() -> tuple[tuple[str, Callable[[Path], dict]], ...]:
Modified by AI/LLM: 2026-09-30 - a module-level tuple after the
runners would be a late declaration (SPEC 6.4.3). Append a check
here (for example shellcheck once SPEC 7.12 ships).
here (for example shellcheck once SPEC 7.9 ships).
Returns:
tuple: `(name, runner)` pairs in report order.
@@ -240,7 +240,7 @@ def run_wiki_checks(
Checks run concurrently (one thread each, mirroring run_sanity);
per-check durations are wall-clock times of parallel checks, so
they can overlap and need not sum to the total (SPEC 7.16.1). The
they can overlap and need not sum to the total (SPEC 7.14.1). The
results keep the registry order regardless of completion order.
Args:
@@ -272,7 +272,7 @@ def run_wiki_checks(
)
# Checks run concurrently through the shared SanityRunner engine
# (SPEC 7.16.1); results keep the registry order
# (SPEC 7.14.1); results keep the registry order
runner = sanity_runner.SanityRunner(
checks=[
(name, functools.partial(check, wiki_root))
@@ -295,14 +295,14 @@ def run_wiki_checks(
# =============================================================================
# Report Formatting (shared SanityRunner structure, SPEC 6.1/7.16.1)
# Report Formatting (shared SanityRunner structure, SPEC 6.1/7.14.1)
# =============================================================================
def format_sanity_report(results: dict) -> str:
"""Format the aggregated sanity results for human-readable output.
Mirrors run_sanity through the shared SanityRunner engine
(SPEC 7.16.1): failing checks' linter reports first (clean runs
(SPEC 7.14.1): failing checks' linter reports first (clean runs
print no report), then the `Results:` table, then the pass banner
or the `Sanity Failed` verdict with per-check details.
@@ -352,7 +352,7 @@ def wiki_sanity(
"""Run all sanity checks and print the aggregated report.
Human-readable runs draw the same live per-check progress as
run_sanity (SPEC 7.16.2) through the shared ProgressDisplay: one
run_sanity (SPEC 7.14.2) through the shared ProgressDisplay: one
bar line per check on a terminal, `Running Wiki Sanity ....`
progress dots on an interval when piped or when `non_interactive`
is set. JSON runs skip the display so their output stays parseable.
+28 -30
View File
@@ -7,9 +7,9 @@ and SHA256 hashes for other files (like JSON) that don't have version tagging ye
The module handles:
- Comparing wiki core files against template versions
- Identifying files that need updates
- Special handling for settings files (preserving user customizations)
- Yielding to the owner's markdown: a newer template is written beside
the file as `<stem>-update.md` for the LLM to merge (SPEC 7.2.11)
- Yielding to the owner: a newer markdown file, or a differing
fiona-settings.json, is written beside the file as
`<stem>-update<suffix>` for the LLM to merge (SPEC 7.1.2.11)
- Presenting update summaries to users
"""
@@ -57,10 +57,10 @@ SETTINGS_FILE = "fiona-settings.json"
# Read-only zones that should never be modified
READ_ONLY_ZONES = ["personal/", "raw/"]
# AI/LLM: stem suffix of the file that carries a newer template (SPEC 7.2.11.1)
# AI/LLM: stem suffix of the file that carries a newer template (SPEC 7.1.2.11.1)
UPDATE_SUFFIX = "-update"
# Generated by AI/LLM: 2026-09-30 - short SHA-256 width in the update report (7.2.12)
# Generated by AI/LLM: 2026-09-30 - short SHA-256 width in the update report (7.1.2.12)
SHORT_HASH_LENGTH = 8
__all__ = [
@@ -161,7 +161,7 @@ def get_llm_wiki_source_path() -> Path:
def update_file_path(file_path: Path) -> Path:
"""Return the sibling update file for a core file (SPEC 7.2.11.1).
"""Return the sibling update file for a core file (SPEC 7.1.2.11.1).
Generated by AI/LLM: 2026-09-30 - `AGENTS.md` gives `AGENTS-update.md`.
@@ -279,7 +279,7 @@ def is_version_newer(candidate: str, baseline: str) -> bool:
def template_sha256(template_path: Path) -> str:
"""Hash the text wiki init would write for a template file (SPEC 7.2.12).
"""Hash the text wiki init would write for a template file (SPEC 7.1.2.12).
Generated by AI/LLM: 2026-09-30 - DATE_PLACEHOLDER expanded, endings kept.
@@ -326,14 +326,14 @@ def _content_differs(wiki_file: Path, template_file: Path) -> bool:
def compare_md_file(file_path: Path, template_path: Path) -> FileComparisonResult:
"""Compare a markdown file against its template version using frontmatter.
Classification (SPEC 7.2.1). An existing markdown file is never
Classification (SPEC 7.1.2.1). An existing markdown file is never
overwritten:
- template version newer -> conflict, the template goes to the
`<stem>-update.md` sibling (SPEC 7.2.11)
`<stem>-update.md` sibling (SPEC 7.1.2.11)
- wiki version newer or content diverged at the same version -> locally
modified (skipped and reported by the update run)
- files without version frontmatter compare SHA-256 and are a conflict
when the hashes differ (SPEC 7.2.12)
when the hashes differ (SPEC 7.1.2.12)
Modified by AI/LLM: 2026-09-30 - SHA-256 compare when a version is missing.
@@ -375,7 +375,7 @@ def compare_non_md_file(file_path: Path, template_path: Path) -> FileComparisonR
This is used for files without version tagging (e.g., JSON files).
Modified by AI/LLM: 2026-09-30 - template side hashes init's text (7.2.12).
Modified by AI/LLM: 2026-09-30 - template side hashes init's text (7.1.2.12).
Args:
file_path: Path to the current wiki file.
@@ -396,11 +396,9 @@ def compare_non_md_file(file_path: Path, template_path: Path) -> FileComparisonR
def compare_settings_file(file_path: Path, template_path: Path) -> FileComparisonResult:
"""Compare settings file with special handling to preserve user customizations.
"""Compare settings by hash and yield on a difference (SPEC 7.1.2.3).
The comparison itself is hash-based (the JSON file has no frontmatter
version); the update run applies copy_settings_with_preservation so user
values survive the update.
Modified by AI/LLM: 2026-10-01 - settings drift is a conflict, not a merge.
Args:
file_path: Path to the current settings file.
@@ -411,6 +409,10 @@ def compare_settings_file(file_path: Path, template_path: Path) -> FileCompariso
"""
result = compare_non_md_file(file_path, template_path)
result.is_settings_file = True
if result.needs_update:
result.needs_update = False
result.is_conflict = True
result.update_path = update_file_path(file_path)
return result
@@ -585,7 +587,7 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
wiki_file = wiki_root / relative
if _is_protected(relative, wiki_root, patterns):
continue
# AI/LLM: under wiki/ only an existing markdown page can conflict (SPEC 7.2.9)
# AI/LLM: under wiki/ only an existing markdown page can conflict (SPEC 7.1.2.9)
wiki_page = _is_wiki_page_path(relative)
if wiki_page and (relative.suffix != ".md" or not wiki_file.exists()):
continue
@@ -605,12 +607,12 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
if result.is_conflict:
summary.conflicts.append(result)
if result.is_settings_file:
summary.settings_file = wiki_file
elif wiki_page:
continue
elif result.needs_update:
summary.files_to_update.append(result)
if result.is_settings_file:
summary.settings_file = wiki_file
elif result.is_locally_modified:
summary.files_skipped.append(result)
@@ -622,7 +624,7 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
def _change_detail(result: FileComparisonResult) -> str:
"""Return the ` (current -> template)` detail for one report line.
Generated by AI/LLM: 2026-09-30 - versions, else short SHA-256 (7.2.12.2).
Generated by AI/LLM: 2026-09-30 - versions, else short SHA-256 (7.1.2.12.2).
"""
if result.current_version and result.template_version:
return f" ({result.current_version} -> {result.template_version})"
@@ -712,11 +714,12 @@ def update_core_files(directory: str | Path = ".", force: bool = False, yes: boo
- When neither flag is set, presents list of files and prompts for y/n.
- Never overwrites files in read-only zones.
- Never overwrites an existing markdown file; a conflict writes the
template to its `<stem>-update.md` sibling (SPEC 7.2.11).
- Settings files are updated with user customizations preserved.
template to its `<stem>-update.md` sibling (SPEC 7.1.2.11).
- A differing settings file stays byte-for-byte; the template is
written as `fiona-settings-update.json` (SPEC 7.1.2.3).
- Returns summary of all updated files.
Modified by AI/LLM: 2026-09-30 - write update files for conflicts.
Modified by AI/LLM: 2026-10-01 - settings drift is a conflict.
"""
wiki_root = Path(directory).resolve()
@@ -745,15 +748,10 @@ def update_core_files(directory: str | Path = ".", force: bool = False, yes: boo
for relative in summary.files_to_add:
_copy_file(template_dir / relative, wiki_root / relative)
# Update outdated files; settings get the merge treatment
# Update outdated non-markdown files in place
for result in summary.files_to_update:
relative = result.file_path.relative_to(wiki_root)
if result.is_settings_file:
copy_settings_with_preservation(
result.file_path, template_dir / relative
)
else:
_copy_file(template_dir / relative, result.file_path)
_copy_file(template_dir / relative, result.file_path)
for result in summary.conflicts:
relative = result.file_path.relative_to(wiki_root)
@@ -959,7 +957,7 @@ def update_main(
)
if summary.conflicts:
print(
"Merge each <stem>-update.md into its file: "
"Merge each <stem>-update<suffix> into its file: "
"run fiona-assistant housekeeping."
)
+2 -2
View File
@@ -114,7 +114,7 @@ def _copy_file(source_item: Path, dest_item: Path) -> None:
"""Copy one file, replacing date placeholders in text files.
Modified by AI/LLM: 2026-09-30 - keep the template's line endings, so a
Windows copy hashes the same as the template (SPEC 7.2.5).
Windows copy hashes the same as the template (SPEC 7.1.2.5).
"""
# Read the file content
try:
@@ -161,7 +161,7 @@ def wiki_init(directory: str = ".") -> str:
It also initializes a git repository and makes the initial commit with
all the template files. The personal/ directory is excluded from git via
.gitignore as per SPEC 7.5.
.gitignore as per SPEC 7.12.
Args:
directory: The directory to initialize as an llm-wiki directory.
+3 -3
View File
@@ -1,4 +1,4 @@
"""Tests for bootstrap install modes (SPEC 7.24).
"""Tests for bootstrap install modes (SPEC 7.21).
Generated by AI/LLM: 2026-09-30 - local and no-env install options.
"""
@@ -54,7 +54,7 @@ def _powershell(*args: str) -> subprocess.CompletedProcess[str]:
class TestPipInstallArgs:
"""SPEC 7.24.1 through 7.24.5: pip argument matrix."""
"""SPEC 7.21.1 through 7.21.5: pip argument matrix."""
def test_local_installs_without_editable_mode(self, bootstrap_install):
"""--local installs '.' and does not pass -e or the dev extra."""
@@ -120,7 +120,7 @@ class TestPipInstallArgs:
class TestBootstrapScripts:
"""SPEC 7.24.2 and 7.24.6: both scripts honor the flags."""
"""SPEC 7.21.2 and 7.21.6: both scripts honor the flags."""
def test_both_scripts_call_the_helper(self):
"""Bash and PowerShell pass --local and --no-env to the helper."""
+3 -3
View File
@@ -97,7 +97,7 @@ class TestFionaMain:
def test_main_wiki_ingest_help(self, capsys):
"""Test wiki ingest --help is printed by the ingest parser.
Generated by AI/LLM: 2026-09-30 - SPEC 4.14 help stays on this command.
Generated by AI/LLM: 2026-09-30 - SPEC 4.7.6 help stays on this command.
"""
with (
patch("sys.argv", ["fiona-assistant", "wiki", "ingest", "--help"]),
@@ -234,7 +234,7 @@ class TestFionaMain:
assert exc_info.value.code == 0
captured = capsys.readouterr()
assert "SANITY PASSED" in captured.out
# Non-interactive output carries no ANSI cursor codes (SPEC 7.16.2)
# Non-interactive output carries no ANSI cursor codes (SPEC 7.14.2)
assert "\x1b[" not in captured.out
def test_main_wiki_sanity_passes_non_interactive(self, minimal_wiki):
@@ -470,7 +470,7 @@ class TestFionaMain:
assert "No violations found" in captured.out or "0" in captured.out
class TestFionaLibrarianTocFile:
"""Tests for 'fiona-assistant librarian toc file' dispatch (SPEC 7.15.2)."""
"""Tests for 'fiona-assistant librarian toc file' dispatch (SPEC 7.3.1.2)."""
def test_main_librarian_toc_file_generates_per_file_toc(self, capsys, hermetic_toc_settings):
"""Test that 'librarian toc file <path>' writes a TOC inside the file."""
+17 -10
View File
@@ -1,4 +1,4 @@
"""Tests for fiona-assistant housekeeping (SPEC 4.15, 7.26).
"""Tests for fiona-assistant housekeeping (SPEC 4.8, 7.2).
Generated by AI/LLM: 2026-09-30 - housekeeping routine tests.
"""
@@ -63,7 +63,7 @@ def _hashes(root: Path) -> dict:
class TestRunHousekeeping:
"""Tests for the housekeeping steps (SPEC 7.26)."""
"""Tests for the housekeeping steps (SPEC 7.2)."""
def test_steps_run_in_order(self, hk_wiki):
results = run_housekeeping(hk_wiki)
@@ -78,7 +78,7 @@ class TestRunHousekeeping:
assert {step["status"] for step in results["steps"]} == {"PASS"}
def test_conflict_is_warn_and_writes_nothing(self, hk_wiki):
"""SPEC 7.26.2: check-update reports conflicts without writing."""
"""SPEC 7.2.2: check-update reports conflicts without writing."""
_page(hk_wiki / "AGENTS.md", "agents", "1.0.0", body="See [index](./wiki/index.md).\n")
step = _step(run_housekeeping(hk_wiki), "check-update")
@@ -92,7 +92,7 @@ class TestRunHousekeeping:
assert not (hk_wiki / "AGENTS-update.md").exists()
def test_pending_update_file_fails_merge(self, hk_wiki):
"""SPEC 7.26.3: every *-update.md waits for a merge."""
"""SPEC 7.2.3: every *-update.md waits for a merge."""
_page(hk_wiki / "wiki" / "schema-update.md", "schema", "1.5.0")
_page(hk_wiki / "orphan-update.md", "orphan")
@@ -100,8 +100,15 @@ class TestRunHousekeeping:
assert step["status"] == "FAIL"
assert step["summary"] == "2 update file(s) wait for a merge"
(hk_wiki / "fiona-settings-update.json").write_text("{}\n", encoding="utf-8")
step = _step(run_housekeeping(hk_wiki), "merge")
assert step["status"] == "FAIL"
assert step["summary"] == "3 update file(s) wait for a merge"
assert "wiki/schema-update.md -> wiki/schema.md (target missing)" in step["details"]
assert "orphan-update.md -> orphan.md (target missing)" in step["details"]
assert "fiona-settings-update.json -> fiona-settings.json" in step["details"]
assert any("1.5.0" in action and "wiki/schema-update.md" in action
for action in step["next"])
@@ -128,7 +135,7 @@ class TestRunHousekeeping:
assert step["status"] == "PASS"
def test_raw_page_is_ingest_warn(self, hk_wiki):
"""SPEC 7.26.4: pages at status: raw wait for a refine."""
"""SPEC 7.2.4: pages at status: raw wait for a refine."""
_page(hk_wiki / "wiki" / "sources" / "s.md", "s", extra="status: raw\n",
body="From [index](../index.md).\n")
@@ -139,7 +146,7 @@ class TestRunHousekeeping:
assert step["next"] == ["Refine each raw page, then set status: refined."]
def test_dead_link_fails_sanity(self, hk_wiki):
"""SPEC 7.26.5: a sanity violation is FAIL with the report lines."""
"""SPEC 7.2.5: a sanity violation is FAIL with the report lines."""
_page(hk_wiki / "wiki" / "a.md", "a", body="See [gone](./gone.md).\n")
step = _step(run_housekeeping(hk_wiki), "sanity")
@@ -149,7 +156,7 @@ class TestRunHousekeeping:
assert any("a.md" in line for line in step["details"])
def test_graph_written_and_orphans_warned(self, hk_wiki):
"""SPEC 7.26.6: the graph lands at the wiki root; orphans warn."""
"""SPEC 7.2.6: the graph lands at the wiki root; orphans warn."""
_page(hk_wiki / "wiki" / "lonely.md", "lonely")
_page(hk_wiki / "wiki" / "lonely-update.md", "lonely")
@@ -167,7 +174,7 @@ class TestRunHousekeeping:
assert step["status"] == "FAIL"
def test_every_step_runs_after_a_failure(self, hk_wiki):
"""SPEC 7.26.1: merge and sanity fail, graph still runs."""
"""SPEC 7.2.1: merge and sanity fail, graph still runs."""
_page(hk_wiki / "AGENTS-update.md", "agents", "3.0.0")
_page(hk_wiki / "wiki" / "a.md", "a", body="See [gone](./gone.md).\n")
@@ -179,7 +186,7 @@ class TestRunHousekeeping:
assert results["passed"] is False
def test_only_graph_is_written(self, hk_wiki):
"""SPEC 7.26.7: housekeeping changes nothing but wiki_graph.html."""
"""SPEC 7.2.7: housekeeping changes nothing but wiki_graph.html."""
_page(hk_wiki / "AGENTS.md", "agents", "1.0.0", body="See [index](./wiki/index.md).\n")
before = _hashes(hk_wiki)
@@ -199,7 +206,7 @@ class TestRunHousekeeping:
class TestHousekeepingReport:
"""Tests for the human and JSON output (SPEC 4.15, 7.26.8)."""
"""Tests for the human and JSON output (SPEC 4.8, 7.2.8)."""
def test_human_report_passes(self, hk_wiki):
report = format_housekeeping_report(run_housekeeping(hk_wiki))
+23 -23
View File
@@ -1,4 +1,4 @@
"""Tests for wiki ingest (SPEC 7.25).
"""Tests for wiki ingest (SPEC 7.1.5).
Generated by AI/LLM: 2026-09-30 - acceptance checks for fetch, archive, convert, and write.
"""
@@ -236,7 +236,7 @@ def _hashes(root: pathlib.Path) -> dict[str, str]:
def test_slug_from_console_url() -> None:
"""SPEC 7.25.2.6: the last three segments become one hyphenated slug."""
"""SPEC 7.1.5.2.6: the last three segments become one hyphenated slug."""
assert slug_from_url("https://host/job/performance_TL153/2108/console") == (
"performance-tl153-2108-console"
)
@@ -315,7 +315,7 @@ def test_text_fallback_decode_warns(tmp_path: pathlib.Path) -> None:
def test_register_converter_without_pipeline_edits(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.1.2: a new format is one class and one registration."""
"""SPEC 7.1.5.1.2: a new format is one class and one registration."""
root = _wiki(tmp_path)
sample = tmp_path / "sample.xtest"
sample.write_bytes(b"hello")
@@ -329,7 +329,7 @@ def test_register_converter_without_pipeline_edits(tmp_path: pathlib.Path) -> No
def test_ftp_scheme_writes_nothing(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.2.1: an unsupported scheme exits 1 and writes nothing."""
"""SPEC 7.1.5.2.1: an unsupported scheme exits 1 and writes nothing."""
root = _wiki(tmp_path)
before = _hashes(root)
code, stdout, stderr = _run(root, "ftp://host/a.pdf")
@@ -353,7 +353,7 @@ def test_missing_file_and_directory(tmp_path: pathlib.Path) -> None:
def test_download_uses_content_type_extension(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.2.5: a PDF response with no suffix is saved as ``.pdf``."""
"""SPEC 7.1.5.2.5: a PDF response with no suffix is saved as ``.pdf``."""
root = _wiki(tmp_path)
body = _pdf(["Hello"])
opener = _FakeOpener(body, "application/pdf", final_url="https://host/report")
@@ -369,7 +369,7 @@ def test_download_uses_content_type_extension(tmp_path: pathlib.Path) -> None:
def test_download_404_leaves_ingest_unchanged(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.2.3: a 404 exits 1 and does not add files."""
"""SPEC 7.1.5.2.3: a 404 exits 1 and does not add files."""
root = _wiki(tmp_path)
(root / "ingest" / "keep.txt").write_text("stay", encoding="utf-8")
before = sorted(path.name for path in (root / "ingest").iterdir())
@@ -394,7 +394,7 @@ def test_download_over_limit_is_deleted(tmp_path: pathlib.Path) -> None:
def test_extensionless_pdf_uses_pdf_converter(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.2.4: leading ``%PDF-`` bytes select the pdf converter."""
"""SPEC 7.1.5.2.4: leading ``%PDF-`` bytes select the pdf converter."""
root = _wiki(tmp_path)
source = tmp_path / "notes"
source.write_bytes(_pdf(["Page text"]))
@@ -406,7 +406,7 @@ def test_extensionless_pdf_uses_pdf_converter(tmp_path: pathlib.Path) -> None:
def test_raw_override_and_escape(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.3.2: ``-r`` places the file, and ``..`` exits 1."""
"""SPEC 7.1.5.3.2: ``-r`` places the file, and ``..`` exits 1."""
root = _wiki(tmp_path)
html = tmp_path / "page.html"
html.write_text("<html><body><article><p>Hi</p></article></body></html>", encoding="utf-8")
@@ -424,7 +424,7 @@ def test_raw_override_and_escape(tmp_path: pathlib.Path) -> None:
def test_reuses_identical_bytes(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.3.3: a second name and ``-r`` reuse the first raw copy."""
"""SPEC 7.1.5.3.3: a second name and ``-r`` reuse the first raw copy."""
root = _wiki(tmp_path)
first = tmp_path / "one.txt"
first.write_text("same bytes\n", encoding="utf-8", newline="\n")
@@ -443,7 +443,7 @@ def test_reuses_identical_bytes(tmp_path: pathlib.Path) -> None:
def test_changed_file_gets_a_second_raw_name(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.3.4: a changed file of the same name is stored as ``slug-2``."""
"""SPEC 7.1.5.3.4: a changed file of the same name is stored as ``slug-2``."""
root = _wiki(tmp_path)
source = tmp_path / "notes.txt"
source.write_text("first\n", encoding="utf-8", newline="\n")
@@ -458,7 +458,7 @@ def test_changed_file_gets_a_second_raw_name(tmp_path: pathlib.Path) -> None:
def test_duplicate_exits_zero_and_skips_the_log(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.3.5: the same bytes report the first page and do not rewrite it."""
"""SPEC 7.1.5.3.5: the same bytes report the first page and do not rewrite it."""
root = _wiki(tmp_path)
source = root / "ingest" / "a.txt"
source.write_text("alpha\n", encoding="utf-8", newline="\n")
@@ -480,7 +480,7 @@ def test_duplicate_exits_zero_and_skips_the_log(tmp_path: pathlib.Path) -> None:
def test_ingest_drop_moves_and_personal_is_copied(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.3.6: ``ingest/`` is moved. A file outside it is copied."""
"""SPEC 7.1.5.3.6: ``ingest/`` is moved. A file outside it is copied."""
root = _wiki(tmp_path)
dropped = root / "ingest" / "a.pdf"
dropped.write_bytes(_pdf(["Moved"]))
@@ -499,7 +499,7 @@ def test_ingest_drop_moves_and_personal_is_copied(tmp_path: pathlib.Path) -> Non
def test_unknown_bytes_archive_without_a_page(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.4.1: random bytes exit 3 under ``raw/other``."""
"""SPEC 7.1.5.4.1: random bytes exit 3 under ``raw/other``."""
root = _wiki(tmp_path)
source = tmp_path / "blob.xyz"
source.write_bytes(b"\x00\x01\x02\xff")
@@ -519,7 +519,7 @@ def test_unknown_bytes_archive_without_a_page(tmp_path: pathlib.Path) -> None:
def test_encrypted_pdf_keeps_raw_and_skips_the_page(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.4.2: an encrypted PDF exits 3 and the raw copy stays."""
"""SPEC 7.1.5.4.2: an encrypted PDF exits 3 and the raw copy stays."""
root = _wiki(tmp_path)
source = tmp_path / "secret.pdf"
source.write_bytes(_pdf(["hidden"], password="secret"))
@@ -532,7 +532,7 @@ def test_encrypted_pdf_keeps_raw_and_skips_the_page(tmp_path: pathlib.Path) -> N
def test_html_keeps_article_link_and_table(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.4.5: article text, no script, an absolute link, and a pipe table."""
"""SPEC 7.1.5.4.5: article text, no script, an absolute link, and a pipe table."""
root = _wiki(tmp_path)
html = """<!doctype html>
<html lang="en"><head><title>Page Title</title></head>
@@ -559,7 +559,7 @@ def test_html_keeps_article_link_and_table(tmp_path: pathlib.Path) -> None:
def test_pdf_page_headings_and_blank_page(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.4.6: pages are numbered, and a blank page is partial."""
"""SPEC 7.1.5.4.6: pages are numbered, and a blank page is partial."""
root = _wiki(tmp_path)
numbered = tmp_path / "two.pdf"
numbered.write_bytes(_pdf(["Alpha", "Beta"]))
@@ -578,7 +578,7 @@ def test_pdf_page_headings_and_blank_page(tmp_path: pathlib.Path) -> None:
def test_target_paths(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.5.1: ``-t concepts`` writes under concepts. Escapes exit 1."""
"""SPEC 7.1.5.5.1: ``-t concepts`` writes under concepts. Escapes exit 1."""
root = _wiki(tmp_path)
source = tmp_path / "idea.txt"
source.write_text("idea\n", encoding="utf-8", newline="\n")
@@ -597,7 +597,7 @@ def test_target_paths(tmp_path: pathlib.Path) -> None:
def test_existing_page_refuses_until_force(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.5.2: a second run exits 1. ``--force`` replaces the page."""
"""SPEC 7.1.5.5.2: a second run exits 1. ``--force`` replaces the page."""
root = _wiki(tmp_path)
source = tmp_path / "item.txt"
source.write_text("one\n", encoding="utf-8", newline="\n")
@@ -620,7 +620,7 @@ def test_existing_page_refuses_until_force(tmp_path: pathlib.Path) -> None:
def test_page_frontmatter_matches_raw_hash(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.5.3 and 7.25.5.4: frontmatter is complete and the page has one H1."""
"""SPEC 7.1.5.5.3 and 7.1.5.5.4: frontmatter is complete and the page has one H1."""
root = _wiki(tmp_path)
index_before = (root / "wiki" / "index.md").read_bytes()
source = tmp_path / "story.md"
@@ -653,7 +653,7 @@ def test_page_frontmatter_matches_raw_hash(tmp_path: pathlib.Path) -> None:
def test_style_violations_become_one_warning(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.5.5: violations the fixer leaves are counted in one warning."""
"""SPEC 7.1.5.5.5: violations the fixer leaves are counted in one warning."""
root = _wiki(tmp_path)
source = tmp_path / "long.md"
source.write_text("# Title\n\n" + ("word " * 40) + "\n", encoding="utf-8", newline="\n")
@@ -664,7 +664,7 @@ def test_style_violations_become_one_warning(tmp_path: pathlib.Path) -> None:
def test_raw_only_and_dry_run(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.7 and 7.25.8: raw-only skips the page. A dry run writes nothing."""
"""SPEC 7.1.5.7 and 7.1.5.8: raw-only skips the page. A dry run writes nothing."""
root = _wiki(tmp_path)
source = root / "ingest" / "only.txt"
source.write_text("archive me\n", encoding="utf-8", newline="\n")
@@ -688,7 +688,7 @@ def test_raw_only_and_dry_run(tmp_path: pathlib.Path) -> None:
def test_pending_hides_refined_pages(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.9: ``--pending`` lists raw pages and drops refined ones."""
"""SPEC 7.1.5.9: ``--pending`` lists raw pages and drops refined ones."""
root = _wiki(tmp_path)
source = tmp_path / "open.txt"
source.write_text("open\n", encoding="utf-8", newline="\n")
@@ -716,7 +716,7 @@ def test_not_a_wiki_and_mutually_exclusive_args(tmp_path: pathlib.Path) -> None:
def test_sanity_ignores_raw_markdown(tmp_path: pathlib.Path) -> None:
"""SPEC 7.25.12: a raw markdown file with style violations does not fail sanity."""
"""SPEC 7.1.5.12: a raw markdown file with style violations does not fail sanity."""
root = _wiki(tmp_path)
raw = root / "raw" / "articles"
raw.mkdir(parents=True)
+1 -1
View File
@@ -1,6 +1,6 @@
"""Branch coverage for wiki ingest stages.
Generated by AI/LLM: 2026-09-30 - error paths and converter edges from SPEC 7.25.
Generated by AI/LLM: 2026-09-30 - error paths and converter edges from SPEC 7.1.5.
"""
from __future__ import annotations
+1 -1
View File
@@ -1,4 +1,4 @@
"""Tests for the shared logging configuration (SPEC 7.20)."""
"""Tests for the shared logging configuration (SPEC 7.17)."""
import logging
import re
+2 -2
View File
@@ -1212,7 +1212,7 @@ class TestProgressDisplayNonInteractive:
interval_seconds=3.0, expected_seconds=30.0, clock=clock,
)
display.progress("lint1", {"result": 0, "duration_seconds": 7.5})
display.progress("lint1", {"result": 0, "duration_seconds": 7.12})
display.heartbeat(["lint2"])
# The dot comes from the interval tick, not from the finished
@@ -1284,7 +1284,7 @@ class TestProgressDisplayInteractive:
)
display.heartbeat(["lint1", "lint2"])
display.progress("lint2", {"result": 0, "duration_seconds": 7.5})
display.progress("lint2", {"result": 0, "duration_seconds": 7.12})
out = stream.getvalue()
assert "lint2 " + "[" + "#" * 15 + "] 100% done (00:07)" in out
+6 -6
View File
@@ -1,8 +1,8 @@
"""Tests for the sanity_manager module (SPEC 7.3).
"""Tests for the sanity_manager module (SPEC 7.1.3).
Covers the aggregated wiki sanity report (markdownlint, python-ruff,
mdlinter) with its modular check registry and the run_sanity-style
output structure (SPEC 6.1/7.16.1).
output structure (SPEC 6.1/7.14.1).
"""
from __future__ import annotations
@@ -140,7 +140,7 @@ class TestRunWikiChecks:
# =============================================================================
# Report Format Tests (run_sanity structure, SPEC 6.1/7.16.1)
# Report Format Tests (run_sanity structure, SPEC 6.1/7.14.1)
# =============================================================================
class TestWikiSanityReport:
@@ -158,7 +158,7 @@ class TestWikiSanityReport:
assert "SANITY PASSED" in output
# Clean runs print no linter reports (SPEC 6.1)
assert "Violations\n" not in output
# Every summary line carries an (MM:SS) timing suffix (SPEC 7.16.1)
# Every summary line carries an (MM:SS) timing suffix (SPEC 7.14.1)
assert re.search(
r"mdlinter:\s+PASS - 0 violations \(\d{2}:\d{2}\)", output
)
@@ -304,11 +304,11 @@ class TestSanityMain:
# =============================================================================
# Progress Display Tests (SPEC 7.16.2)
# Progress Display Tests (SPEC 7.14.2)
# =============================================================================
class TestWikiSanityProgress:
"""Tests for the in-run progress display wiring (SPEC 7.16.2)."""
"""Tests for the in-run progress display wiring (SPEC 7.14.2)."""
@pytest.fixture
def fake_display_class(self, monkeypatch):
+1 -1
View File
@@ -1,4 +1,4 @@
"""Tests for the shared SanityRunner engine (SPEC 7.16.1).
"""Tests for the shared SanityRunner engine (SPEC 7.14.1).
Covers the generalized class behind both the repository sanity runner
(run_sanity) and the wiki sanity command (wiki.sanity_manager):
+3 -3
View File
@@ -770,7 +770,7 @@ class TestMainSettings:
# =============================================================================
# Test: per-file TOC generation (SPEC 7.15.2)
# Test: per-file TOC generation (SPEC 7.3.1.2)
# =============================================================================
SAMPLE_DOC = """# Guide
@@ -1345,7 +1345,7 @@ class TestPackagedFileTocSettings:
class TestFolderTocValidation:
"""Tests for folder-TOC target validation and reporting (SPEC 7.15.1)."""
"""Tests for folder-TOC target validation and reporting (SPEC 7.3.1.1)."""
def test_main_file_target_exits_with_error(self, tmp_path, capsys):
"""Should exit 1 with a hint when the target is a file, not a dir.
@@ -1543,7 +1543,7 @@ class TestTocMarker:
def test_config_change_updates_marker(self, tmp_path):
"""Should keep the marker range when the settings range changes.
The marker params have priority over the settings (SPEC 7.15.2),
The marker params have priority over the settings (SPEC 7.3.1.2),
so a settings change alone leaves an existing TOC unchanged.
"""
doc = tmp_path / "doc.md"
+27 -22
View File
@@ -429,7 +429,7 @@ class TestCheckWikiUpdates:
assert isinstance(summary, UpdateSummary)
def test_real_init_is_up_to_date(self, pristine_wiki):
"""Test a real wiki init reports nothing to update on any OS (SPEC 7.2.5).
"""Test a real wiki init reports nothing to update on any OS (SPEC 7.1.2.5).
Generated by AI/LLM: 2026-09-30 - init must keep template line endings.
"""
@@ -692,7 +692,7 @@ class TestConstants:
# =============================================================================
# Implementation Tests (SPEC 7.2)
# Implementation Tests (SPEC 7.1.2)
# =============================================================================
def _write_md(path: Path, version: str, body: str = "# Doc\n", name: str = "doc"):
@@ -780,7 +780,7 @@ class TestCompareMdFileVersions:
assert result.template_version == "1.0.0"
def test_newer_template_is_conflict(self, tmp_path):
"""Test a newer template is a conflict, never an overwrite (SPEC 7.2.1.1)."""
"""Test a newer template is a conflict, never an overwrite (SPEC 7.1.2.1.1)."""
wiki_file = tmp_path / "file.md"
template_file = tmp_path / "template.md"
_write_md(wiki_file, "1.0.0", body="# Old\n")
@@ -880,7 +880,9 @@ class TestCompareSettingsFileHashes:
result = compare_settings_file(wiki_file, template_file)
assert result.needs_update is True
assert result.needs_update is False
assert result.is_conflict is True
assert result.update_path == wiki_file.with_name("fiona-settings-update.json")
class TestGetAllTemplateFilesImplemented:
@@ -1024,7 +1026,7 @@ class TestCheckWikiUpdatesImplemented:
assert not (wiki / "AGENTS-update.md").exists()
def test_wiki_page_older_than_template_is_conflict(self, template_wiki_pair):
"""Test an older wiki/ template page is a conflict (SPEC 7.2.9)."""
"""Test an older wiki/ template page is a conflict (SPEC 7.1.2.9)."""
_template, wiki = template_wiki_pair
_write_md(wiki / "wiki" / "index.md", "0.1.0", body="# User index\n", name="index")
@@ -1035,7 +1037,7 @@ class TestCheckWikiUpdatesImplemented:
]
def test_conflict_clears_at_template_version(self, template_wiki_pair):
"""Test a merged file at the template version is no conflict (SPEC 7.2.11.4)."""
"""Test a merged file at the template version is no conflict (SPEC 7.1.2.11.4)."""
_template, wiki = template_wiki_pair
_write_md(wiki / "AGENTS.md", "2.0.0", body="# Merged agents\n", name="agents")
@@ -1100,9 +1102,11 @@ class TestCheckWikiUpdatesImplemented:
assert summary.settings_file == (wiki / "fiona-settings.json").resolve()
settings_results = [
r for r in summary.files_to_update if r.is_settings_file
r for r in summary.conflicts if r.is_settings_file
]
assert len(settings_results) == 1
assert settings_results[0].update_path.name == "fiona-settings-update.json"
assert not any(r.is_settings_file for r in summary.files_to_update)
def test_user_created_file_not_flagged(self, template_wiki_pair):
_template, wiki = template_wiki_pair
@@ -1185,7 +1189,7 @@ class TestUpdateCoreFilesImplemented:
"""Tests for performing the actual update."""
def test_yes_keeps_outdated_file_and_writes_update_file(self, template_wiki_pair):
"""Test update yields to the owner and writes AGENTS-update.md (SPEC 7.2.6)."""
"""Test update yields to the owner and writes AGENTS-update.md (SPEC 7.1.2.6)."""
_template, wiki = template_wiki_pair
owner = "---\nname: agents\nversion: 1.0.0\n---\n# Agents v1\n"
(wiki / "AGENTS.md").write_text(owner, encoding="utf-8")
@@ -1200,7 +1204,7 @@ class TestUpdateCoreFilesImplemented:
assert summary.files_to_update == []
def test_update_file_expands_date_placeholder(self, template_wiki_pair):
"""Test the update file holds the expanded template (SPEC 7.2.11.2)."""
"""Test the update file holds the expanded template (SPEC 7.1.2.11.2)."""
template, wiki = template_wiki_pair
_write_md(
template / "README.md", "2.0.0",
@@ -1216,7 +1220,7 @@ class TestUpdateCoreFilesImplemented:
assert sorted(p.name for p in wiki.glob("*-update.md")) == ["README-update.md"]
def test_dry_run_writes_no_update_file(self, template_wiki_pair):
"""Test --dry-run lists the conflict and writes nothing (SPEC 7.2.11.3)."""
"""Test --dry-run lists the conflict and writes nothing (SPEC 7.1.2.11.3)."""
_template, wiki = template_wiki_pair
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
@@ -1225,7 +1229,7 @@ class TestUpdateCoreFilesImplemented:
assert list(wiki.rglob("*-update.md")) == []
def test_wiki_schema_conflict_writes_only_its_update_file(self, template_wiki_pair):
"""Test a wiki/ conflict writes one sibling update file (SPEC 7.2.11.1)."""
"""Test a wiki/ conflict writes one sibling update file (SPEC 7.1.2.11.1)."""
template, wiki = template_wiki_pair
_write_md(template / "wiki" / "schema.md", "1.5.0", body="# Schema\n", name="schema")
owner = "---\nname: schema\nversion: 1.4.0\n---\n# My tags\n"
@@ -1307,17 +1311,18 @@ class TestUpdateCoreFilesImplemented:
user_content
)
def test_settings_merge_preserves_user_values(self, template_wiki_pair):
_template, wiki = template_wiki_pair
(wiki / "fiona-settings.json").write_text(
json.dumps({"a": 1, "user_key": "custom"}), encoding="utf-8"
)
def test_settings_conflict_keeps_owner_and_writes_update(self, template_wiki_pair):
"""SPEC 7.1.2.3: a drifted settings file is a conflict, not a merge."""
template, wiki = template_wiki_pair
owner = json.dumps({"a": 1, "user_key": "custom"})
(wiki / "fiona-settings.json").write_text(owner, encoding="utf-8")
update_core_files(str(wiki), yes=True)
merged = json.loads((wiki / "fiona-settings.json").read_text(encoding="utf-8"))
assert merged["user_key"] == "custom"
assert merged["a"] == 1
assert (wiki / "fiona-settings.json").read_text(encoding="utf-8") == owner
assert (wiki / "fiona-settings-update.json").read_text(encoding="utf-8") == (
(template / "fiona-settings.json").read_text(encoding="utf-8")
)
def test_requires_confirmation_without_flags(self, template_wiki_pair):
_template, wiki = template_wiki_pair
@@ -1481,7 +1486,7 @@ class TestFormatCheckUpdateOutputSkipped:
# =============================================================================
# SHA-256 comparison for files without a version (SPEC 7.2.12)
# SHA-256 comparison for files without a version (SPEC 7.1.2.12)
# Generated by AI/LLM: 2026-09-30 - hash compare and short-hash report.
# =============================================================================
@@ -1497,7 +1502,7 @@ class TestSha256Comparison:
"""Tests for hash comparison of files without a version."""
def test_date_placeholder_template_matches_init_copy(self, tmp_path):
"""A template with DATE_PLACEHOLDER matches its init copy (SPEC 7.2.12.1)."""
"""A template with DATE_PLACEHOLDER matches its init copy (SPEC 7.1.2.12.1)."""
template_file = tmp_path / "template.py"
wiki_file = tmp_path / "example.py"
template_file.write_text("# created DATE_PLACEHOLDER\n", encoding="utf-8", newline="\n")
@@ -1556,7 +1561,7 @@ class TestSha256Comparison:
class TestSha256Report:
"""Tests for the short-hash detail in the update report (SPEC 7.2.12.2)."""
"""Tests for the short-hash detail in the update report (SPEC 7.1.2.12.2)."""
def test_update_line_shows_short_hashes(self):
result = FileComparisonResult(
+42 -42
View File
@@ -66,7 +66,7 @@ the docs contradict the code.
- [x] Remove `src/llm-wiki/utils/scripts/example.py` — won't do:
`wiki init` no longer skips `.py` files (it now makes a 1:1 copy of
the template, so `example.py` ships to user wikis; user decision,
2026-09-27; SPEC 7.1, version 0.30.0)
2026-09-27; SPEC 7.1.1, version 0.30.0)
- [x] Deduplicate conftest: `src/conftest.py` vs `src/tests/conftest.py`
- [x] Consolidated into `src/tests/conftest.py` (sys.path bootstrap
moved there, outer file removed, 2026-09-27); verified
@@ -80,7 +80,7 @@ the docs contradict the code.
- [x] markdownlint should show which files are in violation , what line
- [x] same thing for ruff
- [x] Remove the phantom `html_js_lint` package and `html-js-lint` console
script from `pyproject.toml` until SPEC 7.17 is implemented. The
script from `pyproject.toml` until SPEC 7.15 is implemented. The
directory `src/html_js_lint/` does not exist. Detail is item 2 in
the 2026-09-29 audit below
@@ -138,11 +138,11 @@ Half-moving a package leaves both layouts on `sys.path`.
- [x] `src/fiona_assistant.egg-info/entry_points.txt` still has that
script from the last editable install
- [x] `src/html_js_lint/` does not exist. Invoking `html-js-lint`
fails at import. SPEC 7.17 is the future feature; the entry
fails at import. SPEC 7.15 is the future feature; the entry
point should not ship until that directory exists
- [x] `html5validator` is in runtime `dependencies` and is not
imported anywhere under `src/`. Drop it with the phantom
script, or keep it only when SPEC 7.17 lands
script, or keep it only when SPEC 7.15 lands
- [x] Delete `src/__init__.py`
- [x] The file's only content is the comment `# Fiona tools package`
- [x] An `__init__.py` in `src/` makes `src` itself a package whenever
@@ -305,23 +305,23 @@ items below are done. The command defects after them are still open.
- [x] `run_tests.py` and `run_sanity.py` already sit in
`src/fiona/`. Give them entry points or document
`python -m fiona.run_tests` / `python -m fiona.run_sanity`
in place of `python src/run_tests.py` (SPEC 4.13).
in place of `python src/run_tests.py` (SPEC 4.9).
### Fixes in commands the spec already calls Implemented
- [ ] `json-lint fix` walks the file list twice (SPEC appendix,
SPEC 4.6). The second `fix_file` pass finds the files already
SPEC 4.5). The second `fix_file` pass finds the files already
clean, so the path lines never print. Walk once: one count and
one path line per fixed file.
- [ ] `json-lint chklint --fix` is parsed and ignored
(`src/fiona/customlinter/jsonlint.py`). SPEC 4.6 says
(`src/fiona/customlinter/jsonlint.py`). SPEC 4.5 says
`chklint --fix` rewrites the same way `fix` does.
- [ ] `json-lint fix` treats any path part named `personal` or `raw`
as a read-only zone, including a folder outside the wiki.
Skip with the wiki-relative check in `BaseLinter`
(`src/fiona/customlinter/base.py`), the same rule as `chklint`.
- [ ] `git` failures print `Error:` on stdout and catch `Exception`
(`src/fiona/gittool/git_tool.py`). SPEC 4.7 and section 2: the
(`src/fiona/gittool/git_tool.py`). SPEC 4.6 and section 2: the
message goes to stderr. Catch the errors `GitTool` raises.
This is the concrete case of the P2 logging item.
- [ ] `wiki graph` prints `Error: Directory not found` on stdout
@@ -332,13 +332,13 @@ items below are done. The command defects after them are still open.
`--external-links` with `fiona.wiki.graph` settings after the
CLI has set them (`load_graph_settings` in
`wiki_graph_main`). An explicit flag wins. Settings fill the
defaults only (SPEC 4.12).
defaults only (SPEC 4.7.5).
- [ ] `wiki graph` drops files above `max_files` with a log line
only. Print the kept count and the limit on stderr.
- [ ] `mdoctor fix` rewrites `personal/` and `raw/` (SPEC 4.3,
- [ ] `mdoctor fix` rewrites `personal/` and `raw/` (SPEC 4.2,
appendix). Constraint 1.2.3 says those zones are read-only for
every automated tool. Skip them in `fix_file_programmatically`,
then change SPEC 4.3 to say the command skips those zones.
then change SPEC 4.2 to say the command skips those zones.
- [ ] `graph_generator.py` logs with f-strings. Use lazy `%`
formatting, the same style as `logging_config.py`.
- [ ] `fiona-assistant python-ruff` has an empty help string and a
@@ -350,10 +350,10 @@ items below are done. The command defects after them are still open.
## P1 — Wiki Lifecycle and Version Control
- [x] `wiki init` hardening (SPEC 7.1)
- [x] `wiki init` hardening (SPEC 7.1.1)
- [x] Warn or refuse when the target is already an llm-wiki directory
- [x] Do not clobber user content on re-run (idempotent)
- [x] `fiona-assistant wiki update` (SPEC 7.2)
- [x] `fiona-assistant wiki update` (SPEC 7.1.2)
- [x] Create `src/wiki/update_manager.py` with stub functions
- [x] Add CLI commands: `wiki check-update` and `wiki update`
- [x] Add comprehensive test suite (48 tests)
@@ -361,10 +361,10 @@ items below are done. The command defects after them are still open.
(compare `version` frontmatter)
- [x] Update directory structure when the template changed
- [x] Skip locally-modified files and report them
- [x] `fiona-assistant wiki sanity` (SPEC 7.3)
- [x] `fiona-assistant wiki sanity` (SPEC 7.1.3)
- [x] Run all linters: mdlint, python-ruff, shellcheck (once P2 lands)
- [x] Dead-link check (relative and wiki-internal links)
- [x] Git version control for llm-wiki (SPEC 7.5)
- [x] Git version control for llm-wiki (SPEC 7.12)
- [x] GitPython library wrapper
- [x] Basic operations:
- [x] `save` — commit current edits with
@@ -380,13 +380,13 @@ items below are done. The command defects after them are still open.
- [x] Restore the run_sanity progress heartbeat (`[WAITING]`
lines while checks run) on top of the shared SanityRunner engine
(SPEC 7.16.1); dropped when the engine was generalized
(SPEC 7.14.1); dropped when the engine was generalized
- [x] `SanityRunner.run_all` takes optional `progress` and
`heartbeat` callbacks; check lifecycle logged at INFO
- [x] run_sanity passes stdout callbacks (DONE markers and
WAITING lines, assigned via a carriage-return constant); wiki
sanity output unchanged
- [x] Frontmatter linter (fmlint) (SPEC 7.8)
- [x] Frontmatter linter (fmlint) (SPEC 7.5)
- [x] Implement `src/customlinter/fmlint.py`
- [x] Write TDD tests for fmlint
- [x] Add CLI integration: `fiona-assistant fmlint chklint [directory]`
@@ -405,8 +405,8 @@ items below are done. The command defects after them are still open.
- [x] Migrate `python_ruff` (different compressed shape:
`dict[rel_path, list[dict]]`) onto the shared base format
- [x] Keep all linter reports diffable: same sections, same order
(update SPEC 7.7/7.11 and tests together)
- [x] JSON linter (json-lint) (SPEC 7.18)
(update SPEC 7.4/7.8 and tests together)
- [x] JSON linter (json-lint) (SPEC 7.11)
- [x] Implement `src/customlinter/jsonlint.py`
- [x] Write TDD tests for json-lint
- [x] JSON syntax validation using the standard `json` module
@@ -414,13 +414,13 @@ items below are done. The command defects after them are still open.
- [x] CLI: `fiona-assistant json-lint chklint` and `fix`
- [x] Settings via the `json` section of `fiona-settings.json`
- [x] Integrated into `run_sanity.py` and `wiki sanity`
- [ ] Shellcheck library (SPEC 7.12)
- [ ] Shellcheck library (SPEC 7.9)
- [ ] add shellcheck to toml
- [ ] Wrap shellcheck like `python_ruff` (AI-friendly violation report)
- [ ] Clear install-hint error when shellcheck is missing
- [ ] Lint fenced code blocks inside MD files (SPEC 7.13)
- [ ] Lint fenced code blocks inside MD files (SPEC 7.10)
- [ ] Python blocks via Ruff, shell blocks via shellcheck
- [ ] Logging library instead of `print` for diagnostics (SPEC 7.20)
- [ ] Logging library instead of `print` for diagnostics (SPEC 7.17)
- [x] Shared `fiona.logging_config.setup_logging()` on CLI entry points
- [ ] Error and warning diagnostics go to stderr through logging.
CLI reports stay stdout prints. `git_tool`, `graph_generator`,
@@ -445,7 +445,7 @@ items below are done. The command defects after them are still open.
`front-matter` extension (files with frontmatter no longer raise
phantom MD003/MD022/MD041) and ignores the frontmatter `title`
for MD025
- [ ] Settings manager, `fiona-assistant setup` (SPEC 7.19)
- [ ] Settings manager, `fiona-assistant setup` (SPEC 7.16)
- [x] When running sanity, make sure that markdownlint tests also include
outer dir of the src/ because there are markdown files there
- [x] in `run_sanity.py`, show the failing test function and assert ex.
@@ -598,7 +598,7 @@ WARNING run_tests: pytest short summary missing from output; failure details com
omitted when the scan root is outside the working
directory, because the matcher rejects those paths. The
post-scan directory check still drops ignored files.
SPEC 7.7.3
SPEC 7.4.3
- [x] Make the pristine and minimal wiki fixtures cheaper. Use a
wiki that is not a git repo, or turn off
`respect_gitignore` in the fixture's settings. The scan
@@ -637,13 +637,13 @@ WARNING run_tests: pytest short summary missing from output; failure details com
- [x] Side finding, not a speed issue: `run_tests.py` joins
`PYTHONPATH` with `":"` (`f"{src_dir}:{current_pythonpath}"`).
On Windows the separator is `;`. Use `os.pathsep`. Done.
SPEC 4.13
SPEC 4.9
- [x] in toc generator settings, per-file glob overrides in the `file`
section (SPEC 7.15.2)
section (SPEC 7.3.1.2)
- [ ] instead of current directory as default, find a fiona-settings.json
in the current directory / subdirectory, that will be the llm-wiki
root and default directory for commands (SPEC 7.23)
root and default directory for commands (SPEC 7.20)
- [ ] Enable the pymarkdown `markdown-tables` extension in
`fiona-settings.json` so table rules (MD055/MD056/MD058) run in
`run_sanity.py` (SPEC 5.1 known limitation)
@@ -655,13 +655,13 @@ WARNING run_tests: pytest short summary missing from output; failure details com
## P3 — Metadata, Backup, and Documentation
- [ ] Backup script for llm-wiki so users can recover if something goes
wrong (SPEC 7.6)
wrong (SPEC 7.13)
- [ ] Frontmatter tags on MD files (SPEC 6.2)
- [x] `version`
- [ ] `date` tag
- [ ] Quality signal: `confidence`
- [ ] `contested` flag (true if claims are disputed)
- [ ] Project documentation (SPEC 7.21)
- [ ] Project documentation (SPEC 7.18)
- [x] Root `README.md` links `SPEC.md`
- [x] Root README and `AGENTS.md` document `bootstrap` and `bootstrap.ps1`
- [ ] Refresh `librarian/README.md` and `mdoctor/README.md` for the
@@ -672,17 +672,17 @@ WARNING run_tests: pytest short summary missing from output; failure details com
including the root README link to `./llm-wiki/AGENTS.md`
- [ ] Process hygiene: use semantic commit prefixes
(`feat:`, `fix:`, `docs:`, ...) per project agent rule 8.1
- [x] `fiona-assistant wiki graph` (SPEC 7.4): link parser, graph,
- [x] `fiona-assistant wiki graph` (SPEC 7.1.4): link parser, graph,
HTML template, and CLI in `src/wiki/graph_generator.py`
- [ ] Draw only important graph nodes until a parent is clicked
(SPEC 7.4.16)
(SPEC 7.1.4.16)
- [ ] Setting `fiona.wiki.graph.node_importance_min_point`
- [ ] `0`, or a missing key, draws every node
- [ ] A positive integer hides a node whose `unique_points` is
below that integer until one of its parents is clicked
- [ ] Omit gitignored markdown from the wiki graph (SPEC 7.4.17)
- [ ] Omit gitignored markdown from the wiki graph (SPEC 7.1.4.17)
- [ ] Failing tests in `tests/test_graph_generator.py` for the
acceptances in SPEC 7.4.17, 7.4.17.1, and 7.4.17.2:
acceptances in SPEC 7.1.4.17, 7.1.4.17.1, and 7.1.4.17.2:
`secret.md` absent from JSON nodes, edges, and orphans;
a link to it creates no edge; `max_files` 1 still keeps
`kept.md`; `drafts/` omits `drafts/note.md` and keeps
@@ -693,7 +693,7 @@ WARNING run_tests: pytest short summary missing from output; failure details com
drop a match before the `max_files` cut. Read patterns with
`gitignore_patterns_from_text` and test them with
`path_is_ignored` (`src/fiona/wiki/ignore.py`), the same
rules as SPEC 7.2.10. The scan-root `.gitignore` applies to
rules as SPEC 7.1.2.10. The scan-root `.gitignore` applies to
the whole tree. A subdirectory `.gitignore` applies only
under that subdirectory. Also drop any path under `.git/`
- [ ] Do not parse an omitted file. Drop an edge whose target
@@ -702,18 +702,18 @@ WARNING run_tests: pytest short summary missing from output; failure details com
always runs
- [ ] Housekeeping's orphan list follows automatically, because
`graph_step` builds the graph through `wiki_graph_main`
(SPEC 7.26.6)
- [ ] in spec, refine the sectioning by compiling the modules,
(SPEC 7.2.6)
- [x] in spec, refine the sectioning by compiling the modules,
and their functions as subsections
- [ ] eg 4.1. librarian then 4.1.1 librarian toc, to make it cleaner
- [x] eg 4.1. librarian then 4.1.1 librarian toc, to make it cleaner
## P4 — Design Decisions Needed
- [ ] Librarian: version tracking for non-MD files (SPEC 7.14)
- [ ] Librarian: version tracking for non-MD files (SPEC 7.3.2)
- [ ] Python files — format TBD
- [ ] Bash scripts — format TBD
- [ ] Decide the tagging format before implementing
- [ ] Define LLM wiki tool roles (SPEC 7.22)
- [ ] Define LLM wiki tool roles (SPEC 7.19)
- [ ] Document purpose of `src/` tools
- [ ] Classify tools by role:
- [ ] Ingestion: moving files from `ingest/` to `raw/`
@@ -722,8 +722,8 @@ WARNING run_tests: pytest short summary missing from output; failure details com
## Open Questions (SPEC)
- Tagging format for python files and bash scripts (SPEC 7.14)
- Git wrapper location: implemented at `src/gittool/git_tool.py` (SPEC 7.5)
- Wiki root discovery (SPEC 7.23): the nearest `fiona-settings.json`
- Tagging format for python files and bash scripts (SPEC 7.3.2)
- Git wrapper location: implemented at `src/gittool/git_tool.py` (SPEC 7.12)
- Wiki root discovery (SPEC 7.20): the nearest `fiona-settings.json`
wins; error when two at the same depth are equally near. Ancestor
search is still open.