updated spec sheet
This commit is contained in:
@@ -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)
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user