diff --git a/AGENTS.md b/AGENTS.md index 14f799d..04322e7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 --- ``` diff --git a/SPEC.md b/SPEC.md index edfefbd..d29f71f 100644 --- a/SPEC.md +++ b/SPEC.md @@ -1,6 +1,6 @@ --- name: Fiona-Assistant Specification -version: 0.91.1 +version: 0.96.0 title: Project Spec Sheet created: 2026-09-23 updated: 2026-09-30 @@ -18,6 +18,7 @@ type: summary - [3. llm-wiki Template](#3-llm-wiki-template) - [3.1. What Counts as a Wiki](#31-what-counts-as-a-wiki) - [3.2. Core Files and Read-only Zones](#32-core-files-and-read-only-zones) + - [3.3. Deployed Wiki Rules](#33-deployed-wiki-rules) - [4. Command Catalog](#4-command-catalog) - [4.1. librarian](#41-librarian) - [4.2. librarian toc](#42-librarian-toc) @@ -32,6 +33,8 @@ type: summary - [4.11. wiki sanity](#411-wiki-sanity) - [4.12. wiki graph](#412-wiki-graph) - [4.13. Repository runners](#413-repository-runners) + - [4.14. wiki ingest](#414-wiki-ingest) + - [4.15. housekeeping](#415-housekeeping) - [5. Settings Schema](#5-settings-schema) - [5.1. fiona-settings.json](#51-fiona-settingsjson) - [5.2. settings_dev.json](#52-settings_devjson) @@ -68,6 +71,8 @@ type: summary - [7.22. Tool Roles](#722-tool-roles) - [7.23. Wiki Root Discovery](#723-wiki-root-discovery) - [7.24. Bootstrap install modes](#724-bootstrap-install-modes) + - [7.25. wiki ingest](#725-wiki-ingest) + - [7.26. housekeeping](#726-housekeeping) - [8. Non-Goals](#8-non-goals) - [9. Priority Order](#9-priority-order) - [10. Open Questions](#10-open-questions) @@ -85,7 +90,14 @@ numbers nested requirements such as `7.16.1.1`. Revision 0.40.4 adds the PYC001 exception in *6.4.2.*. Revision 0.41.0 installs one `fiona` package and keeps tests and repo scripts outside it. Revision 0.90.0 specifies `node_importance_min_point` in *7.4.16.* -and leaves that requirement unbuilt. +and leaves that requirement unbuilt. Revision 0.92.0 specifies +`wiki ingest` in *7.25.* and leaves it unbuilt. Revision 0.93.0 adds +SHA-256 reuse across `raw/`, the complete `ingest` frontmatter map, +and the agent metadata check. Revision 0.94.0 makes `wiki update` +yield to the owner's markdown and write `-update.md` instead +(*7.2.11.*), and adds `fiona-assistant housekeeping` (*7.26.*). +Revision 0.96.0 compares a file without a version by SHA-256 and +shows both short hashes in the update report (*7.2.12.*). Each feature section starts with a `Status` line. Requirements use `- *N.M.K.*`. Each `*acceptance*` sits under the requirement it tests. @@ -135,9 +147,16 @@ These apply to every feature. - *acceptance*: `wiki update` on a non-TTY declines unless `--force` or `--yes` is set. - *1.2.3.* `personal/` and `raw/` are read-only for every automated - tool. Tools may resolve links that point into those zones. + tool. Tools may resolve links that point into those zones. The one + exception is `wiki ingest` (*7.25.3.*): it may add a new file under + `raw/`. It never modifies, renames, or deletes a file already there. - *acceptance*: `wiki update` leaves every file under `personal/` and `raw/` byte-for-byte unchanged. + - *acceptance*: A second `wiki ingest` run leaves every file that + was already under `raw/` byte-for-byte unchanged. + - *acceptance*: Ingesting bytes whose SHA-256 matches any file + already under `raw/`, from any path or URL, adds no file under + `raw/` (*7.25.3.3.*). - *1.2.4.* Code changes follow test-first development. `python scripts/run_tests.py` is green, then `python scripts/run_sanity.py` is green, before a change is finished. @@ -177,7 +196,8 @@ Runtime dependencies: Development extras: `pytest>=7.0`, `pytest-cov>=4.0`, `pytest-mock`, `pylint`. `html5validator` is not a dependency until section 7.17 -is implemented. +is implemented. `beautifulsoup4`, `markdownify`, and `pypdf` become +runtime dependencies when section 7.25 is implemented. One importable package, `fiona`, lives under `src/fiona/`. Its subpackages are `librarian`, `mdoctor`, `customlinter`, @@ -296,12 +316,16 @@ Read-only zones, including the zone directory itself: - `raw/` `wiki/` is copied by `wiki init` and then left to the LLM. -`wiki update` does not add, replace, or report any path under -`wiki/`. +`wiki update` does not add, replace, or delete any path under +`wiki/`. The only file it writes there is an update file for a +template page that is newer than the wiki's copy (*7.2.11.*). `wiki update` adds missing core files and directories. It never -deletes user files. It never writes inside a read-only zone, so a -missing file under `personal/` or `raw/` is not added back. It +overwrites an existing markdown file: when the template carries a +newer version, it writes `-update.md` beside the file and +leaves the owner's file as it is. It never deletes user files. It +never writes inside a read-only zone, so a missing file under +`personal/` or `raw/` is not added back. It never writes a path matched by the repository `.gitignore` or by the wiki's own `.gitignore`. @@ -328,6 +352,35 @@ the copy still counts as success and stdout adds - *acceptance*: An existing `README.md` alone is enough to refuse, and that file's bytes are unchanged. +### 3.3. Deployed Wiki Rules + +> Status: Implemented + +Only the template tree is deployed. A wiki does not know this spec, +the root `AGENTS.md`, `scripts/`, or `tests/`. The template +`AGENTS.md` is the entry point: it says what the wiki is and loads +the Fiona skill, which loads `llm-wiki-mod.md`. The product rule +"never commit without permission" (project agent rule 2.4) covers +this repository only. + +- *3.3.1.* No markdown file in the template references a file or + rule outside the template: `SPEC`, `project agent rule`, or + `scripts/run_`. + - *acceptance*: A scan of every template `*.md` finds none of those + strings. +- *3.3.2.* The template `AGENTS.md` links the Fiona skill and + `llm-wiki-mod.md`. + - *acceptance*: Both relative links appear in that file. +- *3.3.3.* A deployed wiki commits with + `fiona-assistant git save --description TEXT` after each ingest + cycle and each housekeeping pass. `clean`, `undo`, and `restore` + run only when the user asks. + - *acceptance*: The template `AGENTS.md` and the Fiona skill both + contain `git save`, and neither says to commit only when asked. +- *3.3.4.* The template `wiki/log.md` holds one seed entry dated + `DATE_PLACEHOLDER`. + - *acceptance*: The log body has exactly one bullet. + --- ## 4. Command Catalog @@ -508,6 +561,8 @@ When something differs, the lines that apply: ```text Files to update: - ( ->