housekeeping and fiona skill overhaul

This commit is contained in:
nvaldez
2026-09-30 21:19:47 +02:00
parent 94d3554d77
commit da01b3fe4a
21 changed files with 2556 additions and 309 deletions
+23 -4
View File
@@ -1,7 +1,7 @@
---
name: Fiona-Assistant Agent Rules
version: 1.7.0
title: LLM Agent Rules
name: Fiona-Assistant Development Agent Rules
version: 1.9.1
title: Agents
type: summary
created: 2025-09-23
updated: 2026-09-30
@@ -9,7 +9,7 @@ tags: [agents, rules, guidelines, llm, ai]
sources: []
---
# Fiona-Assistant LLM Agent Rules
# Agents
- [1. Overview](#1-overview)
- [1.1 Rule References](#11-rule-references)
@@ -128,6 +128,9 @@ bumps versions (step 5). It skips the test and implementation steps.
### 2.4 Commit
- *NEVER* commit without explicit permission!
- This rule covers this repository only. A deployed wiki commits
after each ingest cycle and housekeeping pass
([SPEC](./SPEC.md) 3.3.3).
---
@@ -419,6 +422,22 @@ llm:
- reasoning: high # when the model reports a level
contested: true
contradictions: [other-page-slug]
# written by wiki ingest (SPEC 7.25), optional:
status: raw | refined
source_meta: {author: Name} # metadata read from the source
ingest: # provenance; every key always present
origin: https://host/path # URL or file path of the source
origin_kind: url | file
final_url: null # URL after redirects
fetched: YYYY-MM-DDTHH:MM:SSZ
media_type: text/html
size_bytes: 0
sha256: <64 lowercase hex> # of the raw copy; never hand-edited
raw_reused: false
converter: html # converter name, or agent
conversion: complete | partial
warnings: []
tool: fiona-assistant <version>
---
```
+785 -31
View File
File diff suppressed because it is too large Load Diff
+20
View File
@@ -17,6 +17,7 @@ from fiona.logging_config import setup_logging
from fiona.mdoctor.mdoctor import main as mdoctor_main
from fiona.python_ruff.python_ruff import main as python_ruff_main
from fiona.wiki.graph_generator import wiki_graph_main
from fiona.wiki.housekeeping import housekeeping_main
from fiona.wiki.sanity_manager import sanity_main
from fiona.wiki.update_manager import check_update_main, update_main
from fiona.wiki.wiki import wiki_init
@@ -279,6 +280,23 @@ def main():
help="Disable tracking of external links"
)
# AI/LLM: fiona-assistant housekeeping (SPEC 4.15)
housekeeping_parser = subparsers.add_parser(
"housekeeping",
help="Run the wiki maintenance routine and report what needs work"
)
housekeeping_parser.add_argument(
"directory",
nargs="?",
default=".",
help="Wiki directory (default: current directory)"
)
housekeeping_parser.add_argument(
"--json",
action="store_true",
help="Output results in JSON format"
)
args = parser.parse_args()
setup_logging()
logging.getLogger(__name__).debug("fiona-assistant command: %s", args.command)
@@ -394,6 +412,8 @@ def main():
else:
wiki_parser.print_help()
sys.exit(1)
elif args.command == "housekeeping":
sys.exit(housekeeping_main(directory=args.directory, json_output=args.json))
else:
parser.print_help()
sys.exit(1)
+23 -8
View File
@@ -1,27 +1,34 @@
---
name: llm-wiki-agent-rules
title: LLM Wiki Agent Rules
version: 1.2.0
version: 1.3.0
created: 2025-09-23
updated: 2026-09-29
updated: 2026-09-30
type: summary
---
# LLM Wiki Agent Rules
This file is the entry point for an LLM working in an llm-wiki.
It states only what must be true before any skill is loaded.
This directory is an llm-wiki: a persistent knowledge base of
interlinked markdown. The user brings sources and questions. You
compile each source once into wiki pages, keep the cross-references
current, and answer from those pages. The pattern is
[llm-wiki-mod](./utils/skills/fiona/llm-wiki-mod.md). The wiki's
domain, tags, and directory tree are in [schema](./wiki/schema.md).
This file states only what must be true before any skill is loaded.
Commands, lint codes, and the edit workflow live in the Fiona skill.
- [1. Load the Fiona skill](#1-load-the-fiona-skill)
- [2. What an llm-wiki is](#2-what-an-llm-wiki-is)
- [3. Boundaries](#3-boundaries)
- [4. History](#4-history)
## 1. Load the Fiona skill
If the Fiona skill is not already part of the system prompt, read
[Fiona skill](./utils/skills/fiona/SKILL.md) and follow it for the
rest of the session.
rest of the session. It loads llm-wiki-mod.
When that skill is already loaded, do not read it again. This file
does not repeat it.
@@ -42,8 +49,16 @@ Fiona skill, not this file.
These hold even before the skill is loaded:
- `personal/` is read-only. Never create, edit, or delete there.
- `raw/` is read-only. Never edit archived sources.
- `raw/` is the archive. Add a new source there. Never edit, move,
or delete a file already there.
- Synthesized pages belong under `wiki/`.
- `ingest/` is only the drop zone for files waiting to be parsed.
- Do not commit, snapshot, restore, clean, or undo unless the user
asked.
## 4. History
Git is the wiki's history. After each ingest cycle and each
housekeeping pass (lint fixes, index or TOC updates, page moves),
commit with `fiona-assistant git save --description TEXT`.
`git clean`, `git undo`, and `git restore` discard work. Run them
only when the user asks.
+12 -5
View File
@@ -1,12 +1,19 @@
---
name: map
version: 1.0.0
title: Map Script
version: 1.1.0
title: Script Map
type: summary
created: 2025-09-23
updated: 2026-09-24
updated: 2026-09-30
---
# Map Script
# Script Map
Mapping utility script.
Catalog of the reusable scripts in this folder. Read it before
writing a new script, and add a row when you add one. The rules for
writing a script are in the
[Fiona skill](../skills/fiona/SKILL.md#write-reusable-scripts).
| Script | Purpose | Usage | Added |
| --- | --- | --- | --- |
| `example.py` | Placeholder that prints a greeting. | `python utils/scripts/example.py` | 2025-09-23 |
@@ -4,7 +4,7 @@ category: productivity
description: Operate an llm-wiki with the fiona-assistant CLI.
author: nvaldez
license: MIT
version: 1.4.0
version: 1.9.0
updated: 2026-09-30
---
@@ -18,6 +18,7 @@ You maintain an llm-wiki. The command for that work is
[markdown rules](./markdown_rules.md).
- [Load llm-wiki-mod](#load-llm-wiki-mod)
- [You own the wiki](#you-own-the-wiki)
- [1. Before a command](#1-before-a-command)
- [2. Install](#2-install)
- [3. Which command](#3-which-command)
@@ -33,6 +34,8 @@ You maintain an llm-wiki. The command for that work is
- [13. Frontmatter](#13-frontmatter)
- [14. Checks with no own command](#14-checks-with-no-own-command)
- [15. Do not call](#15-do-not-call)
- [16. Ingest cycle](#16-ingest-cycle)
- [17. Housekeeping](#17-housekeeping)
## Load llm-wiki-mod
@@ -41,6 +44,97 @@ raw sources, the wiki, the schema, and ingest, query, and lint.
If it is not already in context, read it before any wiki work.
When it is already loaded, do not read it again.
## You own the wiki
You are responsible for this wiki: what it says, how it is
organized, how pages link, and its history. The `fiona-assistant`
tools own nothing. They do the repeated, mechanical work cheaply,
so your tokens go to reading sources and making judgments. A tool
is a helper you direct, not an authority you defer to.
- A clean tool run is evidence, not a verdict. `wiki sanity`
passing means the style, frontmatter, and links are valid. It
does not mean a page is true, current, complete, or in the right
place. Read the pages.
- Treat tool output as a draft. When a tool gets something wrong,
such as a bad title, a lost table, or the wrong folder, fix the
result within the rules (section 16.3), or re-run it with better
arguments.
- Decisions stay with you: what a page says, what it links to,
which claims conflict, how confident the page is, and when a
source is too complex for a converter (section 16.2).
- When no tool fits, do the work yourself. Do not bend a tool to a
job it was not built for, and do not invent flags (section 15).
- When a tool fails or misbehaves, tell the user the command and
its output. Do not work around it silently.
### Write reusable scripts
When you repeat the same mechanical step and no `fiona-assistant`
command covers it, write a script under
[utils/scripts](../../scripts/map.md) instead of redoing it by hand
each time. Tokens spent once on a script are saved on every later
run, and the next session can reuse it.
1. Read the [script map](../../scripts/map.md) first. Extend an
existing script before writing a new one.
2. One job per script. Name the file in `snake_case.py`.
3. Use the standard library first. A third-party import must already
be installed with `fiona-assistant`, or be approved by the user.
4. Start with a module docstring: purpose, inputs, outputs, and one
example call. Parse arguments with `argparse`, so `--help` works.
5. Take the wiki root as an argument, defaulting to `.`. Print
results on stdout, with `--json` when you will parse them. Send
diagnostics through `logging` to stderr.
6. Keep it deterministic. No network access unless that is the
script's job and the user agreed. Never write under `raw/` or
`personal/`. A script that writes files offers `--dry-run`.
7. Add a row to the [script map](../../scripts/map.md). Run
`fiona-assistant python-ruff chklint utils/scripts`. Append a
line to `wiki/log.md`.
8. When a script proves useful in general, suggest to the user that
it become a `fiona-assistant` command.
### Save after every ingest cycle and housekeeping pass
When an ingest cycle ends (section 16.4, with sanity passing), run:
```text
fiona-assistant git save --description "ingest <slug>: <what the source is>"
```
After a housekeeping pass (lint fixes, index, log, or TOC updates,
page moves, template updates), with sanity passing, run:
```text
fiona-assistant git save --description "housekeeping: <what changed>"
```
This is a standing instruction. You do not need to ask each time.
It is the step that makes the wiki's history usable:
- **One source, one commit.** The raw copy, the page, the index
entry, the log line, and every concept or entity page the source
changed land together. `git log` becomes the record of what
entered the wiki, when, and from where.
- **Reviewable.** The user can run `git show` on that commit and see
exactly how one source changed the wiki, and check your synthesis
against it.
- **Recoverable.** A bad refinement can be undone or restored
without losing other work. That only holds when each cycle is its
own commit. Batched or skipped saves mix sources, so one undo
drops unrelated work.
- **Proof behind the log.** `wiki/log.md` says what happened. The
commit holds the before and after state that proves it.
Before saving, run `fiona-assistant git status`. `save` stages
everything in the tree. When it shows changes that are not from
this cycle, ask the user before saving. When sanity fails, fix it
first, or ask. A duplicate ingest writes nothing, so `save`
refusing a clean tree is expected. This standing instruction
covers `save` only. `snapshot`, `restore`, `clean`, and `undo`
still need the user's request.
## 1. Before a command
Run from the wiki root, the directory that contains
@@ -50,9 +144,10 @@ parent directories for the wiki root. `librarian toc file *`
looks for `fiona-settings.json` in the current directory, then
in subdirectories.
`personal/` and `raw/` are read-only, including the directory
itself. Never create, edit, or delete there. Never point a fixer
at them.
`personal/` is read-only, including the directory itself. Never
create, edit, or delete there. `raw/` is the archive: you may add a
new source file (section 16.2), but never edit, move, or delete a
file already there. Never point a fixer at either.
`librarian` and `mdoctor` also exist as their own console scripts.
Call them through `fiona-assistant` so one binary covers every
@@ -68,18 +163,13 @@ warnings as the lint report.
python -m pip install fiona-assistant
```
From a checkout of this repository:
```text
python -m pip install -e .
```
`fiona-assistant` with no command prints help and exits 0.
## 3. Which command
| Question | Command |
| --- | --- |
| Maintain the wiki: what needs work? | `housekeeping --json`, then section 17 |
| Is this wiki healthy? | `wiki sanity --json --non-interactive` |
| Markdown style on files I edited? | `mdoctor chklint <dir>` |
| Auto-fix markdown style? | `mdoctor fix <writable-dir>` |
@@ -88,9 +178,12 @@ python -m pip install -e .
| Python under the wiki? | `python-ruff chklint <dir>` |
| New files or new headings? | `librarian toc` and `librarian toc file` |
| What links to what? | `wiki graph` |
| New source, a URL or a file? | `wiki ingest <source> --json`, then section 16 |
| 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` |
| User asked to save wiki edits? | `git save --description TEXT` |
| A `*-update.md` file appeared? | Merge it, section 17.1 |
| Ingest or housekeeping done? | `git save --description TEXT` |
Prefix every row with `fiona-assistant`.
@@ -106,10 +199,10 @@ fiona-assistant wiki init [directory]
Copies the template, substitutes `DATE_PLACEHOLDER` with today's
UTC date, creates a git repo, and commits `Initial llm-wiki commit`.
`.gitignore` starts from the fiona-assistant repository ignore
file and includes `personal/`. An existing `.gitignore` keeps its
lines; missing patterns are appended. Paths matched by that
repository ignore file are not copied. `personal/` is gitignored.
`.gitignore` starts from the packaged default ignore patterns and
includes `personal/`. An existing `.gitignore` keeps its lines;
missing patterns are appended. Paths matched by those default
patterns are not copied. `personal/` is gitignored.
Success stdout:
@@ -135,14 +228,29 @@ When something differs, the lines that apply:
```text
Files to update: <N>
Conflicts (owner copy kept): <N>
- <path> (<current> -> <template>) -> <stem>-update.md
Directories to add: <N>
Files to add: <N>
Total: <N> file(s) need attention
Files skipped (locally modified): <N>
```
`--json` prints one object with `files_to_update`, `files_to_add`,
`directories_to_add`, `files_skipped`, `total`, and `has_updates`.
A file that lacks a version on either side is compared by SHA-256. Equal
hashes mean up to date. Different hashes print the first 8 hex
digits of each side instead of versions:
```text
- utils/scripts/example.py (sha256 1a2b3c4d -> 9f8e7d6c)
```
`--json` prints one object with `files_to_update`, `conflicts`,
`files_to_add`, `directories_to_add`, `files_skipped`, `total`, and
`has_updates`. Each conflict has `path`, `update_path`,
`current_version`, and `template_version`. Entries in
`files_to_update` and `conflicts` also carry `current_sha256` and
`template_sha256`: the full hash, or `null` when versions were
compared.
### 4.3. update
@@ -150,10 +258,18 @@ Files skipped (locally modified): <N>
fiona-assistant wiki update [directory] [--dry-run] [-y|--yes] [-f|--force] [--json]
```
Updates drifted core files and adds missing ones. Never deletes
user files. Never writes inside `personal/` or `raw/`. Never
writes anything under `wiki/` (seeded at init, then filled by the
LLM). Never writes a path matched by `.gitignore`.
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`.
Never overwrites an existing markdown file. When the template has a
newer version of one, such as `AGENTS.md`, `wiki/index.md`,
`wiki/log.md`, or `wiki/schema.md`, the owner's file stays as it is
and the template is written beside it as `<stem>-update.md`
(`AGENTS-update.md`, `wiki/schema-update.md`). You merge it during
housekeeping (section 17.1).
Run `--dry-run` first. It prints the plan, writes nothing, and
exits 0. Without `--yes` or `--force` the command prompts. On a
@@ -163,9 +279,12 @@ Pass `--yes` only after the user agrees to the dry run.
Success stdout:
```text
Update complete: <U> file(s) updated, <A> added, <S> skipped.
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`.
### 4.4. sanity
```text
@@ -202,6 +321,68 @@ Also: `--include-pattern`, `--exclude-pattern`,
`--external-links` / `--no-external-links`.
`--json` is an alias for `--format json`.
### 4.6. ingest
Planned. Run `fiona-assistant wiki ingest --help`
first. When the subcommand does not exist, do every step of
section 16 by hand.
```text
fiona-assistant wiki ingest <source> [--wiki DIR] [-r|--raw PATH] [-t|--target PATH] [--raw-only] [-f|--force] [--dry-run] [--json]
fiona-assistant wiki ingest --pending [--wiki DIR] [--json]
```
`<source>` is an `http://` or `https://` URL, or a file path. The
tool is the first phase of an ingest:
- A URL is downloaded into `ingest/` as whatever it is: HTML, PDF,
text. No credentials are sent.
- The file is archived under `raw/`. A file in `ingest/` is moved.
Any other file is copied. Nothing already in `raw/` is changed.
- Before archiving, its SHA-256 is compared with every file in
`raw/`. Identical bytes are never archived twice: the existing
copy is reused (`raw_reused: true`). When a page already cites
that copy, nothing is written and `duplicate_page` names it.
- The archive is converted to markdown and written as one page
with `status: raw`, `confidence: zero`, and `llm.model: none`.
- One line is appended to `wiki/log.md`.
It does not refine the page, edit `wiki/index.md`, or touch any
other page. That is your phase, section 16.
| Flag | Use |
| --- | --- |
| `-r`, `--raw PATH` | Place the raw copy, relative to `raw/`. A directory (`-r jenkins/tl153`) or a file name with an extension. |
| `-t`, `--target PATH` | Place the page, relative to `wiki/`. A directory (`-t concepts`) or a `.md` file name. |
| `--raw-only` | Archive only. Use it when you will convert by hand. |
| `-f`, `--force` | Replace an existing page. Ask the user first when that page is refined. |
| `--dry-run` | Print the plan. Writes nothing in the wiki. A URL is still downloaded, to a temporary directory. |
| `--pending` | List pages still at `status: raw`. |
Defaults: raw copies go to `raw/articles/` (HTML, text, markdown),
`raw/papers/` (PDF), or `raw/other/` (no converter). Pages go to
`wiki/sources/<slug>.md`. Use `-r` to group related sources, and
`-t` when the user names a place or the source belongs beside
existing pages.
| Converter | Handles | Loses |
| --- | --- | --- |
| `markdown` | `.md` | Nothing. Source frontmatter moves to `source_meta`. |
| `text` | `.txt`, `.log` | Structure. The body is one fenced `text` block. |
| `html` | web pages | Navigation, scripts, and anything drawn by JavaScript. |
| `pdf` | PDFs with a text layer | Tables, images, columns, and scanned pages. |
Pass `--json` and read the object: `raw_path`, `page_path`,
`sha256`, `raw_reused`, `duplicate_page`, `converter`,
`conversion` (`complete`, `partial`, `none`), and `warnings`. The
page frontmatter carries the same facts in its `ingest` map.
| Exit | Meaning | Next |
| --- | --- | --- |
| 0 | Page written, `--raw-only`, or a duplicate | Read `duplicate_page`, `conversion`, and `warnings`, then section 16.1. |
| 1 | Error on stderr, nothing written | Fix the argument, or fetch the source another way (section 16.2). |
| 3 | Raw copy archived, no page | Convert by hand (section 16.2). |
## 5. librarian
`fiona-assistant librarian` with no subcommand lists `.`.
@@ -344,9 +525,12 @@ JSN004 duplicate keys, JSN005 key order, JSN006 line length.
## 10. git
These commands act on the git repository that contains the current
directory. Run them from the wiki root. Run them only when the
user asked. `fiona-assistant git` with no subcommand prints help
and exits 1.
directory. Run them from the wiki root. `save` runs after each
ingest cycle and housekeeping pass, without asking
([save rule](#save-after-every-ingest-cycle-and-housekeeping-pass)).
`snapshot`, `restore`, `clean`, and `undo` run only on the user's
request. `fiona-assistant git` with no subcommand prints help and
exits 1.
```text
fiona-assistant git status
@@ -423,6 +607,8 @@ After you edit a page:
8. If you touched Python, `fiona-assistant python-ruff chklint <dir>`.
9. Before you call the wiki healthy,
`fiona-assistant wiki sanity . --json --non-interactive`.
10. When sanity passes, save
([save rule](#save-after-every-ingest-cycle-and-housekeeping-pass)).
Relative markdown links must point at a real file. Wikilinks
`[[page]]` must match a markdown file stem. Both are checked by
@@ -432,7 +618,8 @@ style.
Ingest drops files in `ingest/`. Archive sources under `raw/` and
do not edit them after that. Synthesized pages go under `wiki/`
(`concepts/`, `entities/`, `comparisons/`, `queries/`).
(`concepts/`, `entities/`, `comparisons/`, `queries/`). The full
ingest is section 16.
## 13. Frontmatter
@@ -458,6 +645,8 @@ in the same edit. fmlint enforces `name` and `version` only.
| `contested` | wiki pages | `true` when a claim is disputed, otherwise `false`. |
| `contradictions` | wiki pages | Other page slugs that disagree. `[]` when none. |
| `description` | SKILL.md only | Required when the file name is `SKILL.md`. |
| `status` | ingested pages | `raw` from `wiki ingest`. You set `refined` (section 16.4). |
| `ingest`, `source_meta` | ingested pages | Written by `wiki ingest`. Check them (section 16.3). Keep them when you refine. |
### Quality signals
@@ -516,7 +705,235 @@ These are not implemented. Do not invent flags for them.
- `fiona-assistant pycustomlint`
- `fiona-assistant python-ruff fix`
On a checkout of the fiona-assistant product repository, tests and
the product gate are `python scripts/run_tests.py` and
`python scripts/run_sanity.py --non-interactive`. Those are not wiki
commands. A wiki uses `fiona-assistant wiki sanity`.
`fiona-assistant wiki ingest` is planned. Call it only after
`fiona-assistant wiki ingest --help` succeeds. Otherwise follow
section 16 by hand.
## 16. Ingest cycle
An ingest has two phases. `wiki ingest` (section 4.6) converts the
source into a page at `status: raw`. You refine that page to
`status: refined`. The ingest is done only when both phases are
done. The pattern is section 3.1 of
[llm-wiki-mod](./llm-wiki-mod.md).
### 16.1. Convert
1. When the raw or page location is not obvious, run
`fiona-assistant wiki ingest <source> --dry-run --json` and
check `raw_path` and `page_path`.
2. Run `fiona-assistant wiki ingest <source> --json`, with `-r` and
`-t` when needed.
3. Read the result. When `duplicate_page` is set, the same bytes
are already archived and ingested. Nothing was written. Refine
that page if it is still `status: raw`, else stop and tell the
user which page holds the source. Use `--force` only when the
user wants it converted again.
4. On exit 0 with `conversion: complete` and no warning that lost
content, check the metadata (section 16.3), then refine
(section 16.4). Otherwise decide with section 16.2.
### 16.2. Convert by hand
The tool is the default, not a rule. You decide when the source is
too complex for it and read the source yourself. Convert by hand
when:
- The command exited 3: no converter, or conversion failed.
- `conversion` is `partial` and the warnings show lost text: no text
layer (a scanned PDF), no text content (a page drawn by JavaScript
or a login page), or pages with no text.
- Layout carries the meaning: tables, multi-column papers, forms,
slides, spreadsheets, diagrams, or a bundle of logs.
- The download failed on authentication (401, 403, or a login page
in the body). Fetch the source with a tool that has access, save
it into `ingest/`, and ingest that file.
How:
1. Make sure the raw copy exists. When it does not, run
`fiona-assistant wiki ingest <file> --raw-only --json`. Without
the tool, first compute the file's SHA-256 (`sha256sum <file>`,
or `Get-FileHash -Algorithm SHA256 <file>` in PowerShell) and
compare it with the files under `raw/` of the same size and with
`ingest.sha256` in `wiki/` pages. Reuse a match. Do not archive
the same bytes twice. With no match, copy the file (move it when
it is in `ingest/`) to the default folder in section 4.6, under
a lowercase hyphenated name that is not taken.
2. Read the raw file with your own tools. Never edit it.
3. Write the page where the tool would have put it, with the
complete frontmatter in section 16.5. Set
`ingest.converter: agent`, and fill `sha256`, `size_bytes`,
`media_type`, and `fetched` from the raw file.
4. You may write the refined page in one pass. Then follow
section 16.4 from step 3.
When the tool archived the wrong file or to the wrong place, tell
the user. Do not move or delete anything under `raw/`.
### 16.3. Check the metadata
The tool fills every key in section 16.5, but it reads the source
mechanically. Check the frontmatter against the source before you
refine, and fix what is wrong.
| Key | Check | May edit |
| --- | --- | --- |
| `title` | The real title, not a site name, a file name, or `Untitled`. | yes |
| `type` | Usually `summary` for a source page. | yes |
| `tags` | From the schema taxonomy. | yes |
| `sources` | Points at the raw file, and that file exists. | only when wrong |
| `source_meta` | Author, dates, and description match the source. Add values the converter missed, such as a date printed in the body. | yes |
| `ingest.conversion` | `partial` when you see lost text, tables, or pages. | yes |
| `ingest.warnings` | Add what you found lost. Leave the tool's lines. | yes |
| `ingest.origin`, `origin_kind`, `final_url` | Match the URL or path the user gave. | only when wrong |
| `ingest.sha256`, `size_bytes`, `media_type`, `fetched`, `tool` | Facts computed by the tool. | no |
Verify `ingest.sha256` against the raw file with `sha256sum` or
`Get-FileHash`. When a computed fact is wrong, re-run the ingest
with `--force` or tell the user. Do not hand-edit it. Bump the page
`version` patch and `updated` when you edit the metadata.
### 16.4. Refine
1. `fiona-assistant wiki ingest --pending --json` lists the pages
still at `status: raw`. Without the tool, search `wiki/` for
`status: raw`. Check each page's metadata first (section 16.3).
2. Read the page and the source it cites. Open the raw file when
`ingest.conversion` is `partial` or a claim looks garbled.
3. Rewrite the page as a source summary:
- The first paragraph says what the source is and why it matters.
- Keep facts, numbers, decisions, dates, and names. Keep a short
code or log excerpt when it backs a claim.
- Drop boilerplate: menus, cookie notices, repeated headers and
footers, page numbers.
- Stay under the 200-line split rule in the schema. Detail stays
in the raw file, which `sources` cites.
4. Add at least two outbound links, as the schema asks. Link the
concept and entity pages the source touches.
5. Update or create those concept and entity pages, using the page
thresholds in the schema. When the source disagrees with a page,
set `contested` and `contradictions` on both.
6. When the page belongs elsewhere, move it and fix every inbound
link.
7. Set the frontmatter: `status: refined`, `version: 1.0.0`,
`updated`, `type`, `tags` from the taxonomy, and the quality
signals from section 13 with your model in `llm`. Keep
`sources`, `source_meta`, and every `ingest` key.
8. Add the page to `wiki/index.md`. Append
`- YYYY-MM-DD - refined <page path> from <raw path>` to
`wiki/log.md`.
9. Run the work loop in section 12, ending with `wiki sanity`.
The ingest is done when no page is left at `status: raw` and sanity
passes. Then save it
([save rule](#save-after-every-ingest-cycle-and-housekeeping-pass)).
### 16.5. Raw page frontmatter
`wiki ingest` writes every key below, even when a value is empty
(`[]`, `{}`, or `null`). Write the same when you convert by hand.
```yaml
---
name: <slug>
version: 0.1.0
title: <title>
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: summary
status: raw
sources: [raw/<category>/<slug>.<ext>]
source_meta: {author: <name>}
ingest:
origin: <url or file path>
origin_kind: url
final_url: null
fetched: YYYY-MM-DDTHH:MM:SSZ
media_type: text/html
size_bytes: 0
sha256: <64 lowercase hex>
raw_reused: false
converter: <converter name, or agent>
conversion: complete
warnings: []
tool: fiona-assistant <version>
tags: []
confidence: zero
llm:
- model: none
contested: false
contradictions: []
---
```
When you write it by hand, set `llm.model` to your model and
`confidence` from section 13.
## 17. Housekeeping
```text
fiona-assistant housekeeping [directory] [--json]
```
One call runs the maintenance routine and tells you what needs work.
Run it when the user asks for maintenance, after `wiki update`, and
before you call the wiki healthy. It writes only `wiki_graph.html`.
It never runs `wiki update`, merges, or fixes anything. That is
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. |
| `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`. |
Every step runs, even after one fails. Exit 0 when no step is
`FAIL`; `WARN` steps do not fail the run. Pass `--json` and read
`steps[].status`, `details`, and `next`: `next` is the action to
take. The human report ends with `HOUSEKEEPING PASSED`, or
`HOUSEKEEPING FAILED - <N> step(s) need attention: <names>`.
Work through the `FAIL` steps, then run housekeeping again until it
passes. Fix a `WARN` when the user's task covers it; otherwise
report it. Then save the pass
([save rule](#save-after-every-ingest-cycle-and-housekeeping-pass)).
### 17.1. Merge an update file
`wiki update` yields to the owner. When the packaged template has a
newer version of a markdown file the owner may have edited, such as
`AGENTS.md`, `wiki/index.md`, `wiki/log.md`, or `wiki/schema.md`,
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:
1. Read both files. Compare them, for example with
`git diff --no-index <file> <stem>-update.md`.
2. Keep every owner edit: their wording, tags, sections, index
entries, and log lines. The owner wins where the two disagree on
content.
3. Take what the template adds or corrects: new sections, new
rules, new frontmatter fields, and fixed command names, flags,
or paths. A tool contract (a command, a flag, a required field)
comes from the template.
4. For `wiki/index.md` and `wiki/log.md`, keep the owner's entries.
Take only new structure from the template. Never replace the
owner's entries with the template's.
5. Set `version` to at least the update file's `version`, and
`updated` to today. Keep the owner's `created`. A lower version
brings the conflict back on the next `wiki update`.
6. Delete the update file.
7. Append `- YYYY-MM-DD - merged <stem>-update.md into <file>` to
`wiki/log.md`, and bump that file.
8. Run `fiona-assistant housekeeping` again. `merge` passes when no
update file is left.
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
missing, ask the user whether to restore it from the update file.
@@ -1,7 +1,7 @@
---
name: llm-wiki-mod
title: LLM Wiki Pattern
version: 1.2.0
version: 1.4.0
updated: 2026-09-30
type: concept
tags: [wiki, schema]
@@ -40,7 +40,8 @@ Three layers. The directory tree in
### 2.1. Raw sources
`raw/` is the archive. The agent reads it and does not edit it.
`raw/` is the archive. The agent adds new sources there and never
edits, moves, or deletes one already archived.
`ingest/` is the drop zone for files that still need parsing.
`personal/` holds user notes and is read-only, including the
directory itself.
@@ -76,6 +77,12 @@ should be checked before the next file.
After the archive step, the source lives under `raw/` and is not
edited again.
An ingest has two phases. A tool fetches the source, archives it
under `raw/`, and converts it into a page marked `status: raw`.
The agent then refines that page, updates the pages it touches,
and marks it `status: refined`. The steps are section 16 of the
[Fiona skill](./SKILL.md).
### 3.2. Query
Ask against the wiki. The agent reads the index, opens the pages
@@ -107,26 +114,16 @@ dated bullet:
Bump `version` and `updated` on `log.md` when appending. The log
is the timeline of ingests, queries, and lint passes.
Git holds the before and after of each entry. Every ingest cycle
and every housekeeping pass ends in one commit, so one source or
one cleanup can be reviewed or undone on its own.
## 5. Page rules
These match [schema](../../../wiki/schema.md). Where this file and
the schema disagree, the schema wins.
- File names are lowercase, with hyphens, and without spaces.
- Every markdown file has frontmatter. `name` and `version` are required.
- Every page under `wiki/` also requires `confidence`, `llm`,
`contested`, and `contradictions`. How to set them is section 13
of the [Fiona skill](./SKILL.md).
- Optional fields are `title`, `created`, `updated`, `type`, `tags`, and `sources`.
- `type` is `entity`, `concept`, `comparison`, `query`, `summary`, or `toc`.
- Tags come from the taxonomy in the schema.
- Bump `version` on every edit. Set `updated` to the edit date.
- Patch for a clarification, minor for a new section, major for a breaking change.
- Use a relative markdown link between pages.
- A relative link resolves to a file. A wikilink matches a markdown file stem.
- A new page is listed in the index. Each action is one line in the log.
- Create a page when a concept is in two or more sources, or is central to one.
- Split a page that grows past 200 lines.
File names, frontmatter, tags, links, and when to create or split
a page are in [schema](../../../wiki/schema.md). How to fill the
frontmatter and the quality signals is section 13 of the
[Fiona skill](./SKILL.md). This file does not repeat them.
## 6. Why this works
+7 -2
View File
@@ -1,10 +1,15 @@
---
name: index
title: Wiki Index
version: 1.0.0
version: 1.1.0
type: summary
created: 2025-09-23
updated: 2026-09-24
updated: 2026-09-30
confidence: trusted
llm:
- model: none
contested: false
contradictions: []
---
# Wiki Index
+5 -73
View File
@@ -1,13 +1,13 @@
---
name: log
title: Wiki Log
version: 1.2.10
version: 2.0.0
type: summary
created: 2025-09-23
updated: 2026-09-30
created: DATE_PLACEHOLDER
updated: DATE_PLACEHOLDER
confidence: trusted
llm:
- model: grok-4.7
- model: none
contested: false
contradictions: []
---
@@ -16,72 +16,4 @@ contradictions: []
Chronological tracking of all actions performed on the wiki.
- 2026-09-25 - Reconciled the frontmatter schemas: `name`/`version` required,
`title` optional, `toc` added to allowed types (SPEC 6.2,
project agent rule 10.1, schema.md v1.1.0); stamped frontmatter on
`personal/README.md` and `raw/README.md`.
- 2026-09-25 - Renumbered AGENTS.md rules into numbered sections (rule 8 is
now rule 10.1); updated cross-references in SPEC.md, todo.md, run_sanity.py,
and schema.md.
- 2026-09-25 - Sectionized the llm-wiki AGENTS.md with numbered sections
(1. Pre-requisites through 6. Boundaries) and a matching TOC; bumped it
to v1.1.0.
- 2026-09-25 - Added project agent rule 3.1 (rule references use the
`project agent rule N.M` form, renamed from `fiona project rule`);
updated cross-references in SPEC.md, todo.md, run_sanity.py, and
schema.md to the new form.
- 2026-09-26 - Updated the root AGENTS.md structure diagram to match reality
(llm-wiki lives at `src/llm-wiki/`; `src/` also contains `wiki/`,
`run_tests.py`, `run_sanity.py`, `settings_dev.json`, `utils.sh`,
`install_packages.sh`); declared `wiki/schema.md` the final source of
truth for the llm-wiki directory structure; added the missing
`wiki/logs/` and `wiki/sources/` entries to the schema.md diagram
(schema.md v1.2.0).
- 2026-09-26 - Added the missing SPEC 7.16.3 reference to the
fiona-settings framework todo item in `todo.md`.
- 2026-09-27 - Restored the run_sanity progress heartbeat on the shared
SanityRunner engine (SPEC 7.16.1): `run_all` gained optional
`progress` and `heartbeat` callbacks plus INFO lifecycle logging;
run_sanity passes stdout callbacks (DONE markers and WAITING lines)
while wiki sanity output stays unchanged. Fixed the two ruff
violations from the engine refactor (I001 in test_sanity_runner,
PERF102 in wiki/sanity_manager); marked the todo.md heartbeat item
done and updated SPEC 7.16.1 accordingly.
- 2026-09-27 - Sped up the pytest sanity check (64s -> 14s with
coverage): added session-scoped `pristine_wiki` and
`pristine_check_results` fixtures plus a `minimal_wiki` fixture to
src/tests/conftest.py, and rewired test_sanity_manager.py and the
wiki-sanity tests in test_fiona_main.py onto them, so the full
template is sanity-checked once per session instead of 13 times;
also fixed the missing trailing newline in todo.md (MD047).
- 2026-09-27 - Added live per-check progress bars to run_sanity
(SPEC 7.16.2): interactive mode renders a block of progress bars
in place (ANSI cursor-up and line-clear), non-interactive mode
(--non-interactive or pipe) prints plain status lines every
`interval` seconds. Progress is set in settings_dev.json's
`progress` section with `interval` and `expected-seconds` keys.
- 2026-09-29 - Retargeted spec citations in this log, `todo.md`, and
the code to the current section numbers.
- 2026-09-29 - Moved the template to `src/fiona/data/llm_wiki/` as
package data (no importable `llm-wiki` package). Fiona skill v1.2.1.
- 2026-09-29 - Restored the development lifecycle as project agent
rule 2.1 (AGENTS.md v1.4.1) and linked the python-tdd skill.
- 2026-09-29 - PYC001 allows a module-level if/else import before
the first function or class, for OS selection (SPEC 6.4.2,
v0.40.0).
- 2026-09-29 - llm-wiki AGENTS.md (v1.2.0) is a short entry point
that loads the Fiona skill when it is not already in the system
prompt. Fiona skill v1.2.0 documents the fiona-assistant CLI and
loads llm-wiki-mod into context when that file is not already
loaded. Root AGENTS.md v1.3.3 points wiki tasks at that skill.
- 2026-09-29 - Aligned `utils/skills/fiona/llm-wiki-mod.md` (v1.1.0)
to the schema: canonical frontmatter, the raw / wiki / schema
layers, and the index, log, and page rules. Commands stay in
the Fiona skill.
- 2026-09-30 - Quality signals are required on pages under `wiki/`:
`confidence`, `llm` (`model`, and `reasoning` when reported),
`contested`, and `contradictions`. Fiona skill v1.3.0 teaches
how to set them. fmlint still enforces `name` and `version` only
(SPEC 6.2.3, schema v1.3.0).
- 2026-09-30 - Clarified that a markdown link is `[text](url)` in the
schema conventions (schema v1.3.2).
- DATE_PLACEHOLDER - Initialized the llm-wiki.
+35 -17
View File
@@ -1,14 +1,14 @@
---
name: llm-wiki-schema
title: LLM Wiki Schema
version: 1.3.2
version: 1.6.0
created: 2025-09-18
updated: 2026-09-30
type: summary
tags: [wiki, schema]
confidence: trusted
llm:
- model: grok-4.7
- model: claude-opus-5.5
contested: false
contradictions: []
---
@@ -17,7 +17,8 @@ contradictions: []
## Domain
Personal knowledge base and inventory management.
A personal knowledge base. Replace this line with the wiki's subject
and extend the tag taxonomy to match it.
## Conventions
@@ -25,11 +26,13 @@ Personal knowledge base and inventory management.
- Every page starts with YAML frontmatter. Required on every file:
`name`, `version`. Required on pages under `wiki/`: `confidence`,
`llm`, `contested`, `contradictions`. Optional: `title`, `created`,
`updated`, `type`, `tags`, `sources`.
`updated`, `type`, `tags`, `sources`. Ingested pages also carry
`status`, `source_meta`, and the `ingest` provenance map.
- Use markdown links (`[text](url)`) to link between pages (minimum 2 outbound links per page).
- When updating a page, always bump the `updated` date.
- When updating a page, bump `version` and set `updated` to the edit date.
- Every new page must be added to `index.md` under the correct section.
- Every action must be appended to `log.md`.
- Every action must be appended to `log.md`. In the first edit of a
new year, move the previous year's entries to `logs/log-YYYY.md`.
## Frontmatter
@@ -37,9 +40,8 @@ Personal knowledge base and inventory management.
`wiki/` also requires the quality signals `confidence`, `llm`,
`contested`, and `contradictions`. How to set them is section 13 of
the [Fiona skill](../utils/skills/fiona/SKILL.md). All other fields
are optional. This is the single canonical frontmatter schema,
identical to project agent rule 10.1 (see SPEC 6.2). fmlint enforces
`name` and `version` only.
are optional. This is the single canonical frontmatter schema.
fmlint enforces `name` and `version` only.
```yaml
---
@@ -58,13 +60,27 @@ llm:
- reasoning: high # when the model reports a level
contested: true
contradictions: [other-page-slug]
# written by wiki ingest (Fiona skill section 16):
status: raw | refined
source_meta: {author: Name} # metadata read from the source
ingest: # provenance; every key always present
origin: https://host/path # URL or file path of the source
origin_kind: url | file
final_url: null # URL after redirects
fetched: YYYY-MM-DDTHH:MM:SSZ
media_type: text/html
size_bytes: 0
sha256: <64 lowercase hex> # of the raw copy; never hand-edited
raw_reused: false
converter: html # converter name, or agent
conversion: complete | partial
warnings: []
tool: fiona-assistant <version>
---
```
## Tag Taxonomy
- inventory
- box
- wiki
- schema
@@ -73,7 +89,7 @@ contradictions: [other-page-slug]
- Create a page when an entity/concept appears in 2+ sources OR is central to
one source.
- Split pages over 200 lines.
- Archive superseded pages to `_archive/`.
- Move superseded pages to `wiki/_archive/` and fix every inbound link.
## Directory Structure
@@ -89,7 +105,8 @@ llm-wiki/
│ ├── articles/ # Web articles, clippings
│ ├── papers/ # PDFs, arXiv papers
│ ├── transcripts/ # Meeting notes, interviews
│ └── assets/ # Images, diagrams referenced by sources
│ ├── assets/ # Images, diagrams referenced by sources
│ └── other/ # Ingested files no converter handles
├── utils/
│ ├── personas/ # Agent personas configurations
│ ├── scripts/ # Reusable utility scripts
@@ -104,12 +121,13 @@ llm-wiki/
│ ├── comparisons/ # Layer 2: Side-by-side analyses
│ ├── queries/ # Layer 2: Filed query results worth keeping
│ ├── sources/ # Layer 2: Source material backing wiki pages
│ └── logs/ # Archived log files rotated out of log.md
│ ├── logs/ # Archived log files rotated out of log.md
│ └── _archive/ # Superseded pages, created when first needed
└── table_of_contents.md # Auto-generated navigation index for quick lookup
```
- **Layer 1 — Raw Sources:** `raw/` at the wiki root. The agent reads but never
modifies these.
- **Layer 1 — Raw Sources:** `raw/` at the wiki root. The agent adds new
sources and never modifies existing ones.
- **Layer 2 — The Wiki:** Agent-owned markdown files. Created, updated, and
cross-referenced by the agent.
- **Layer 3 — The Schema:** `SCHEMA.md` defines structure, conventions, and tag taxonomy.
- **Layer 3 — The Schema:** `wiki/schema.md` (this file) defines structure, conventions, and tag taxonomy.
+9 -9
View File
@@ -74,7 +74,7 @@ class GitTool:
# Check for modified/staged files
if self.repo.is_dirty():
return False
# Check for untracked files
untracked = self.repo.untracked_files
return len(untracked) == 0
@@ -171,7 +171,7 @@ class GitTool:
tag for tag in self.repo.tags
if tag.name.endswith(f"_{tag_name}") or tag.name == tag_name
]
if matching_tags:
# Sort by commit date descending and take the most recent
matching_tags.sort(
@@ -179,7 +179,7 @@ class GitTool:
reverse=True
)
tag_ref = matching_tags[0]
if tag_ref is None:
raise git.GitCommandError(
f"Tag '{tag_name}' does not exist."
@@ -190,7 +190,7 @@ class GitTool:
# Restore the tag's tree into the working directory and index
self.repo.git.checkout(tag_ref.commit, "--", ".")
# Create a new commit with the restored state
new_commit = self.repo.index.commit(restore_message)
@@ -289,23 +289,23 @@ class GitTool:
git.InvalidGitRepositoryError: If git initialization fails.
"""
repo_path = pathlib.Path(repo_path).resolve()
# Initialize the repo
repo = GitTool.init_repo(repo_path)
# CURSOR: 2026-09-30 - seed .gitignore from the repository ignore file.
# AI/LLM: 2026-09-30 - seed .gitignore from the repository ignore file.
ensure_wiki_gitignore(repo_path)
# Add all files and make initial commit
repo.git.add("--all")
repo.index.commit(initial_message)
return repo
def main(): # pragma: no cover
"""Command-line interface for the GitTool.
Note: CLI is tested via integration tests through fiona-assistant git commands.
"""
parser = argparse.ArgumentParser(
+340
View File
@@ -0,0 +1,340 @@
"""Wiki housekeeping routine (SPEC 4.15, 7.26).
Generated by AI/LLM: 2026-09-30 - one call for LLM wiki maintenance.
`fiona-assistant housekeeping` runs the maintenance steps in a fixed
order and reports, per step, a status (`PASS`, `WARN`, `FAIL`), a
summary, detail lines, and the next actions for the LLM. The routine
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.
- `ingest`: pages under `wiki/` still at `status: raw`.
- `sanity`: every `wiki sanity` check.
- `graph`: regenerate `wiki_graph.html` and list orphan pages.
"""
from __future__ import annotations
import contextlib
import io
import json
import os
import sys
import tempfile
from collections.abc import Callable
from pathlib import Path
from fiona.librarian.md_frontmatter import FrontmatterError, parse_frontmatter
from fiona.wiki.graph_generator import wiki_graph_main
from fiona.wiki.sanity_manager import SETTINGS_FILE, run_wiki_checks
from fiona.wiki.update_manager import UPDATE_SUFFIX, check_wiki_updates
STEP_NAMES = ("check-update", "merge", "ingest", "sanity", "graph")
GRAPH_FILE = "wiki_graph.html"
UPDATE_FILE_SUFFIX = f"{UPDATE_SUFFIX}.md"
# AI/LLM: read-only zones sit at the wiki root; .git is skipped anywhere
ROOT_SKIP_DIRS = frozenset({"personal", "raw"})
# =============================================================================
# Helpers
# =============================================================================
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).
"""
return {
"name": name,
"status": status,
"summary": summary,
"details": details or [],
"next": next_steps or [],
}
def _relative(path: str | Path, wiki_root: Path) -> str:
"""Return a path relative to the wiki root, with `/` separators.
Generated by AI/LLM: 2026-09-30 - report paths from the wiki root.
"""
return Path(os.path.relpath(path, wiki_root)).as_posix()
def _frontmatter(path: Path) -> dict:
"""Return a page's frontmatter, or an empty dict when it cannot be read.
Generated by AI/LLM: 2026-09-30 - sanity reports broken YAML itself.
"""
try:
frontmatter = parse_frontmatter(path)
except (FrontmatterError, UnicodeDecodeError):
return {}
return frontmatter if isinstance(frontmatter, dict) else {}
def _markdown_files(wiki_root: Path, subdir: str = "") -> list[Path]:
"""List markdown files outside read-only zones and `.git`, sorted.
Generated by AI/LLM: 2026-09-30 - pruned walk for the merge and ingest steps.
Args:
wiki_root: Root path of the wiki.
subdir: Optional directory, relative to the root, to walk instead.
Returns:
list[Path]: Markdown files found.
"""
start = wiki_root / subdir
found = []
for current, dirs, files in os.walk(start):
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 if name.endswith(".md"))
return sorted(found)
# =============================================================================
# Steps
# =============================================================================
def check_update_step(wiki_root: Path) -> dict:
"""Report core files behind the template without writing (SPEC 7.26.2).
Generated by AI/LLM: 2026-09-30 - read-only wiki check-update.
"""
summary = check_wiki_updates(wiki_root)
details = [f"update: {_relative(r.file_path, wiki_root)}" for r in summary.files_to_update]
details += [
f"conflict: {_relative(r.file_path, wiki_root)} -> {_relative(r.update_path, wiki_root)}"
for r in summary.conflicts
]
details += [f"add: {path.as_posix()}" for path in summary.files_to_add]
text = (
f"{len(summary.files_to_update)} update(s), {len(summary.conflicts)} conflict(s), "
f"{len(summary.files_to_add)} addition(s)"
)
if not details:
return _step("check-update", "PASS", text)
return _step("check-update", "WARN", text, details, [
"Ask the user, then run fiona-assistant wiki update --dry-run and wiki update --yes."
])
def merge_step(wiki_root: Path) -> dict:
"""List update files that wait for an LLM merge (SPEC 7.26.3).
Generated by AI/LLM: 2026-09-30 - pending *-update.md merges.
"""
details, actions = [], []
for update_file in _markdown_files(wiki_root):
if not update_file.name.endswith(UPDATE_FILE_SUFFIX):
continue
target = update_file.with_name(
update_file.name[: -len(UPDATE_FILE_SUFFIX)] + ".md"
)
update_rel = _relative(update_file, wiki_root)
target_rel = _relative(target, wiki_root)
missing = "" if target.exists() else " (target missing)"
details.append(f"{update_rel} -> {target_rel}{missing}")
version = _frontmatter(update_file).get("version") or "the template version"
actions.append(
f"Merge {update_rel} into {target_rel}: keep the owner's edits, "
f"take the template changes, set version to at least {version}, "
f"then delete {update_rel}."
)
text = f"{len(details)} update file(s) wait for a merge"
return _step("merge", "FAIL" if details else "PASS", text, details, actions)
def ingest_step(wiki_root: Path) -> dict:
"""List pages under wiki/ still at `status: raw` (SPEC 7.26.4).
Generated by AI/LLM: 2026-09-30 - pages waiting for a refine.
"""
pages = [
_relative(page, wiki_root)
for page in _markdown_files(wiki_root, "wiki")
if _frontmatter(page).get("status") == "raw"
]
text = f"{len(pages)} raw page(s)"
if not pages:
return _step("ingest", "PASS", text)
return _step("ingest", "WARN", text, pages,
["Refine each raw page, then set status: refined."])
def sanity_step(wiki_root: Path) -> dict:
"""Run every wiki sanity check without the progress display (SPEC 7.26.5).
Generated by AI/LLM: 2026-09-30 - failing check reports as details.
"""
results = run_wiki_checks(wiki_root)
failing = {name: check for name, check in results["checks"].items() if check["result"]}
text = f"{results['total_violations']} violation(s) in {len(failing)} check(s)"
if not failing:
return _step("sanity", "PASS", text)
details = [
f"{name}: {line.strip().removeprefix('- ')}"
for name, check in failing.items()
for line in check["stdout"].splitlines()
if line.strip()
]
return _step("sanity", "FAIL", text, details,
["Fix the violations, then run fiona-assistant housekeeping again."])
def graph_step(wiki_root: Path) -> dict:
"""Write wiki_graph.html at the wiki root and list orphans (SPEC 7.26.6).
Generated by AI/LLM: 2026-09-30 - graph plus orphan pages under wiki/.
"""
captured = io.StringIO()
with tempfile.TemporaryDirectory() as temp_dir:
graph_json = Path(temp_dir) / "graph.json"
with contextlib.redirect_stdout(captured), contextlib.redirect_stderr(captured):
code = wiki_graph_main(str(wiki_root), output=str(graph_json), format_type="json")
if code == 0:
code = wiki_graph_main(str(wiki_root), output=str(wiki_root / GRAPH_FILE))
if code != 0:
error = captured.getvalue().strip() or f"wiki graph exited {code}"
return _step("graph", "FAIL", f"could not write {GRAPH_FILE}",
error.splitlines())
data = json.loads(graph_json.read_text(encoding="utf-8"))
orphans = sorted(
rel for rel in (_relative(path, wiki_root) for path in data["orphans"])
if rel.startswith("wiki/") and not rel.endswith(UPDATE_FILE_SUFFIX)
)
text = (
f"wrote {GRAPH_FILE} ({data['metadata']['file_count']} nodes, "
f"{len(data['edges'])} edges)"
)
if not orphans:
return _step("graph", "PASS", text)
return _step("graph", "WARN", text, [f"orphan: {rel}" for rel in orphans],
["Link each orphan page from a related page or from wiki/index.md."])
STEPS: tuple[Callable[[Path], dict], ...] = (
check_update_step,
merge_step,
ingest_step,
sanity_step,
graph_step,
)
# =============================================================================
# Routine and Report
# =============================================================================
def run_housekeeping(directory: str | Path = ".") -> dict:
"""Run every housekeeping step over a wiki (SPEC 7.26.1).
Generated by AI/LLM: 2026-09-30 - every step runs, even after a FAIL.
Args:
directory: The wiki directory. Defaults to the current directory.
Returns:
dict: `target` (resolved path), `steps` (one result per step,
in `STEP_NAMES` order), and `passed` (no step is `FAIL`).
Raises:
FileNotFoundError: If the directory does not exist.
NotADirectoryError: If the directory is not an llm-wiki directory.
"""
wiki_root = Path(directory).resolve()
if not wiki_root.exists():
raise FileNotFoundError(f"Directory not found: {directory}")
if not (wiki_root / SETTINGS_FILE).exists():
raise NotADirectoryError(f"Directory '{directory}' is not an llm-wiki directory")
steps = [step(wiki_root) for step in STEPS]
return {
"target": wiki_root,
"steps": steps,
"passed": all(step["status"] != "FAIL" for step in steps),
}
def format_housekeeping_report(results: dict) -> str:
"""Format housekeeping results for humans and LLMs (SPEC 4.15).
Generated by AI/LLM: 2026-09-30 - step blocks, next steps, verdict.
Args:
results: The dict returned by run_housekeeping.
Returns:
str: The report text.
"""
lines = ["Housekeeping Report", f"TARGET: {results['target']}", ""]
for step in results["steps"]:
lines.append(f"[{step['status']}] {step['name']}: {step['summary']}")
lines.extend(f" - {detail}" for detail in step["details"])
actions = list(dict.fromkeys(a for step in results["steps"] for a in step["next"]))
if actions:
lines.extend(["", "Next steps:"])
lines.extend(f" - {action}" for action in actions)
failing = [step["name"] for step in results["steps"] if step["status"] == "FAIL"]
lines.append("")
if failing:
lines.append(
f"HOUSEKEEPING FAILED - {len(failing)} step(s) need attention: "
f"{', '.join(failing)}"
)
else:
lines.append("HOUSEKEEPING PASSED")
return "\n".join(lines)
def housekeeping_main(directory: str = ".", json_output: bool = False) -> int:
"""Main function for the 'housekeeping' CLI command.
Generated by AI/LLM: 2026-09-30 - exit 1 on any FAIL step.
Args:
directory: Wiki directory (default: current directory).
json_output: If True, print the results as one JSON object.
Returns:
int: 0 when no step is `FAIL`, 1 otherwise or on an invalid wiki.
"""
try:
results = run_housekeeping(directory)
except (FileNotFoundError, NotADirectoryError) as error:
print(f"Error: {error}", file=sys.stderr)
return 1
if json_output:
print(json.dumps({**results, "target": str(results["target"])}, indent=2))
else:
print(format_housekeeping_report(results))
return 0 if results["passed"] else 1
__all__ = [
"GRAPH_FILE",
"STEPS",
"STEP_NAMES",
"check_update_step",
"format_housekeeping_report",
"graph_step",
"housekeeping_main",
"ingest_step",
"merge_step",
"run_housekeeping",
"sanity_step",
]
+9 -9
View File
@@ -1,6 +1,6 @@
"""Gitignore patterns shared by wiki init and wiki update.
Generated by CURSOR: 2026-09-30 - seed wiki ignores from the repository file.
Generated by AI/LLM: 2026-09-30 - seed wiki ignores from the repository file.
"""
from __future__ import annotations
@@ -16,7 +16,7 @@ _PERSONAL_PATTERN = "personal/"
def gitignore_patterns_from_text(text: str) -> list[str]:
"""Return ignore patterns from gitignore text.
Generated by CURSOR: 2026-09-30 - drop blanks and comments.
Generated by AI/LLM: 2026-09-30 - drop blanks and comments.
Args:
text: Contents of a .gitignore file.
@@ -35,7 +35,7 @@ def gitignore_patterns_from_text(text: str) -> list[str]:
def path_is_ignored(relpath: str, patterns: list[str]) -> bool:
"""Return whether a relative posix path matches any gitignore pattern.
Generated by CURSOR: 2026-09-30 - match unanchored names and directory prefixes.
Generated by AI/LLM: 2026-09-30 - match unanchored names and directory prefixes.
A pattern with no slash matches any path segment. A trailing slash matches
a directory and everything under it. ``*`` does not cross a directory
@@ -66,7 +66,7 @@ def _pattern_matches(relpath: str, pattern: str) -> bool:
def repository_gitignore_path() -> pathlib.Path | None:
"""Find the fiona-assistant repository .gitignore, if this tree has one.
Generated by CURSOR: 2026-09-30 - prefer the source checkout over package data.
Generated by AI/LLM: 2026-09-30 - prefer the source checkout over package data.
Returns:
Path to the repository .gitignore, or None when this install is not
@@ -87,7 +87,7 @@ def repository_gitignore_path() -> pathlib.Path | None:
def packaged_gitignore_path() -> pathlib.Path | None:
"""Return the packaged copy of the repository .gitignore, if present.
Generated by CURSOR: 2026-09-30 - fallback for an installed wheel.
Generated by AI/LLM: 2026-09-30 - fallback for an installed wheel.
Returns:
Path to ``fiona/data/default.gitignore``, or None when it is absent.
@@ -102,7 +102,7 @@ def packaged_gitignore_path() -> pathlib.Path | None:
def repository_gitignore_text() -> str:
"""Load the ignore file that seeds a wiki, as LF text.
Generated by CURSOR: 2026-09-30 - repository file, then packaged copy.
Generated by AI/LLM: 2026-09-30 - repository file, then packaged copy.
Returns:
Ignore file text ending in a newline.
@@ -122,7 +122,7 @@ def repository_gitignore_text() -> str:
def wiki_gitignore_patterns() -> list[str]:
"""Return patterns written into a wiki, repository set plus personal/.
Generated by CURSOR: 2026-09-30 - personal/ stays untracked after init.
Generated by AI/LLM: 2026-09-30 - personal/ stays untracked after init.
Returns:
Ignore patterns in write order.
@@ -136,7 +136,7 @@ def wiki_gitignore_patterns() -> list[str]:
def wiki_gitignore_text() -> str:
"""Return the full .gitignore body for a wiki that does not have one yet.
Generated by CURSOR: 2026-09-30 - repository text plus personal/ when missing.
Generated by AI/LLM: 2026-09-30 - repository text plus personal/ when missing.
Returns:
File body ending in a newline.
@@ -150,7 +150,7 @@ def wiki_gitignore_text() -> str:
def ensure_wiki_gitignore(directory: pathlib.Path) -> None:
"""Create .gitignore or append patterns that are not already listed.
Generated by CURSOR: 2026-09-30 - put or append the repository ignores.
Generated by AI/LLM: 2026-09-30 - put or append the repository ignores.
Args:
directory: Wiki root that should contain .gitignore.
+149 -19
View File
@@ -8,6 +8,8 @@ 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)
- Presenting update summaries to users
"""
@@ -49,6 +51,8 @@ class FileComparisonResult:
is_new_file: bool = False
is_settings_file: bool = False
is_locally_modified: bool = False
is_conflict: bool = False
update_path: Path | None = None
def __post_init__(self):
"""Validate the comparison result."""
@@ -64,6 +68,7 @@ class UpdateSummary:
files_to_add: list[Path] = field(default_factory=list)
directories_to_add: list[Path] = field(default_factory=list)
files_skipped: list[FileComparisonResult] = field(default_factory=list)
conflicts: list[FileComparisonResult] = field(default_factory=list)
settings_file: Path | None = None
@property
@@ -71,12 +76,13 @@ class UpdateSummary:
"""Check if there are any updates needed."""
return bool(
self.files_to_update or self.files_to_add or self.directories_to_add
or self.conflicts
)
@property
def total_files(self) -> int:
"""Get the total number of files to update/add."""
return len(self.files_to_update) + len(self.files_to_add)
"""Get the total number of files to update, add, or write as conflicts."""
return len(self.files_to_update) + len(self.files_to_add) + len(self.conflicts)
# =============================================================================
@@ -108,6 +114,9 @@ SETTINGS_FILE = "fiona-settings.json"
# Read-only zones that should never be modified
READ_ONLY_ZONES = ["personal/", "raw/"]
# CURSOR: stem suffix of the file that carries a newer template (SPEC 7.2.11.1)
UPDATE_SUFFIX = "-update"
# =============================================================================
# Helper Functions
@@ -124,6 +133,20 @@ def get_llm_wiki_source_path() -> Path:
return llm_wiki_template()
def update_file_path(file_path: Path) -> Path:
"""Return the sibling update file for a core file (SPEC 7.2.11.1).
Generated by CURSOR: 2026-09-30 - `AGENTS.md` gives `AGENTS-update.md`.
Args:
file_path: The owner's core file.
Returns:
Path: `<stem>-update<suffix>` in the same directory.
"""
return file_path.with_name(f"{file_path.stem}{UPDATE_SUFFIX}{file_path.suffix}")
def calculate_sha256(file_path: Path) -> str:
"""Calculate SHA256 hash of a file.
@@ -228,6 +251,26 @@ def is_version_newer(candidate: str, baseline: str) -> bool:
return candidate > baseline
def template_sha256(template_path: Path) -> str:
"""Hash the text wiki init would write for a template file (SPEC 7.2.12).
Generated by CURSOR: 2026-09-30 - DATE_PLACEHOLDER expanded, endings kept.
Args:
template_path: Path to the template file.
Returns:
str: SHA-256 hex digest of the expanded UTF-8 text, or of the raw
bytes when the file is not UTF-8 text.
"""
try:
with open(template_path, encoding="utf-8", newline="") as handle:
text = replace_date_placeholders(handle.read())
except UnicodeDecodeError:
return calculate_sha256(template_path)
return hashlib.sha256(text.encode("utf-8")).hexdigest()
def _content_differs(wiki_file: Path, template_file: Path) -> bool:
"""Compare a wiki file against its template, placeholder-expanded.
@@ -256,11 +299,16 @@ 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):
- template version newer -> needs update
Classification (SPEC 7.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)
- wiki version newer or content diverged at the same version -> locally
modified (skipped and reported by the update run)
- files without version frontmatter fall back to a content comparison
- files without version frontmatter compare SHA-256 and are a conflict
when the hashes differ (SPEC 7.2.12)
Modified by CURSOR: 2026-09-30 - SHA-256 compare when a version is missing.
Args:
file_path: Path to the current wiki file.
@@ -281,15 +329,17 @@ def compare_md_file(file_path: Path, template_path: Path) -> FileComparisonResul
)
if current_version is None or template_version is None:
result.needs_update = _content_differs(file_path, template_path)
return result
if is_version_newer(template_version, current_version):
result.needs_update = True
result.current_hash = calculate_sha256(file_path)
result.template_hash = template_sha256(template_path)
result.is_conflict = result.current_hash != result.template_hash
elif is_version_newer(template_version, current_version):
result.is_conflict = True
elif is_version_newer(current_version, template_version) or _content_differs(
file_path, template_path
):
result.is_locally_modified = True
if result.is_conflict:
result.update_path = update_file_path(file_path)
return result
@@ -298,6 +348,8 @@ 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 CURSOR: 2026-09-30 - template side hashes init's text (7.2.12).
Args:
file_path: Path to the current wiki file.
template_path: Path to the template file in the package.
@@ -310,7 +362,7 @@ def compare_non_md_file(file_path: Path, template_path: Path) -> FileComparisonR
is_core_file=True,
has_template_version=False,
current_hash=calculate_sha256(file_path),
template_hash=calculate_sha256(template_path),
template_hash=template_sha256(template_path),
)
result.needs_update = result.current_hash != result.template_hash
return result
@@ -384,12 +436,26 @@ def _excluded_from_update(relative: Path, wiki_root: Path, patterns: list[str])
Paths under ``wiki/`` are seeded only by wiki init. Read-only zones and
gitignore matches are never written or reported.
"""
return _is_wiki_page_path(relative) or _is_protected(relative, wiki_root, patterns)
def _is_wiki_page_path(relative: Path) -> bool:
"""Return whether a template-relative path is ``wiki/`` or under it.
Generated by CURSOR: 2026-09-30 - wiki/ pages only ever get conflicts.
"""
rel = relative.as_posix()
if rel == "wiki" or rel.startswith("wiki/"):
return True
return rel == "wiki" or rel.startswith("wiki/")
def _is_protected(relative: Path, wiki_root: Path, patterns: list[str]) -> bool:
"""Return whether a path is in a read-only zone or gitignored.
Generated by CURSOR: 2026-09-30 - split out of _excluded_from_update.
"""
if is_read_only_file(wiki_root / relative, wiki_root):
return True
return path_is_ignored(rel, patterns)
return path_is_ignored(relative.as_posix(), patterns)
def find_missing_core_files(wiki_root: Path, template_dir: Path) -> list[Path]:
@@ -490,7 +556,11 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
for relative in get_all_template_files(template_dir):
wiki_file = wiki_root / relative
if _excluded_from_update(relative, wiki_root, patterns):
if _is_protected(relative, wiki_root, patterns):
continue
# CURSOR: under wiki/ only an existing markdown page can conflict (SPEC 7.2.9)
wiki_page = _is_wiki_page_path(relative)
if wiki_page and (relative.suffix != ".md" or not wiki_file.exists()):
continue
template_file = template_dir / relative
@@ -506,7 +576,11 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
else:
result = compare_non_md_file(wiki_file, template_file)
if result.needs_update:
if result.is_conflict:
summary.conflicts.append(result)
elif wiki_page:
continue
elif result.needs_update:
summary.files_to_update.append(result)
if result.is_settings_file:
summary.settings_file = wiki_file
@@ -518,6 +592,23 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
return summary
SHORT_HASH_LENGTH = 8
def _change_detail(result: FileComparisonResult) -> str:
"""Return the ` (current -> template)` detail for one report line.
Generated by CURSOR: 2026-09-30 - versions, else short SHA-256 (7.2.12.2).
"""
if result.current_version and result.template_version:
return f" ({result.current_version} -> {result.template_version})"
if result.current_hash and result.template_hash:
current = result.current_hash[:SHORT_HASH_LENGTH]
template = result.template_hash[:SHORT_HASH_LENGTH]
return f" (sha256 {current} -> {template})"
return ""
def format_check_update_output(summary: UpdateSummary) -> str:
"""Format the check-update summary for human-readable output.
@@ -534,11 +625,17 @@ def format_check_update_output(summary: UpdateSummary) -> str:
else:
lines.append(f"Files to update: {len(summary.files_to_update)}")
for result in summary.files_to_update:
detail = ""
if result.current_version and result.template_version:
detail = f" ({result.current_version} -> {result.template_version})"
detail = _change_detail(result)
lines.append(f" - {result.file_path.as_posix()}{detail}")
if summary.conflicts:
lines.append(f"Conflicts (owner copy kept): {len(summary.conflicts)}")
for result in summary.conflicts:
detail = _change_detail(result)
lines.append(
f" - {result.file_path.as_posix()}{detail} -> {result.update_path.name}"
)
if summary.directories_to_add:
lines.append(f"Directories to add: {len(summary.directories_to_add)}")
for directory in summary.directories_to_add:
@@ -590,8 +687,12 @@ def update_core_files(directory: str | Path = ".", force: bool = False, yes: boo
- When force=True or yes=True, updates all identified files without prompting.
- 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.
- Returns summary of all updated files.
Modified by CURSOR: 2026-09-30 - write update files for conflicts.
"""
wiki_root = Path(directory).resolve()
@@ -630,6 +731,10 @@ def update_core_files(directory: str | Path = ".", force: bool = False, yes: boo
else:
_copy_file(template_dir / relative, result.file_path)
for result in summary.conflicts:
relative = result.file_path.relative_to(wiki_root)
_copy_file(template_dir / relative, result.update_path)
# Report locally-modified files that were skipped
if verbose and summary.files_skipped:
print("Skipped locally-modified files:")
@@ -722,10 +827,23 @@ def check_update_main(directory: str = ".", json_output: bool = False) -> int:
"path": str(result.file_path),
"current_version": result.current_version,
"template_version": result.template_version,
"current_sha256": result.current_hash,
"template_sha256": result.template_hash,
"is_settings_file": result.is_settings_file,
}
for result in summary.files_to_update
],
"conflicts": [
{
"path": str(result.file_path),
"update_path": str(result.update_path),
"current_version": result.current_version,
"template_version": result.template_version,
"current_sha256": result.current_hash,
"template_sha256": result.template_hash,
}
for result in summary.conflicts
],
"files_to_add": [str(p) for p in summary.files_to_add],
"directories_to_add": [
str(p) for p in summary.directories_to_add
@@ -798,6 +916,10 @@ def update_main(
"directories_added": [
str(p) for p in summary.directories_to_add
],
"conflicts": [
{"path": str(result.file_path), "update_path": str(result.update_path)}
for result in summary.conflicts
],
"files_skipped": [
str(result.file_path) for result in summary.files_skipped
],
@@ -808,8 +930,14 @@ def update_main(
print(
f"Update complete: {len(summary.files_to_update)} file(s) "
f"updated, {len(summary.files_to_add)} added, "
f"{len(summary.conflicts)} conflict(s), "
f"{len(summary.files_skipped)} skipped."
)
if summary.conflicts:
print(
"Merge each <stem>-update.md into its file: "
"run fiona-assistant housekeeping."
)
return 0
@@ -830,6 +958,7 @@ __all__ = [
"CORE_FILES",
"READ_ONLY_ZONES",
"SETTINGS_FILE",
"UPDATE_SUFFIX",
"FileComparisonResult",
"UpdateSummary",
"calculate_sha256",
@@ -848,5 +977,6 @@ __all__ = [
"is_read_only_file",
"is_version_newer",
"update_core_files",
"update_file_path",
"update_main",
]
+8 -4
View File
@@ -95,7 +95,7 @@ def _copy_children(source: Path, destination: Path, template_root: Path,
"""Copy every non-ignored child of source into destination."""
for item in source.iterdir():
relative = item.relative_to(template_root).as_posix()
# CURSOR: repository .gitignore matches (byte-code caches and the like)
# AI/LLM: repository .gitignore matches (byte-code caches and the like)
# are not copied into a wiki.
if any(path_matches(pattern, relative) for pattern in ignore_patterns):
continue
@@ -111,17 +111,21 @@ def _copy_children(source: Path, destination: Path, template_root: Path,
def _copy_file(source_item: Path, dest_item: Path) -> None:
"""Copy one file, replacing date placeholders in text files."""
"""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).
"""
# Read the file content
try:
with open(source_item, "r", encoding="utf-8") as f:
with open(source_item, "r", encoding="utf-8", newline="") as f:
content = f.read()
# Replace date placeholders if present
content = replace_date_placeholders(content)
# Write to destination
with open(dest_item, "w", encoding="utf-8") as f:
with open(dest_item, "w", encoding="utf-8", newline="") as f:
f.write(content)
except (UnicodeDecodeError, PermissionError):
# For binary files or files with permission issues, use shutil.copy2
+1 -1
View File
@@ -160,7 +160,7 @@ class TestConstellationThemes:
Generated by AI/LLM: 2026-09-29 - dark theme beside grayscale.
Modified by AI/LLM: 2026-09-30 - night slate instead of black.
Modified by CURSOR: 2026-09-30 - dark theme mid and high node colors.
Modified by AI/LLM: 2026-09-30 - dark theme mid and high node colors.
"""
themes = load_constellation_themes()
dark = themes["dark"]
+265
View File
@@ -0,0 +1,265 @@
"""Tests for fiona-assistant housekeeping (SPEC 4.15, 7.26).
Generated by AI/LLM: 2026-09-30 - housekeeping routine tests.
"""
from __future__ import annotations
import hashlib
import json
import shutil
from pathlib import Path
from unittest.mock import patch
import pytest
from fiona.__main__ import main
from fiona.wiki.housekeeping import (
STEP_NAMES,
format_housekeeping_report,
housekeeping_main,
run_housekeeping,
)
from fiona.wiki.wiki import get_llm_wiki_source_path
def _page(path: Path, name: str, version: str = "1.0.0", extra: str = "",
body: str = "") -> None:
"""Write a small markdown page with frontmatter at path."""
path.parent.mkdir(parents=True, exist_ok=True)
text = f"---\nname: {name}\nversion: {version}\n{extra}---\n\n# {name.capitalize()}\n"
path.write_text(text + (f"\n{body}" if body else ""), encoding="utf-8")
@pytest.fixture
def hk_wiki(tmp_path, monkeypatch):
"""A clean two-page wiki and a template that matches it."""
template = tmp_path / "template"
wiki = tmp_path / "wiki"
settings = get_llm_wiki_source_path() / "fiona-settings.json"
for root in (template, wiki):
root.mkdir()
shutil.copy2(settings, root / "fiona-settings.json")
_page(root / "AGENTS.md", "agents", "2.0.0", body="See [index](./wiki/index.md).\n")
_page(root / "wiki" / "index.md", "index", body="See [a](./a.md).\n")
_page(wiki / "wiki" / "a.md", "a", body="Back to [index](./index.md).\n")
monkeypatch.setattr(
"fiona.wiki.update_manager.get_llm_wiki_source_path", lambda: template
)
return wiki
def _step(results: dict, name: str) -> dict:
"""Return the named step from a housekeeping result."""
return next(step for step in results["steps"] if step["name"] == name)
def _hashes(root: Path) -> dict:
"""Map every file under root to its SHA-256."""
return {
path: hashlib.sha256(path.read_bytes()).hexdigest()
for path in root.rglob("*") if path.is_file()
}
class TestRunHousekeeping:
"""Tests for the housekeeping steps (SPEC 7.26)."""
def test_steps_run_in_order(self, hk_wiki):
results = run_housekeeping(hk_wiki)
assert [step["name"] for step in results["steps"]] == list(STEP_NAMES)
assert STEP_NAMES == ("check-update", "merge", "ingest", "sanity", "graph")
def test_clean_wiki_passes(self, hk_wiki):
results = run_housekeeping(hk_wiki)
assert results["passed"] is True
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."""
_page(hk_wiki / "AGENTS.md", "agents", "1.0.0", body="See [index](./wiki/index.md).\n")
step = _step(run_housekeeping(hk_wiki), "check-update")
assert step["status"] == "WARN"
assert step["summary"] == "0 update(s), 1 conflict(s), 0 addition(s)"
assert "conflict: AGENTS.md -> AGENTS-update.md" in step["details"]
assert step["next"] == [
"Ask the user, then run fiona-assistant wiki update --dry-run and wiki update --yes."
]
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."""
_page(hk_wiki / "wiki" / "schema-update.md", "schema", "1.5.0")
_page(hk_wiki / "orphan-update.md", "orphan")
step = _step(run_housekeeping(hk_wiki), "merge")
assert step["status"] == "FAIL"
assert step["summary"] == "2 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 any("1.5.0" in action and "wiki/schema-update.md" in action
for action in step["next"])
def test_merge_detail_without_missing_target(self, hk_wiki):
_page(hk_wiki / "AGENTS-update.md", "agents", "3.0.0")
step = _step(run_housekeeping(hk_wiki), "merge")
assert step["details"] == ["AGENTS-update.md -> AGENTS.md"]
def test_update_file_without_version_names_template_version(self, hk_wiki):
(hk_wiki / "AGENTS-update.md").write_text("# no frontmatter\n", encoding="utf-8")
step = _step(run_housekeeping(hk_wiki), "merge")
assert "at least the template version" in step["next"][0]
def test_read_only_zones_are_not_scanned_for_update_files(self, hk_wiki):
_page(hk_wiki / "raw" / "note-update.md", "note")
_page(hk_wiki / "personal" / "note-update.md", "note")
step = _step(run_housekeeping(hk_wiki), "merge")
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."""
_page(hk_wiki / "wiki" / "sources" / "s.md", "s", extra="status: raw\n",
body="From [index](../index.md).\n")
step = _step(run_housekeeping(hk_wiki), "ingest")
assert step["status"] == "WARN"
assert step["details"] == ["wiki/sources/s.md"]
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."""
_page(hk_wiki / "wiki" / "a.md", "a", body="See [gone](./gone.md).\n")
step = _step(run_housekeeping(hk_wiki), "sanity")
assert step["status"] == "FAIL"
assert step["summary"] == "1 violation(s) in 1 check(s)"
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."""
_page(hk_wiki / "wiki" / "lonely.md", "lonely")
_page(hk_wiki / "wiki" / "lonely-update.md", "lonely")
step = _step(run_housekeeping(hk_wiki), "graph")
assert (hk_wiki / "wiki_graph.html").is_file()
assert step["status"] == "WARN"
assert step["summary"].startswith("wrote wiki_graph.html (")
assert step["details"] == ["orphan: wiki/lonely.md"]
def test_graph_error_is_fail(self, hk_wiki):
with patch("fiona.wiki.housekeeping.wiki_graph_main", return_value=1):
step = _step(run_housekeeping(hk_wiki), "graph")
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."""
_page(hk_wiki / "AGENTS-update.md", "agents", "3.0.0")
_page(hk_wiki / "wiki" / "a.md", "a", body="See [gone](./gone.md).\n")
results = run_housekeeping(hk_wiki)
assert _step(results, "merge")["status"] == "FAIL"
assert _step(results, "sanity")["status"] == "FAIL"
assert (hk_wiki / "wiki_graph.html").is_file()
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."""
_page(hk_wiki / "AGENTS.md", "agents", "1.0.0", body="See [index](./wiki/index.md).\n")
before = _hashes(hk_wiki)
run_housekeeping(hk_wiki)
after = _hashes(hk_wiki)
after.pop(hk_wiki / "wiki_graph.html")
assert after == before
def test_missing_directory_raises(self, tmp_path):
with pytest.raises(FileNotFoundError, match="Directory not found"):
run_housekeeping(tmp_path / "nope")
def test_non_wiki_raises(self, tmp_path):
with pytest.raises(NotADirectoryError, match="not an llm-wiki directory"):
run_housekeeping(tmp_path)
class TestHousekeepingReport:
"""Tests for the human and JSON output (SPEC 4.15, 7.26.8)."""
def test_human_report_passes(self, hk_wiki):
report = format_housekeeping_report(run_housekeeping(hk_wiki))
assert report.startswith(f"Housekeeping Report\nTARGET: {hk_wiki.resolve()}\n")
assert "[PASS] merge: 0 update file(s) wait for a merge" in report
assert "Next steps:" not in report
assert report.endswith("HOUSEKEEPING PASSED")
def test_human_report_fails_with_next_steps(self, hk_wiki):
_page(hk_wiki / "AGENTS-update.md", "agents", "3.0.0")
report = format_housekeeping_report(run_housekeeping(hk_wiki))
assert "[FAIL] merge: 1 update file(s) wait for a merge" in report
assert " - AGENTS-update.md -> AGENTS.md" in report
assert "Next steps:\n - Merge AGENTS-update.md into AGENTS.md" in report
assert report.endswith("HOUSEKEEPING FAILED - 1 step(s) need attention: merge")
def test_next_steps_have_no_repeats(self):
results = {
"target": Path("/w"),
"passed": True,
"steps": [
{"name": "a", "status": "WARN", "summary": "s", "details": [], "next": ["x"]},
{"name": "b", "status": "WARN", "summary": "s", "details": [], "next": ["x"]},
],
}
assert format_housekeeping_report(results).count(" - x") == 1
def test_json_warn_only_passes(self, hk_wiki, capsys):
_page(hk_wiki / "wiki" / "lonely.md", "lonely")
code = housekeeping_main(str(hk_wiki), json_output=True)
output = json.loads(capsys.readouterr().out)
assert code == 0
assert output["passed"] is True
assert output["target"] == str(hk_wiki.resolve())
assert _step(output, "graph")["status"] == "WARN"
def test_main_exits_1_on_fail(self, hk_wiki, capsys):
_page(hk_wiki / "AGENTS-update.md", "agents", "3.0.0")
assert housekeeping_main(str(hk_wiki)) == 1
assert "HOUSEKEEPING FAILED" in capsys.readouterr().out
def test_main_reports_non_wiki(self, tmp_path, capsys):
assert housekeeping_main(str(tmp_path)) == 1
assert "is not an llm-wiki directory" in capsys.readouterr().err
class TestHousekeepingCli:
"""Tests for the fiona-assistant housekeeping command."""
def test_cli_dispatches(self, hk_wiki, capsys):
argv = ["fiona-assistant", "housekeeping", str(hk_wiki), "--json"]
with patch("sys.argv", argv), pytest.raises(SystemExit) as exc_info:
main()
assert exc_info.value.code == 0
assert json.loads(capsys.readouterr().out)["passed"] is True
+1 -1
View File
@@ -1,6 +1,6 @@
"""Tests for wiki gitignore seeding and matching.
Generated by CURSOR: 2026-09-30 - cover repository ignore patterns.
Generated by AI/LLM: 2026-09-30 - cover repository ignore patterns.
"""
from __future__ import annotations
+68
View File
@@ -0,0 +1,68 @@
"""Tests for the deployed-wiki rules in the llm-wiki template (SPEC 3.3).
Generated by AI/LLM: 2026-09-30 - the template is self-contained and
tells a deployed wiki to commit after ingest and housekeeping.
"""
from __future__ import annotations
import pathlib
import re
import pytest
from fiona.paths import llm_wiki_template
TEMPLATE = llm_wiki_template()
AGENTS = TEMPLATE / "AGENTS.md"
SKILL = TEMPLATE / "utils" / "skills" / "fiona" / "SKILL.md"
LOG = TEMPLATE / "wiki" / "log.md"
def _body(path: pathlib.Path) -> str:
"""Return the markdown text after the frontmatter block.
Generated by AI/LLM: 2026-09-30 - drop frontmatter before content checks.
"""
text = path.read_text(encoding="utf-8")
return text.split("---", 2)[2] if text.startswith("---") else text
@pytest.mark.parametrize("path", sorted(TEMPLATE.rglob("*.md")), ids=str)
@pytest.mark.parametrize("needle", ["SPEC", "project agent rule", "scripts/run_"])
def test_template_markdown_has_no_outside_reference(path: pathlib.Path, needle: str) -> None:
"""SPEC 3.3.1: template markdown never cites files outside the template.
Generated by AI/LLM: 2026-09-30 - a deployed wiki only has the template.
"""
assert needle not in path.read_text(encoding="utf-8")
@pytest.mark.parametrize("link", ["./utils/skills/fiona/SKILL.md", "./utils/skills/fiona/llm-wiki-mod.md"])
def test_agents_links_skill_and_concept(link: str) -> None:
"""SPEC 3.3.2: the entry point links the Fiona skill and llm-wiki-mod.
Generated by AI/LLM: 2026-09-30 - AGENTS.md is the wiki entry point.
"""
assert f"]({link})" in AGENTS.read_text(encoding="utf-8")
@pytest.mark.parametrize("path", [AGENTS, SKILL], ids=["AGENTS", "SKILL"])
def test_deployed_wiki_commits_after_ingest(path: pathlib.Path) -> None:
"""SPEC 3.3.3: save after ingest and housekeeping, not only when asked.
Generated by AI/LLM: 2026-09-30 - commits are the wiki's history.
"""
text = " ".join(path.read_text(encoding="utf-8").split())
assert "git save" in text
assert not re.search(r"(commit|Run them)[^.]*only when the user asked", text)
assert "Do not commit" not in text
def test_seed_log_has_one_entry() -> None:
"""SPEC 3.3.4: a new wiki's log starts with one seed bullet.
Generated by AI/LLM: 2026-09-30 - no product history in a new wiki.
"""
bullets = [line for line in _body(LOG).splitlines() if line.startswith("- ")]
assert bullets == ["- DATE_PLACEHOLDER - Initialized the llm-wiki."]
+332 -76
View File
@@ -13,6 +13,7 @@ from __future__ import annotations
import hashlib
import json
import re
import shutil
import sys
import tempfile
@@ -46,6 +47,7 @@ from fiona.wiki.update_manager import (
update_core_files,
update_main,
)
from fiona.wiki.wiki import _copy_file
# =============================================================================
# Fixtures
@@ -57,11 +59,11 @@ def temp_wiki_dir():
with tempfile.TemporaryDirectory() as tmpdir:
wiki_dir = Path(tmpdir) / "test_wiki"
wiki_dir.mkdir()
# Create a basic fiona-settings.json to mark it as an llm-wiki
settings_file = wiki_dir / "fiona-settings.json"
settings_file.write_text(json.dumps({"markdown": {"pymarkdown": {}}}, indent=2))
yield wiki_dir
@@ -71,17 +73,17 @@ def temp_template_dir():
with tempfile.TemporaryDirectory() as tmpdir:
template_dir = Path(tmpdir) / "template"
template_dir.mkdir()
# Create some template files
(template_dir / "AGENTS.md").write_text("---\nname: AGENTS\nversion: 1.0.0\n---\n# Agents")
(template_dir / "README.md").write_text("---\nname: README\nversion: 1.0.0\n---\n# README")
(template_dir / "fiona-settings.json").write_text(json.dumps({"version": "1.0.0"}, indent=2))
# Create subdirectory
wiki_subdir = template_dir / "wiki"
wiki_subdir.mkdir()
(wiki_subdir / "index.md").write_text("---\nname: index\nversion: 1.0.0\n---\n# Index")
yield template_dir
@@ -90,19 +92,19 @@ def mock_wiki_root():
"""Create a mock wiki root with some files."""
with tempfile.TemporaryDirectory() as tmpdir:
wiki_root = Path(tmpdir)
# Create core files
(wiki_root / "AGENTS.md").write_text("---\nname: AGENTS\nversion: 1.0.0\n---\n# Agents")
(wiki_root / "fiona-settings.json").write_text(json.dumps({"version": "1.0.0"}, indent=2))
# Create user file (not core)
(wiki_root / "user_notes.md").write_text("# User Notes")
# Create read-only zone
personal_dir = wiki_root / "personal"
personal_dir.mkdir()
(personal_dir / "private.md").write_text("# Private")
yield wiki_root
@@ -116,7 +118,7 @@ class TestFileComparisonResult:
def test_default_values(self):
"""Test that default values are set correctly."""
result = FileComparisonResult(file_path=Path("/test/file.md"))
assert result.file_path == Path("/test/file.md")
assert result.is_core_file is False
assert result.has_template_version is False
@@ -131,7 +133,7 @@ class TestFileComparisonResult:
def test_needs_update_when_new_file(self):
"""Test that new files are marked as needing update."""
result = FileComparisonResult(file_path=Path("/test/file.md"), is_new_file=True)
assert result.needs_update is True
def test_custom_values(self):
@@ -144,7 +146,7 @@ class TestFileComparisonResult:
template_version="2.0.0",
needs_update=True
)
assert result.is_core_file is True
assert result.has_template_version is True
assert result.current_version == "1.0.0"
@@ -158,7 +160,7 @@ class TestUpdateSummary:
def test_empty_summary(self):
"""Test empty update summary."""
summary = UpdateSummary()
assert summary.files_to_update == []
assert summary.files_to_add == []
assert summary.settings_file is None
@@ -175,12 +177,12 @@ class TestUpdateSummary:
file_path=Path("/test/file2.md"),
needs_update=True
)
summary = UpdateSummary(
files_to_update=[result1, result2],
files_to_add=[Path("/test/new_file.md")]
)
assert len(summary.files_to_update) == 2
assert len(summary.files_to_add) == 1
assert summary.has_updates is True
@@ -191,7 +193,7 @@ class TestUpdateSummary:
summary = UpdateSummary(
settings_file=Path("/test/fiona-settings.json")
)
assert summary.settings_file == Path("/test/fiona-settings.json")
@@ -206,12 +208,12 @@ class TestCalculateSha256:
"""Test SHA256 hash calculation for a file."""
test_file = tmp_path / "test.txt"
test_file.write_text("test content")
result = calculate_sha256(test_file)
# Calculate expected hash
expected = hashlib.sha256(b"test content").hexdigest()
assert result == expected
assert len(result) == 64 # SHA256 hash is 64 hex characters
@@ -261,7 +263,7 @@ class TestIsReadOnlyFile:
personal_dir.mkdir()
file_path = personal_dir / "private.md"
file_path.write_text("test")
assert is_read_only_file(file_path, temp_wiki_dir) is True
def test_raw_zone(self, temp_wiki_dir):
@@ -270,14 +272,14 @@ class TestIsReadOnlyFile:
raw_dir.mkdir()
file_path = raw_dir / "data.json"
file_path.write_text("test")
assert is_read_only_file(file_path, temp_wiki_dir) is True
def test_non_read_only_file(self, temp_wiki_dir):
"""Test that files outside read-only zones are not read-only."""
file_path = temp_wiki_dir / "AGENTS.md"
file_path.write_text("test")
assert is_read_only_file(file_path, temp_wiki_dir) is False
def test_file_outside_wiki_not_read_only(self, temp_wiki_dir):
@@ -314,13 +316,13 @@ class TestCompareMdFile:
"""Test comparing files with identical versions."""
wiki_file = tmp_path / "file.md"
template_file = tmp_path / "template.md"
content = "---\nname: Test\nversion: 1.0.0\n---\n# Content"
wiki_file.write_text(content)
template_file.write_text(content)
result = compare_md_file(wiki_file, template_file)
assert result.file_path == wiki_file
assert result.is_core_file is True
assert result.has_template_version is True
@@ -330,15 +332,15 @@ class TestCompareMdFile:
"""Test comparing files with different versions."""
wiki_file = tmp_path / "file.md"
template_file = tmp_path / "template.md"
wiki_content = "---\nname: Test\nversion: 1.0.0\n---\n# Content"
template_content = "---\nname: Test\nversion: 2.0.0\n---\n# Content"
wiki_file.write_text(wiki_content)
template_file.write_text(template_content)
result = compare_md_file(wiki_file, template_file)
assert result.file_path == wiki_file
assert result.is_core_file is True
@@ -350,13 +352,13 @@ class TestCompareNonMdFile:
"""Test comparing JSON files using hash."""
wiki_file = tmp_path / "settings.json"
template_file = tmp_path / "template_settings.json"
content = json.dumps({"version": "1.0.0"}, indent=2)
wiki_file.write_text(content)
template_file.write_text(content)
result = compare_non_md_file(wiki_file, template_file)
assert result.file_path == wiki_file
assert result.is_core_file is True
assert result.has_template_version is False
@@ -369,15 +371,15 @@ class TestCompareSettingsFile:
"""Test comparing settings files."""
wiki_settings = tmp_path / "fiona-settings.json"
template_settings = tmp_path / "template_settings.json"
wiki_content = json.dumps({"version": "1.0.0", "custom": "value"}, indent=2)
template_content = json.dumps({"version": "2.0.0", "new_setting": "new"}, indent=2)
wiki_settings.write_text(wiki_content)
template_settings.write_text(template_content)
result = compare_settings_file(wiki_settings, template_settings)
assert result.file_path == wiki_settings
assert result.is_core_file is True
assert result.is_settings_file is True
@@ -393,7 +395,7 @@ class TestGetAllTemplateFiles:
def test_get_all_template_files(self, temp_template_dir):
"""Test getting all files from template directory."""
files = get_all_template_files(temp_template_dir)
# Should return a list (may be empty in stub)
assert isinstance(files, list)
@@ -405,9 +407,9 @@ class TestFindMissingCoreFiles:
"""Test finding files that exist in template but not in wiki."""
# Create a file in template that doesn't exist in wiki
(temp_template_dir / "new_file.md").write_text("---\nname: New\nversion: 1.0.0\n---\n# New")
missing = find_missing_core_files(temp_wiki_dir, temp_template_dir)
# Should return a list (may be empty in stub)
assert isinstance(missing, list)
@@ -423,9 +425,19 @@ class TestCheckWikiUpdates:
"""Test checking a pristine wiki (no updates needed)."""
# A wiki created by init should have no updates needed
summary = check_wiki_updates(str(temp_wiki_dir))
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).
Generated by AI/LLM: 2026-09-30 - init must keep template line endings.
"""
summary = check_wiki_updates(pristine_wiki)
assert [r.file_path.name for r in summary.files_to_update] == []
assert summary.has_updates is False
def test_check_nonexistent_directory(self):
"""Test checking a non-existent directory."""
with pytest.raises(FileNotFoundError):
@@ -436,7 +448,7 @@ class TestCheckWikiUpdates:
# Create a directory without fiona-settings.json
non_wiki_dir = tmp_path / "non_wiki"
non_wiki_dir.mkdir()
with pytest.raises(NotADirectoryError):
check_wiki_updates(str(non_wiki_dir))
@@ -447,10 +459,10 @@ class TestCheckWikiUpdates:
wiki_dir = tmp_path / "wiki"
wiki_dir.mkdir()
(wiki_dir / "fiona-settings.json").write_text(json.dumps({}))
# Mock get_llm_wiki_source_path to return non-existent path
mock_get_source.return_value = Path("/nonexistent/template")
with pytest.raises(FileNotFoundError, match="Template directory not found"):
check_wiki_updates(str(wiki_dir))
@@ -466,7 +478,7 @@ class TestFormatCheckUpdateOutput:
"""Test formatting an empty summary."""
summary = UpdateSummary()
output = format_check_update_output(summary)
assert "Wiki is up to date" in output
def test_format_summary_with_updates(self):
@@ -479,9 +491,9 @@ class TestFormatCheckUpdateOutput:
files_to_update=[result],
files_to_add=[Path("/test/new_file.md")]
)
output = format_check_update_output(summary)
assert "Files to update: 1" in output
assert "Files to add: 1" in output
assert "Total: 2" in output
@@ -497,13 +509,13 @@ class TestUpdateCoreFiles:
def test_update_no_changes_needed(self, temp_wiki_dir):
"""Test updating when no changes are needed."""
summary = update_core_files(str(temp_wiki_dir), force=True)
assert isinstance(summary, UpdateSummary)
def test_update_with_force(self, temp_wiki_dir):
"""Test updating with force flag."""
summary = update_core_files(str(temp_wiki_dir), force=True)
assert isinstance(summary, UpdateSummary)
def test_update_without_force_raises(self, temp_wiki_dir):
@@ -530,22 +542,22 @@ class TestCopySettingsWithPreservation:
"""Test that user settings are preserved during update."""
wiki_settings = tmp_path / "wiki_settings.json"
template_settings = tmp_path / "template_settings.json"
wiki_content = json.dumps({
"version": "1.0.0",
"markdown": {"pymarkdown": {"line_length": 120}},
"user_custom": "value"
}, indent=2)
template_content = json.dumps({
"version": "2.0.0",
"markdown": {"pymarkdown": {"line_length": 100}},
"new_setting": "new"
}, indent=2)
wiki_settings.write_text(wiki_content)
template_settings.write_text(template_content)
# This is a stub, so it just shouldn't crash
copy_settings_with_preservation(wiki_settings, template_settings)
@@ -560,19 +572,19 @@ class TestCheckUpdateMain:
def test_check_update_main_default(self, temp_wiki_dir):
"""Test check-update main with default arguments."""
result = check_update_main(directory=str(temp_wiki_dir))
assert result == 0
def test_check_update_main_json(self, temp_wiki_dir):
"""Test check-update main with JSON output."""
result = check_update_main(directory=str(temp_wiki_dir), json_output=True)
assert result == 0
def test_check_update_main_nonexistent(self):
"""Test check-update main with non-existent directory."""
result = check_update_main(directory="/nonexistent")
assert result == 1
@@ -630,7 +642,7 @@ class TestUpdateMain:
def test_update_main_nonexistent(self):
"""Test update main with non-existent directory."""
result = update_main(directory="/nonexistent")
assert result == 1
@patch("fiona.wiki.update_manager.update_core_files")
@@ -640,12 +652,12 @@ class TestUpdateMain:
wiki_dir = tmp_path / "wiki"
wiki_dir.mkdir()
(wiki_dir / "fiona-settings.json").write_text(json.dumps({}))
# Mock update_core_files to raise RuntimeError
mock_update.side_effect = RuntimeError("Test error")
result = update_main(directory=str(wiki_dir))
assert result == 1
@@ -767,7 +779,8 @@ class TestCompareMdFileVersions:
assert result.current_version == "1.0.0"
assert result.template_version == "1.0.0"
def test_newer_template_needs_update(self, tmp_path):
def test_newer_template_is_conflict(self, tmp_path):
"""Test a newer template is a conflict, never an overwrite (SPEC 7.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")
@@ -775,7 +788,9 @@ class TestCompareMdFileVersions:
result = compare_md_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 == tmp_path / "file-update.md"
assert result.is_locally_modified is False
assert result.current_version == "1.0.0"
assert result.template_version == "2.0.0"
@@ -808,11 +823,13 @@ class TestCompareMdFileVersions:
wiki_file.write_text("plain text\n", encoding="utf-8")
template_file.write_text("plain text\n", encoding="utf-8")
assert compare_md_file(wiki_file, template_file).needs_update is False
assert compare_md_file(wiki_file, template_file).is_conflict is False
template_file.write_text("changed text\n", encoding="utf-8")
assert compare_md_file(wiki_file, template_file).needs_update is True
result = compare_md_file(wiki_file, template_file)
assert result.is_conflict is True
assert result.needs_update is False
class TestCompareNonMdFileHashes:
@@ -990,18 +1007,41 @@ class TestCheckWikiUpdatesImplemented:
assert summary.files_skipped == []
assert summary.directories_to_add == []
def test_outdated_md_reported_with_versions(self, template_wiki_pair):
def test_outdated_md_reported_as_conflict(self, template_wiki_pair):
_template, wiki = template_wiki_pair
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
summary = check_wiki_updates(str(wiki))
assert summary.has_updates is True
assert len(summary.files_to_update) == 1
result = summary.files_to_update[0]
assert summary.files_to_update == []
assert len(summary.conflicts) == 1
result = summary.conflicts[0]
assert result.file_path == (wiki / "AGENTS.md").resolve()
assert result.update_path == (wiki / "AGENTS-update.md").resolve()
assert result.current_version == "1.0.0"
assert result.template_version == "2.0.0"
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)."""
_template, wiki = template_wiki_pair
_write_md(wiki / "wiki" / "index.md", "0.1.0", body="# User index\n", name="index")
summary = check_wiki_updates(str(wiki))
assert [r.update_path for r in summary.conflicts] == [
(wiki / "wiki" / "index-update.md").resolve()
]
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)."""
_template, wiki = template_wiki_pair
_write_md(wiki / "AGENTS.md", "2.0.0", body="# Merged agents\n", name="agents")
summary = check_wiki_updates(str(wiki))
assert summary.conflicts == []
def test_missing_file_reported_as_add(self, template_wiki_pair):
_template, wiki = template_wiki_pair
@@ -1073,16 +1113,18 @@ class TestCheckWikiUpdatesImplemented:
assert summary.has_updates is False
def test_wiki_pages_stay_out_of_the_report(self, template_wiki_pair):
"""Test an edited wiki page is not an update, add, or skip."""
"""Test a newer wiki page is not an update, add, skip, or conflict."""
_template, wiki = template_wiki_pair
_write_md(
wiki / "wiki" / "index.md", "0.1.0", body="# User index\n", name="index"
wiki / "wiki" / "index.md", "3.0.0", body="# User index\n", name="index"
)
(wiki / "wiki" / "queries" / ".gitkeep").write_text("local", encoding="utf-8")
summary = check_wiki_updates(str(wiki))
reported = [result.file_path.as_posix() for result in summary.files_to_update]
reported += [result.file_path.as_posix() for result in summary.files_skipped]
reported += [result.file_path.as_posix() for result in summary.conflicts]
reported += [path.as_posix() for path in summary.files_to_add]
reported += [path.as_posix() for path in summary.directories_to_add]
assert not any(
@@ -1142,16 +1184,59 @@ class TestCheckWikiUpdatesImplemented:
class TestUpdateCoreFilesImplemented:
"""Tests for performing the actual update."""
def test_yes_updates_outdated_file(self, template_wiki_pair):
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)."""
_template, wiki = template_wiki_pair
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
owner = "---\nname: agents\nversion: 1.0.0\n---\n# Agents v1\n"
(wiki / "AGENTS.md").write_text(owner, encoding="utf-8")
summary = update_core_files(str(wiki), yes=True)
assert (wiki / "AGENTS.md").read_text(encoding="utf-8") == (
assert (wiki / "AGENTS.md").read_text(encoding="utf-8") == owner
assert (wiki / "AGENTS-update.md").read_text(encoding="utf-8") == (
"---\nname: agents\nversion: 2.0.0\n---\n# Agents v2\n"
)
assert len(summary.files_to_update) == 1
assert len(summary.conflicts) == 1
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)."""
template, wiki = template_wiki_pair
_write_md(
template / "README.md", "2.0.0",
body="updated: DATE_PLACEHOLDER\n", name="readme",
)
update_core_files(str(wiki), yes=True)
first = (wiki / "README-update.md").read_bytes()
update_core_files(str(wiki), yes=True)
assert b"DATE_PLACEHOLDER" not in first
assert (wiki / "README-update.md").read_bytes() == first
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)."""
_template, wiki = template_wiki_pair
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
assert update_main(directory=str(wiki), dry_run=True) == 0
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)."""
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"
(wiki / "wiki" / "schema.md").write_text(owner, encoding="utf-8")
before = {p for p in wiki.rglob("*") if p.is_file()}
update_core_files(str(wiki), yes=True)
after = {p for p in wiki.rglob("*") if p.is_file()}
assert after - before == {wiki / "wiki" / "schema-update.md"}
assert (wiki / "wiki" / "schema.md").read_text(encoding="utf-8") == owner
def test_yes_adds_missing_file_and_directory(self, template_wiki_pair):
template, wiki = template_wiki_pair
@@ -1177,6 +1262,9 @@ class TestUpdateCoreFilesImplemented:
update_core_files(str(wiki), yes=True)
assert (wiki / "wiki" / "index.md").read_text(encoding="utf-8") == user
assert (wiki / "wiki" / "index-update.md").read_text(encoding="utf-8") == (
"---\nname: index\nversion: 1.0.0\n---\n# Index\n"
)
assert not (wiki / "wiki" / "queries").exists()
def test_yes_leaves_gitignored_file_unchanged(self, template_wiki_pair):
@@ -1248,7 +1336,7 @@ class TestUpdateCoreFilesImplemented:
update_core_files(str(wiki))
assert "version: 2.0.0" in (wiki / "AGENTS.md").read_text(encoding="utf-8")
assert "version: 2.0.0" in (wiki / "AGENTS-update.md").read_text(encoding="utf-8")
def test_interactive_confirmation_declined(
self, template_wiki_pair, monkeypatch
@@ -1300,8 +1388,12 @@ class TestCheckUpdateMainJson:
assert result == 0
assert output["has_updates"] is True
assert output["files_to_update"][0]["current_version"] == "1.0.0"
assert output["files_to_update"][0]["template_version"] == "2.0.0"
assert output["files_to_update"] == []
conflict = output["conflicts"][0]
assert conflict["current_version"] == "1.0.0"
assert conflict["template_version"] == "2.0.0"
assert conflict["update_path"].endswith("AGENTS-update.md")
assert output["total"] == 1
def test_json_reports_skipped_files(self, template_wiki_pair, capsys):
_template, wiki = template_wiki_pair
@@ -1341,10 +1433,24 @@ class TestUpdateMainJsonImplemented:
output = json.loads(capsys.readouterr().out)
assert result == 0
assert len(output["files_updated"]) == 1
assert output["files_updated"] == []
assert len(output["files_added"]) == 1
assert output["conflicts"][0]["update_path"].endswith("AGENTS-update.md")
assert output["files_skipped"] == []
def test_human_output_reports_conflicts(self, template_wiki_pair, capsys):
"""Test the success line counts conflicts and names housekeeping."""
_template, wiki = template_wiki_pair
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
assert update_main(directory=str(wiki), yes=True) == 0
out = capsys.readouterr().out
assert "Conflicts (owner copy kept): 1" in out
assert "AGENTS.md (1.0.0 -> 2.0.0) -> AGENTS-update.md" in out
assert "0 file(s) updated, 0 added, 1 conflict(s), 0 skipped." in out
assert "run fiona-assistant housekeeping" in out
class TestFormatCheckUpdateOutputSkipped:
"""Tests for skipped files in the formatted output."""
@@ -1372,3 +1478,153 @@ class TestFormatCheckUpdateOutputSkipped:
assert "Wiki is up to date" in output
assert "Files skipped" in output
# =============================================================================
# SHA-256 comparison for files without a version (SPEC 7.2.12)
# Generated by AI/LLM: 2026-09-30 - hash compare and short-hash report.
# =============================================================================
HEX64 = r"^[0-9a-f]{64}$"
def _sha(text: str) -> str:
"""Return the SHA-256 hex digest of UTF-8 text."""
return hashlib.sha256(text.encode("utf-8")).hexdigest()
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)."""
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")
_copy_file(template_file, wiki_file)
result = compare_non_md_file(wiki_file, template_file)
assert result.needs_update is False
assert result.current_hash == result.template_hash
def test_binary_template_hashes_raw_bytes(self, tmp_path):
template_file = tmp_path / "template.bin"
wiki_file = tmp_path / "blob.bin"
template_file.write_bytes(b"\xff\xfe\x00DATE_PLACEHOLDER")
wiki_file.write_bytes(b"\xff\xfe\x00DATE_PLACEHOLDER")
result = compare_non_md_file(wiki_file, template_file)
assert result.needs_update is False
assert result.template_hash == calculate_sha256(template_file)
def test_unversioned_md_equal_is_up_to_date(self, tmp_path):
wiki_file = tmp_path / "file.md"
template_file = tmp_path / "template.md"
wiki_file.write_text("plain\n", encoding="utf-8", newline="\n")
template_file.write_text("plain\n", encoding="utf-8", newline="\n")
result = compare_md_file(wiki_file, template_file)
assert result.is_conflict is False
assert result.current_hash == _sha("plain\n")
assert result.template_hash == _sha("plain\n")
def test_unversioned_md_differs_is_conflict_with_hashes(self, tmp_path):
wiki_file = tmp_path / "file.md"
template_file = tmp_path / "template.md"
wiki_file.write_text("mine\n", encoding="utf-8", newline="\n")
template_file.write_text("theirs\n", encoding="utf-8", newline="\n")
result = compare_md_file(wiki_file, template_file)
assert result.is_conflict is True
assert result.current_hash == _sha("mine\n")
assert result.template_hash == _sha("theirs\n")
def test_versioned_md_has_no_hashes(self, tmp_path):
wiki_file = tmp_path / "file.md"
template_file = tmp_path / "template.md"
_write_md(wiki_file, "1.0.0")
_write_md(template_file, "2.0.0")
result = compare_md_file(wiki_file, template_file)
assert result.current_hash is None
assert result.template_hash is None
class TestSha256Report:
"""Tests for the short-hash detail in the update report (SPEC 7.2.12.2)."""
def test_update_line_shows_short_hashes(self):
result = FileComparisonResult(
file_path=Path("utils/scripts/example.py"),
current_hash="1a2b3c4d" + "0" * 56,
template_hash="9f8e7d6c" + "0" * 56,
needs_update=True,
)
output = format_check_update_output(UpdateSummary(files_to_update=[result]))
assert "example.py (sha256 1a2b3c4d -> 9f8e7d6c)" in output
assert "0" * 56 not in output
def test_conflict_line_shows_short_hashes(self):
result = FileComparisonResult(
file_path=Path("notes.md"),
current_hash="aaaaaaaa" + "1" * 56,
template_hash="bbbbbbbb" + "1" * 56,
is_conflict=True,
update_path=Path("notes-update.md"),
)
output = format_check_update_output(UpdateSummary(conflicts=[result]))
assert "notes.md (sha256 aaaaaaaa -> bbbbbbbb) -> notes-update.md" in output
def test_version_line_keeps_versions(self):
result = FileComparisonResult(
file_path=Path("AGENTS.md"),
current_version="1.0.0",
template_version="2.0.0",
is_conflict=True,
update_path=Path("AGENTS-update.md"),
)
output = format_check_update_output(UpdateSummary(conflicts=[result]))
assert "AGENTS.md (1.0.0 -> 2.0.0) -> AGENTS-update.md" in output
assert "sha256" not in output
def test_drifted_script_listed_with_hashes(self, template_wiki_pair, capsys):
template, wiki = template_wiki_pair
script = Path("utils") / "scripts" / "example.py"
(template / script).parent.mkdir(parents=True, exist_ok=True)
(template / script).write_text("print('new')\n", encoding="utf-8", newline="\n")
(wiki / script).parent.mkdir(parents=True, exist_ok=True)
(wiki / script).write_text("print('old')\n", encoding="utf-8", newline="\n")
assert check_update_main(directory=str(wiki)) == 0
out = capsys.readouterr().out
short_cur = _sha("print('old')\n")[:8]
short_tmpl = _sha("print('new')\n")[:8]
assert f"(sha256 {short_cur} -> {short_tmpl})" in out
def test_json_carries_full_hashes(self, template_wiki_pair, capsys):
template, wiki = template_wiki_pair
script = Path("utils") / "scripts" / "example.py"
(template / script).parent.mkdir(parents=True, exist_ok=True)
(template / script).write_text("print('new')\n", encoding="utf-8", newline="\n")
(wiki / script).parent.mkdir(parents=True, exist_ok=True)
(wiki / script).write_text("print('old')\n", encoding="utf-8", newline="\n")
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
assert check_update_main(directory=str(wiki), json_output=True) == 0
output = json.loads(capsys.readouterr().out)
entry = output["files_to_update"][0]
assert re.match(HEX64, entry["current_sha256"])
assert entry["template_sha256"] == _sha("print('new')\n")
conflict = output["conflicts"][0]
assert conflict["current_sha256"] is None
assert conflict["template_sha256"] is None