diff --git a/AGENTS.md b/AGENTS.md index 994b0c0..b1715ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,7 +57,7 @@ This document defines the rules and guidelines for LLM Agents (including AI assi - After Modifying the repo, make sure `python src/run_sanity.py` passes before finalizing. - Documentation / Specs: - Before changing any functionality, read [SPEC](./SPEC.md) (the project spec sheet) so the change follows the specified requirements and acceptance criteria. - - Whenever a change alters behavior, adds a feature, or changes a requirement, update [SPEC](./SPEC.md) in the same task so the spec stays in sync (adjust section status: `planned` -> `partial` -> `shipped`). + - Whenever a change alters behavior, adds a feature, or changes a requirement, update [SPEC](./SPEC.md) in the same task so the spec stays in sync (adjust section status: `planned` -> `partial` -> `implemented`; use `won't do` for rejected features). ## Environment Setup (MANDATORY) diff --git a/SPEC.md b/SPEC.md index 625bc15..ac2e290 100644 --- a/SPEC.md +++ b/SPEC.md @@ -1,6 +1,6 @@ --- name: Fiona-Assistant Specification -version: 0.1.0 +version: 0.3.0 title: Project Spec Sheet created: 2026-09-23 updated: 2026-09-23 @@ -10,8 +10,30 @@ type: summary # Fiona-Assistant Specification **Spec sheet for the Fiona-Assistant toolkit.** Derived from `todo.md` and the -current codebase state. Each feature section lists status, requirements, and -acceptance criteria. Status values: `shipped`, `partial`, `planned`. +current codebase state. Each feature section opens with a `Status` line +followed by requirements and acceptance criteria. Status values: +`Implemented`, `Partially Implemented`, `Planned`, `Won't Do`. + + +- [1. Product Overview](#1-product-overview) +- [2. Feature Specifications](#2-feature-specifications) + - [2.1 llm-wiki Lifecycle Management](#21-llm-wiki-lifecycle-management) + - [2.1.1 `wiki init`](#211-wiki-init) + - [2.1.2 `wiki update`](#212-wiki-update) + - [2.1.3 `wiki sanity`](#213-wiki-sanity) + - [2.2 Git Version Control for llm-wiki](#22-git-version-control-for-llm-wiki) + - [2.2.1 Backup Script](#221-backup-script) + - [2.3 Shellcheck Library](#23-shellcheck-library) + - [2.4 MD Code Block Linting](#24-md-code-block-linting) + - [2.5 MD Frontmatter Tagging](#25-md-frontmatter-tagging) + - [2.6 Librarian: Non-MD File Support](#26-librarian-non-md-file-support) + - [2.7 Logging Library](#27-logging-library) + - [2.8 Documentation (medium priority)](#28-documentation-medium-priority) + - [2.9 Project Clarification (low priority)](#29-project-clarification-low-priority) +- [3. Non-Goals](#3-non-goals) +- [4. Priority Order](#4-priority-order) +- [5. Open Questions](#5-open-questions) + --- @@ -35,28 +57,17 @@ reserve LLM tokens for creative and analytical work. --- -## 2. Current Capabilities (shipped) +## 2. Feature Specifications -| Capability | Module | Notes | -|------------|--------|-------| -| Unified CLI dispatcher | `src/fiona/__main__.py` | `librarian`, `mdoctor`, `python-ruff`, `wiki` subcommands | -| File listing / wiki inventory | `src/librarian/librarian.py` | Recursive directory scans | -| Markdown linting | `src/mdoctor/mdoctor.py` | PyMarkdown wrapper, AI-friendly violation reports | -| Python linting | `src/python_ruff/python_ruff.py` | Ruff wrapper, AI-friendly violation reports | -| TOC generation | `src/librarian/toc_generator.py` | Nested TOC from markdown headers | -| MD frontmatter parsing | `src/librarian/md_frontmatter.py` | Name/version extraction for version control | -| llm-wiki template packaging | `src/llm-wiki/` | Included as package data in the PyPI package | -| `wiki init` | `src/wiki/wiki.py` | Copies llm-wiki template into a target directory | - ---- - -## 3. Feature Specifications - -### 3.1 llm-wiki Lifecycle Management — `partial` +### 2.1 llm-wiki Lifecycle Management +> Status: Partially Implemented +> > Covers: `fiona-assistant wiki init` (exists), `wiki update`, `wiki sanity`. -#### 3.1.1 `wiki init` — `partial` +#### 2.1.1 `wiki init` + +> Status: Partially Implemented Initialize the current or given directory as an llm-wiki directory by copying the packaged template (structure + core files), replacing `DATE_PLACEHOLDER` @@ -71,11 +82,13 @@ Requirements: Acceptance criteria: - Running `wiki init` on an empty directory produces a valid llm-wiki tree - that passes `wiki sanity` (once 3.1.3 ships; passes `mdoctor chklint` today). + that passes `wiki sanity` (once 2.1.3 ships; passes `mdoctor chklint` today). - Idempotence: re-running on an initialized directory does not clobber user content. -#### 3.1.2 `wiki update` — `planned` +#### 2.1.2 `wiki update` + +> Status: Planned Update an existing llm-wiki directory to the current template version. @@ -96,14 +109,16 @@ Acceptance criteria: - On a wiki with outdated core files, only those files are updated and the report lists each updated file with old and new version. -#### 3.1.3 `wiki sanity` — `planned` +#### 2.1.3 `wiki sanity` + +> Status: Planned Run all validation checks over an llm-wiki directory in one command. Requirements: - Runs markdown lint (`mdoctor`), Python lint (`python-ruff`), and any other - registered linters (shellcheck once 3.2 ships). + registered linters (shellcheck once 2.2 ships). - Checks for dead links (relative and wiki-internal links resolving to existing files). - Aggregated, AI-friendly summary report: per-check pass/fail, violation @@ -116,7 +131,9 @@ Acceptance criteria: --- -### 3.2 Git Version Control for llm-wiki — `planned` +### 2.2 Git Version Control for llm-wiki + +> Status: Planned Local version control, snapshot, and backup of wiki content via a GitPython wrapper module (proposed: `src/librarian/vcs.py` or `src/vcs/`). @@ -146,7 +163,9 @@ Acceptance criteria: state. - `clean` leaves `git status` empty. -#### 3.2.1 Backup Script — `planned` +#### 2.2.1 Backup Script + +> Status: Planned A user-facing backup mechanism so content can be recovered if something goes wrong. @@ -165,7 +184,9 @@ Acceptance criteria: --- -### 3.3 Shellcheck Library — `planned` +### 2.3 Shellcheck Library + +> Status: Planned Lint bash/shell scripts in the wiki and project. @@ -174,7 +195,7 @@ Requirements: - Wrap `shellcheck` following the same pattern as `python_ruff` (external linter, AI-friendly aggregated violation report). - Graceful error when `shellcheck` is not installed on the system. -- Integrated into `wiki sanity` (3.1.3). +- Integrated into `wiki sanity` (2.1.3). Acceptance criteria: @@ -184,7 +205,9 @@ Acceptance criteria: --- -### 3.4 MD Code Block Linting — `planned` +### 2.4 MD Code Block Linting + +> Status: Planned Lint fenced code blocks inside markdown files for quality. @@ -194,7 +217,7 @@ Requirements: python blocks via Ruff, shell blocks via shellcheck, others skipped. - Report violations with the md file path and the position inside the code block (block index and line within block, plus md line offset). -- Integrated into `wiki sanity` (3.1.3). +- Integrated into `wiki sanity` (2.1.3). Acceptance criteria: @@ -203,16 +226,18 @@ Acceptance criteria: --- -### 3.5 MD Frontmatter Tagging — `partial` +### 2.5 MD Frontmatter Tagging + +> Status: Partially Implemented Tag md files with metadata used for version control and quality signals. | Tag | Status | Purpose | |-----|--------|---------| -| `version` | shipped | Source control and `wiki update` change detection | -| `date` | planned | Creation/last-update timestamps maintained by tooling | -| `confidence` | planned | Quality signal (e.g. high/medium/low) on concept notes | -| `contested` | planned | Boolean flag marking notes with disputed claims | +| `version` | Implemented | Source control and `wiki update` change detection | +| `date` | Planned | Creation/last-update timestamps maintained by tooling | +| `confidence` | Planned | Quality signal (e.g. high/medium/low) on concept notes | +| `contested` | Planned | Boolean flag marking notes with disputed claims | Requirements: @@ -226,7 +251,9 @@ Acceptance criteria: --- -### 3.6 Librarian: Non-MD File Support — `planned` +### 2.6 Librarian: Non-MD File Support + +> Status: Planned Extend frontmatter-style tracking beyond md files. @@ -238,7 +265,9 @@ decision; do not implement until the tagging format is specified. --- -### 3.7 Logging Library — `planned` +### 2.7 Logging Library + +> Status: Planned Replace `print`-based output with a logging library across the codebase. @@ -255,7 +284,9 @@ Acceptance criteria: --- -### 3.8 Documentation — `planned` (medium priority) +### 2.8 Documentation (medium priority) + +> Status: Planned - Write `src/README.md` with project description. - Setup instructions (`pip install -e .`). @@ -271,7 +302,9 @@ Acceptance criteria: --- -### 3.9 Project Clarification — `planned` (low priority) +### 2.9 Project Clarification (low priority) + +> Status: Planned Define the role of each `src/` tool in the wiki workflow. @@ -292,7 +325,7 @@ Acceptance criteria: --- -## 4. Non-Goals +## 3. Non-Goals - No LLM/API integration: Fiona-Assistant is deterministic tooling only. - No modification of `personal/` or `raw/` content by any automated tool. @@ -300,27 +333,27 @@ Acceptance criteria: --- -## 5. Priority Order +## 4. Priority Order | Priority | Feature | Section | |----------|---------|---------| -| P1 | `wiki update` | 3.1.2 | -| P1 | Git wrapper (`save`/`snapshot`/`restore`/`clean`/`undo`) | 3.2 | -| P1 | `wiki sanity` incl. dead-link check | 3.1.3 | -| P2 | Shellcheck library | 3.3 | -| P2 | MD code block linting | 3.4 | -| P2 | Logging library | 3.7 | -| P3 | Frontmatter tags (`date`, `confidence`, `contested`) | 3.5 | -| P3 | Backup script | 3.2.1 | -| P3 | Documentation | 3.8 | -| P4 | Non-MD file tracking (py/bash) | 3.6 | -| P4 | Project clarification | 3.9 | +| P1 | `wiki update` | 2.1.2 | +| P1 | Git wrapper (`save`/`snapshot`/`restore`/`clean`/`undo`) | 2.2 | +| P1 | `wiki sanity` incl. dead-link check | 2.1.3 | +| P2 | Shellcheck library | 2.3 | +| P2 | MD code block linting | 2.4 | +| P2 | Logging library | 2.7 | +| P3 | Frontmatter tags (`date`, `confidence`, `contested`) | 2.5 | +| P3 | Backup script | 2.2.1 | +| P3 | Documentation | 2.8 | +| P4 | Non-MD file tracking (py/bash) | 2.6 | +| P4 | Project clarification | 2.9 | --- -## 6. Open Questions +## 5. Open Questions -- Tagging format for python files and bash scripts (3.6) is undecided. +- Tagging format for python files and bash scripts (2.6) is undecided. - Git wrapper location and naming (`src/vcs/` vs `src/librarian/vcs.py`). - Whether `wiki update` should support a `--force` flag or interactive confirmation for locally-modified core files. diff --git a/todo.md b/todo.md index 351e3e3..890181b 100644 --- a/todo.md +++ b/todo.md @@ -1,66 +1,94 @@ # Fiona Project TODO List -## llm-wiki + +- [Done](#done) +- [P1 — Wiki Lifecycle and Version Control](#p1--wiki-lifecycle-and-version-control) +- [P2 — Quality Tooling](#p2--quality-tooling) +- [P3 — Metadata, Backup, and Documentation](#p3--metadata-backup-and-documentation) +- [P4 — Design Decisions Needed](#p4--design-decisions-needed) +- [Open Questions (SPEC 5)](#open-questions-spec-5) + -> src/llm-wiki/* +Ordered by priority. Each item references its section in [SPEC.md](./SPEC.md) +(the source of truth for requirements and acceptance criteria). -- [x] find a way how to include the llm-wiki template as part of the PyPI package -- [ ] make a `fiona-assistant wiki init` to initialize the current or given directory as an `llm-wiki` directory - - [ ] at the same time if the directory is already an llm-wiki dir `fiona-assistant wiki update` should update all core versions of md files / scripts and update structure if neccesarry -- [ ] make use of git for local version control / snapshot / backup of the llm-wiki - - [ ] make a gitpython library wrapper - - [ ] basic operation: - - [ ] `save` commit the current edits with 'yyyy-mm-dd HH:MM:SS description_from_llm' - - [ ] `snaphot` use the `save` but also create a git tag `yyyy-mm-dd_tag_name` - - [ ] `restore` restore the `tag_name` state - - [ ] `clean` remove current edits (stating area) git status should be clean - - [ ] `undo` go back to the previous commit, error if git status is not clean, and suggest a `clean` command first -- [ ] make a backup script to that users can go back in case something goes wrong -- [ ] `fiona-assistant wiki sanity` to run all tests ex. mdlint, pylint, and all lints. - - [ ] should also check for dead links +## Done -## Shellcheck +- [x] Include the llm-wiki template as part of the PyPI package +- [x] MD frontmatter parser for version control of core files (SPEC 2.5) + - [x] `version` tag support +- [x] `fiona-assistant wiki init` — copy packaged template into a target + directory (basic flow; hardening tracked under P1) -- [ ] Implement shell check library +## P1 — Wiki Lifecycle and Version Control -## MD File +- [ ] `wiki init` hardening (SPEC 2.1.1) + - [ ] Warn or refuse when the target is already an llm-wiki directory + - [ ] Do not clobber user content on re-run (idempotent) +- [ ] `fiona-assistant wiki update` (SPEC 2.1.2) + - [ ] Update core md files / scripts to current template versions + (compare `version` frontmatter) + - [ ] Update directory structure when the template changed + - [ ] Skip locally-modified files and report them +- [ ] `fiona-assistant wiki sanity` (SPEC 2.1.3) + - [ ] Run all linters: mdlint, python-ruff, shellcheck (once P2 lands) + - [ ] Dead-link check (relative and wiki-internal links) +- [ ] Git version control for llm-wiki (SPEC 2.2) + - [ ] GitPython library wrapper + - [ ] Basic operations: + - [ ] `save` — commit current edits with + `yyyy-mm-dd HH:MM:SS ` + - [ ] `snapshot` — `save` plus a git tag `yyyy-mm-dd_` + - [ ] `restore` — restore the `` state + - [ ] `clean` — discard current edits (staging area); `git status` + must be clean afterwards + - [ ] `undo` — go back one commit; error if the working tree is dirty + and suggest `clean` first -- [ ] lint code blocks inside the MD files for quality +## P2 — Quality Tooling -## TOC generator +- [ ] Shellcheck library (SPEC 2.3) + - [ ] Wrap shellcheck like `python_ruff` (AI-friendly violation report) + - [ ] Clear install-hint error when shellcheck is missing +- [ ] Lint fenced code blocks inside MD files (SPEC 2.4) + - [ ] Python blocks via Ruff, shell blocks via shellcheck +- [ ] Logging library instead of `print` across the codebase (SPEC 2.7) + - [ ] Diagnostics to stderr with levels; preserve tool output format -- [ ] Tag MD files with +## P3 — Metadata, Backup, and Documentation + +- [ ] Backup script for llm-wiki so users can recover if something goes + wrong (SPEC 2.2.1) +- [ ] Frontmatter tags on MD files (SPEC 2.5) - [x] `version` - [ ] `date` tag - - [ ] quality signals: `confidence` - - [ ] `contested` if true - -## Librarian - -- [x] MDfile (filematter), for version control and future updates for core files - - [x] version -- [ ] python files: TBD -- [ ] bash scripts: TBD - -## Python Code base - -- [ ] Implement Logging library for logging instead of print - -## 🟢 Documentation (Medium Priority) - -- [ ] **Project documentation** + - [ ] Quality signal: `confidence` + - [ ] `contested` flag (true if claims are disputed) +- [ ] Project documentation (SPEC 2.8) - [ ] Write `src/README.md` with project description - - [ ] Add setup instructions (`pip install -e .`) - - [ ] Add usage examples for librarian and mdoctor + - [ ] Setup instructions (`pip install -e .`) + - [ ] Usage examples for librarian and mdoctor - [ ] Update `librarian/README.md` with actual usage info - [ ] Add `mdoctor/README.md` -## 🟢 Project Clarification (Low Priority) +## P4 — Design Decisions Needed -- [ ] **Define LLM Wiki tool roles** - - [ ] Document purpose of `fiona/src/` tools - - [ ] Define if tools are for: - - [ ] Ingestion: Moving files from `ingest/` to `raw/` - - [ ] Processing: Converting `raw/` to `wiki/concepts/` - - [ ] Maintenance: Updating `index.md`/`log.md` - - [ ] Add scripts to `utils/` for these tasks (e.g., `ingest.py`, `process.py`) +- [ ] Librarian: version tracking for non-MD files (SPEC 2.6) + - [ ] Python files — format TBD + - [ ] Bash scripts — format TBD + - [ ] Decide the tagging format before implementing +- [ ] Define LLM wiki tool roles (SPEC 2.9) + - [ ] Document purpose of `src/` tools + - [ ] Classify tools by role: + - [ ] Ingestion: moving files from `ingest/` to `raw/` + - [ ] Processing: converting `raw/` to `wiki/concepts/` + - [ ] Maintenance: updating `index.md` / `log.md` + - [ ] Add scripts to `utils/` for these tasks + (e.g. `ingest.py`, `process.py`) + +## Open Questions (SPEC 5) + +- Tagging format for python files and bash scripts (SPEC 2.6) +- Git wrapper location: `src/vcs/` vs `src/librarian/vcs.py` (SPEC 2.2) +- `wiki update`: `--force` flag vs interactive confirmation for + locally-modified core files (SPEC 2.1.2)