updated spec sheet

This commit is contained in:
nvaldez
2026-09-23 18:12:02 +02:00
parent 067695a79f
commit 73dfc01b70
3 changed files with 166 additions and 105 deletions
+1 -1
View File
@@ -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)
+88 -55
View File
@@ -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`.
<!-- TOC -->
- [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)
<!-- /TOC -->
---
@@ -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.
+77 -49
View File
@@ -1,66 +1,94 @@
# Fiona Project TODO List
## llm-wiki
<!-- TOC -->
- [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)
<!-- /TOC -->
> 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 <description>`
- [ ] `snapshot` — `save` plus a git tag `yyyy-mm-dd_<tag_name>`
- [ ] `restore` — restore the `<tag_name>` 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)