From 9e98390f2bacd10b7aa16cb23cf923d7d72c9743 Mon Sep 17 00:00:00 2001 From: nvaldez Date: Thu, 1 Oct 2026 11:36:20 +0200 Subject: [PATCH] =?UTF-8?q?Version=201.=C2=851.0=20SPEC=20subsection=20imp?= =?UTF-8?q?rovement,=20and=20wiki=20update=20refinement?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 8 +- SPEC.md | 1731 +++++++++-------- pyproject.toml | 2 +- scripts/bootstrap_install.py | 2 +- src/fiona/__main__.py | 2 +- .../data/llm_wiki/utils/skills/fiona/SKILL.md | 46 +- src/fiona/librarian/toc_generator.py | 6 +- src/fiona/logging_config.py | 4 +- src/fiona/run_sanity.py | 6 +- src/fiona/sanity_runner/__init__.py | 2 +- src/fiona/sanity_runner/sanity_runner.py | 10 +- src/fiona/wiki/housekeeping.py | 50 +- src/fiona/wiki/ingest/__init__.py | 2 +- src/fiona/wiki/ingest/archiver.py | 4 +- src/fiona/wiki/ingest/converters/__init__.py | 2 +- src/fiona/wiki/ingest/converters/base.py | 6 +- src/fiona/wiki/ingest/converters/html.py | 4 +- src/fiona/wiki/ingest/converters/markdown.py | 2 +- src/fiona/wiki/ingest/converters/pdf.py | 6 +- src/fiona/wiki/ingest/converters/text.py | 2 +- src/fiona/wiki/ingest/fetchers.py | 10 +- src/fiona/wiki/ingest/log_writer.py | 2 +- src/fiona/wiki/ingest/media.py | 2 +- src/fiona/wiki/ingest/models.py | 8 +- src/fiona/wiki/ingest/page_writer.py | 10 +- src/fiona/wiki/ingest/pipeline.py | 16 +- src/fiona/wiki/sanity_manager.py | 20 +- src/fiona/wiki/update_manager.py | 58 +- src/fiona/wiki/wiki.py | 4 +- tests/test_bootstrap_install.py | 6 +- tests/test_fiona_main.py | 6 +- tests/test_housekeeping.py | 27 +- tests/test_ingest.py | 46 +- tests/test_ingest_edges.py | 2 +- tests/test_logging_config.py | 2 +- tests/test_run_sanity.py | 4 +- tests/test_sanity_manager.py | 12 +- tests/test_sanity_runner.py | 2 +- tests/test_toc_generator.py | 6 +- tests/test_update_manager.py | 49 +- todo.md | 84 +- 41 files changed, 1179 insertions(+), 1094 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 04322e7..31a0af9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,10 @@ --- name: Fiona-Assistant Development Agent Rules -version: 1.9.1 +version: 1.9.2 title: Agents type: summary created: 2025-09-23 -updated: 2026-09-30 +updated: 2026-10-01 tags: [agents, rules, guidelines, llm, ai] sources: [] --- @@ -103,7 +103,7 @@ Before step 2, load the environment (project agent rule 3.1). - Semver: patch for a clarification, minor for a new rule or requirement, major for a breaking contract change. - Bump [SPEC](./SPEC.md) when step 1 or step 4 changed it. - - Python and shell files have no version tag yet (SPEC 4.8.1). + - Python and shell files have no version tag yet (SPEC 7.3.2.1). Leave them untagged. A documentation edit that does not change product behavior still @@ -422,7 +422,7 @@ llm: - reasoning: high # when the model reports a level contested: true contradictions: [other-page-slug] -# written by wiki ingest (SPEC 7.25), optional: +# written by wiki ingest (SPEC 7.1.5), optional: status: raw | refined source_meta: {author: Name} # metadata read from the source ingest: # provenance; every key always present diff --git a/SPEC.md b/SPEC.md index 034e885..1715ce3 100644 --- a/SPEC.md +++ b/SPEC.md @@ -1,9 +1,9 @@ --- name: Fiona-Assistant Specification -version: 0.99.0 +version: 1.1.0 title: Project Spec Sheet created: 2026-09-23 -updated: 2026-09-30 +updated: 2026-10-01 type: summary --- @@ -21,20 +21,21 @@ type: summary - [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) - - [4.3. mdoctor](#43-mdoctor) - - [4.4. fmlint](#44-fmlint) - - [4.5. python-ruff](#45-python-ruff) - - [4.6. json-lint](#46-json-lint) - - [4.7. git](#47-git) - - [4.8. wiki init](#48-wiki-init) - - [4.9. wiki check-update](#49-wiki-check-update) - - [4.10. wiki update](#410-wiki-update) - - [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) + - [4.1.1. librarian toc](#411-librarian-toc) + - [4.2. mdoctor](#42-mdoctor) + - [4.3. fmlint](#43-fmlint) + - [4.4. python-ruff](#44-python-ruff) + - [4.5. json-lint](#45-json-lint) + - [4.6. git](#46-git) + - [4.7. wiki](#47-wiki) + - [4.7.1. wiki init](#471-wiki-init) + - [4.7.2. wiki check-update](#472-wiki-check-update) + - [4.7.3. wiki update](#473-wiki-update) + - [4.7.4. wiki sanity](#474-wiki-sanity) + - [4.7.5. wiki graph](#475-wiki-graph) + - [4.7.6. wiki ingest](#476-wiki-ingest) + - [4.8. housekeeping](#48-housekeeping) + - [4.9. Repository runners](#49-repository-runners) - [5. Settings Schema](#5-settings-schema) - [5.1. fiona-settings.json](#51-fiona-settingsjson) - [5.2. settings_dev.json](#52-settings_devjson) @@ -47,36 +48,38 @@ type: summary - [6.5. JSN Codes](#65-jsn-codes) - [6.6. Base Linter Contract](#66-base-linter-contract) - [7. Feature Requirements](#7-feature-requirements) - - [7.1. wiki init](#71-wiki-init) - - [7.2. wiki update](#72-wiki-update) - - [7.3. wiki sanity](#73-wiki-sanity) - - [7.4. wiki graph](#74-wiki-graph) - - [7.5. Git Operations](#75-git-operations) - - [7.6. Backup Script](#76-backup-script) - - [7.7. mdoctor](#77-mdoctor) - - [7.8. fmlint](#78-fmlint) - - [7.9. mdlinter](#79-mdlinter) - - [7.10. pycustomlint](#710-pycustomlint) - - [7.11. python-ruff](#711-python-ruff) - - [7.12. Shellcheck](#712-shellcheck) - - [7.13. Markdown Code Blocks](#713-markdown-code-blocks) - - [7.14. Non-markdown Version Tags](#714-non-markdown-version-tags) - - [7.15. Folder and In-file TOC](#715-folder-and-in-file-toc) - - [7.16. Test and Sanity Runners](#716-test-and-sanity-runners) - - [7.17. html-js-lint](#717-html-js-lint) - - [7.18. json-lint](#718-json-lint) - - [7.19. settings setup](#719-settings-setup) - - [7.20. Logging](#720-logging) - - [7.21. Documentation](#721-documentation) - - [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) -- [Appendix A. Maintainer Notes](#appendix-a-maintainer-notes) + - [7.1. wiki](#71-wiki) + - [7.1.1. wiki init](#711-wiki-init) + - [7.1.2. wiki update](#712-wiki-update) + - [7.1.3. wiki sanity](#713-wiki-sanity) + - [7.1.4. wiki graph](#714-wiki-graph) + - [7.1.5. wiki ingest](#715-wiki-ingest) + - [7.2. housekeeping](#72-housekeeping) + - [7.3. librarian](#73-librarian) + - [7.3.1. Folder and In-file TOC](#731-folder-and-in-file-toc) + - [7.3.2. Non-markdown Version Tags](#732-non-markdown-version-tags) + - [7.4. mdoctor](#74-mdoctor) + - [7.5. fmlint](#75-fmlint) + - [7.6. mdlinter](#76-mdlinter) + - [7.7. pycustomlint](#77-pycustomlint) + - [7.8. python-ruff](#78-python-ruff) + - [7.9. Shellcheck](#79-shellcheck) + - [7.10. Markdown Code Blocks](#710-markdown-code-blocks) + - [7.11. json-lint](#711-json-lint) + - [7.12. Git Operations](#712-git-operations) + - [7.13. Backup Script](#713-backup-script) + - [7.14. Test and Sanity Runners](#714-test-and-sanity-runners) + - [7.15. html-js-lint](#715-html-js-lint) + - [7.16. settings setup](#716-settings-setup) + - [7.17. Logging](#717-logging) + - [7.18. Documentation](#718-documentation) + - [7.19. Tool Roles](#719-tool-roles) + - [7.20. Wiki Root Discovery](#720-wiki-root-discovery) + - [7.21. Bootstrap install modes](#721-bootstrap-install-modes) +- [Appendix A. Non-Goals](#appendix-a-non-goals) +- [Appendix B. Priority Order](#appendix-b-priority-order) +- [Appendix C. Open Questions](#appendix-c-open-questions) +- [Appendix D. Maintainer Notes](#appendix-d-maintainer-notes) @@ -86,28 +89,32 @@ observable software. Status values are `Implemented`, `Partially Implemented`, `Planned`, and `Won't Do`. Revision 0.40.0 reorganizes the sheet into contracts. Revision 0.40.1 -numbers nested requirements such as `7.16.1.1`. Revision 0.40.4 adds +numbers nested requirements such as `7.14.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.* +Revision 0.90.0 specifies `node_importance_min_point` in *7.1.4.16.* and leaves that requirement unbuilt. Revision 0.92.0 specifies -`wiki ingest` in *7.25.* and leaves it unbuilt. Revision 0.93.0 adds +`wiki ingest` in *7.1.5.* 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.*). +(*7.1.2.11.*), and adds `fiona-assistant housekeeping` (*7.2.*). 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.*). +shows both short hashes in the update report (*7.1.2.12.*). Revision 0.97.0 rejects a module-level assignment that follows the first function or class (*6.4.3.*). Revision 0.98.0 specifies that -`wiki graph` omits a file matched by `.gitignore` (*7.4.17.*) and +`wiki graph` omits a file matched by `.gitignore` (*7.1.4.17.*) and leaves that requirement unbuilt. Revision 0.99.0 builds `wiki ingest` -(*7.25.*). +(*7.1.5.*). Revision 1.0.0 groups each module's functions under that +module and moves Non-Goals, Priority Order, and Open Questions +to Appendices A, B, and C. Revision 1.1.0 treats a differing +`fiona-settings.json` as a conflict and writes +`fiona-settings-update.json` (*7.1.2.3.*). Each feature section starts with a `Status` line. Requirements use `- *N.M.K.*`. Each `*acceptance*` sits under the requirement it tests. `NOT_IMPLEMENTED` marks work that is specified and not built yet. -Class names, file paths, and history live in Appendix A. +Class names, file paths, and history live in Appendix D. --- @@ -126,12 +133,12 @@ creative and analytical work. - *acceptance*: Every heading follows that numbering. - *1.1.2.* A requirement is `- *N.M.K.* `. A group is numbered the same way, and each item under it adds one segment, for example - `*7.16.1.*` then `*7.16.1.1.*`. Its acceptance is the next nested + `*7.14.1.*` then `*7.14.1.1.*`. Its acceptance is the next nested `- *acceptance*: `, and that acceptance describes this requirement only. - *acceptance*: No acceptance describes a neighboring requirement. - - *acceptance*: The shared-engine bullets in section 7.16 are - numbered `7.16.1` and `7.16.1.1`, not plain dashes. + - *acceptance*: The shared-engine bullets in section 7.14 are + numbered `7.14.1` and `7.14.1.1`, not plain dashes. - *1.1.3.* Unbuilt requirements start with `` `NOT_IMPLEMENTED` ``. - *acceptance*: Every planned item carries that tag. - *1.1.4.* The block between `` and @@ -153,7 +160,7 @@ These apply to every feature. 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. The one - exception is `wiki ingest` (*7.25.3.*): it may add a new file under + exception is `wiki ingest` (*7.1.5.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. @@ -161,7 +168,7 @@ These apply to every feature. 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.*). + `raw/` (*7.1.5.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. @@ -173,7 +180,7 @@ These apply to every feature. with file, line, column, and rule code. - *1.2.6.* Authored lengths in HTML and CSS use `em` or another relative unit (`rem`, `%`, `vh`, `vw`). They are not written in - `px`. The wiki graph page in section 7.4 is that web surface. + `px`. The wiki graph page in section 7.1.4 is that web surface. A position read from the layout engine is written back in `rem`. A theme length number uses the same scale: 16 is `1em`. - *acceptance*: The graph template contains no `px` length. @@ -187,7 +194,7 @@ These apply to every feature. Python `>= 3.11` (also 3.12 and 3.13). The default development install from the repository root is `pip install -e ".[dev]"`. `bootstrap --local` installs the same tree as a normal package -(`pip install .`). Section 7.24 defines those modes. The build +(`pip install .`). Section 7.21 defines those modes. The build requires setuptools 61 or newer. Runtime dependencies: @@ -200,9 +207,9 @@ Runtime dependencies: | GitPython | 3.1.0 | Development extras: `pytest>=7.0`, `pytest-cov>=4.0`, `pytest-mock`, -`pylint`. `html5validator` is not a dependency until section 7.17 +`pylint`. `html5validator` is not a dependency until section 7.15 is implemented. `beautifulsoup4`, `markdownify`, and `pypdf` become -runtime dependencies when section 7.25 is implemented. +runtime dependencies when section 7.1.5 is implemented. One importable package, `fiona`, lives under `src/fiona/`. Its subpackages are `librarian`, `mdoctor`, `customlinter`, @@ -223,7 +230,7 @@ Console scripts: `python-ruff`, `fmlint`, `json-lint`, and `git` are reached only through `fiona-assistant`. `html-js-lint` is not installed until -section 7.17 is implemented. +section 7.15 is implemented. Coverage measures `src/fiona`, omitting tests. The config lives in `pyproject.toml`. The gate percentage is section 5.2. @@ -243,7 +250,7 @@ pymarkdown resets the root logger mid-run. `pip install -e .`. - *acceptance*: `fiona-assistant` with no arguments prints help and exits 0. -- *2.2.* `html-js-lint` is not an installed script until section 7.17 +- *2.2.* `html-js-lint` is not an installed script until section 7.15 exists. - *acceptance*: A fresh install does not fail at import because of a missing `html_js_lint` package. @@ -322,12 +329,15 @@ Read-only zones, including the zone directory itself: `wiki/` is copied by `wiki init` and then left to the LLM. `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.*). +template page that is newer than the wiki's copy (*7.1.2.11.*). `wiki update` adds missing core files and directories. It never 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 +leaves the owner's file as it is. A differing +`fiona-settings.json` is the same kind of conflict: the owner's +file stays, and the template is written as +`fiona-settings-update.json` (*7.1.2.3.*). 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 @@ -392,7 +402,7 @@ this repository only. > Status: Implemented One command tree. Optional `[directory]` defaults to `.` today. -Wiki-root discovery (section 7.23) is not built. An invalid +Wiki-root discovery (section 7.20) is not built. An invalid directory prints `Error: '' is not a valid directory.` on stderr and exits 1, unless a command below states a different message. @@ -417,7 +427,7 @@ Found files in '': `mdoctor list` uses the same listing with the prefix `MDoctor: Found files in '':`. -### 4.2. librarian toc +#### 4.1.1. librarian toc `toc [directory] [flags]` writes `table_of_contents.md` in the target folder. Flags: `--recursive-toc`, `--non-recursive`, and @@ -430,7 +440,7 @@ A path that is a file or missing exits 1 on stderr and names `toc file ` writes an in-file TOC in that markdown file. `toc file *` does that for every markdown file under the wiki root -found by section 7.15. `--sectionized` forces section numbering for +found by section 7.3.1. `--sectionized` forces section numbering for that run. Status lines: ```text @@ -443,7 +453,7 @@ generated toc for file(s), skipped The summary line is bulk mode only. A file with no H1 is `skipped (no H1 heading)` and is not rewritten. -### 4.3. mdoctor +### 4.2. mdoctor No subcommand means `chklint .`. @@ -462,21 +472,21 @@ A pymarkdown API failure prints `Error: pymarkdown fix failed: ` on stderr and exits 1. The command does not skip `personal/` or `raw/`. -### 4.4. fmlint +### 4.3. fmlint `fiona-assistant fmlint` with no subcommand means `chklint .`. `chklint [directory]` prints the shared report with header `Frontmatter Lint Violations` and exits 0 even when violations exist. A missing directory exits 1. -### 4.5. python-ruff +### 4.4. python-ruff No subcommand means `chklint .`. The report header is `Ruff Violations`. Exit code is 0 when the ruff process itself succeeds, including when violations are listed. `lint(path, fix=True)` passes `--fix` to the ruff binary. There is no `fix` subcommand yet. -### 4.6. json-lint +### 4.5. json-lint No subcommand means `chklint .`. Header is `JSONLint Violations`. @@ -495,7 +505,7 @@ JSONLintFix: file(s) fixed A missing directory on `fix` prints `Error: '' does not exist.` on stderr and exits 1. -### 4.7. git +### 4.6. git Operates on the git repository at the current directory. Timestamps are UTC. @@ -535,7 +545,11 @@ commit stays. (`Cannot undo: only one commit exists in the repository.`), then `git reset --hard HEAD~1`. -### 4.8. wiki init +### 4.7. wiki + +Subcommands of `fiona-assistant wiki`. + +#### 4.7.1. wiki init `fiona-assistant wiki init [directory]`. Success stdout: @@ -545,7 +559,7 @@ Successfully initialized llm-wiki directory at: Rules are section 3. -### 4.9. wiki check-update +#### 4.7.2. wiki check-update `fiona-assistant wiki check-update [directory] [--json]`. The directory must contain `fiona-settings.json`, else stderr @@ -578,10 +592,10 @@ Files skipped (locally modified): ``` The version parenthesis appears only when both versions exist. -When the file was compared by hash instead (*7.2.12.*), the +When the file was compared by hash instead (*7.1.2.12.*), the parenthesis is `(sha256 ->