fiona skill improvement, and local non edit bootstrap install

This commit is contained in:
nvaldez
2026-09-30 11:06:02 +02:00
parent 3471ff9fe6
commit 0907252d4c
13 changed files with 773 additions and 155 deletions
+29 -7
View File
@@ -1,10 +1,10 @@
---
name: Fiona-Assistant Agent Rules
version: 1.5.0
version: 1.7.0
title: LLM Agent Rules
type: summary
created: 2025-09-23
updated: 2026-09-29
updated: 2026-09-30
tags: [agents, rules, guidelines, llm, ai]
sources: []
---
@@ -151,10 +151,21 @@ source bootstrap --env <env_name> --python <version>
# With cleanup flag
source bootstrap --env <env_name> -c
# This checkout as a normal package (not editable)
source bootstrap --local
# Current user, no virtual environment
source bootstrap --local --no-env
```
Windows (PowerShell, must be dot-sourced). This creates a repo-local venv
at `.venvs\<name>` with the Python launcher. It does not install pyenv.
Windows (PowerShell). A virtual-environment install must be
dot-sourced. This creates a repo-local venv at `.venvs\<name>` with
the Python launcher. It does not install pyenv. `--no-env` skips that
venv and may be executed with `-File`. `--local` installs this
repository with `pip install .` (not editable, no `dev` extra).
`--no-env` installs with `pip install --user`, so `fiona-assistant`
runs without activating an environment. The two flags combine.
```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
@@ -162,6 +173,8 @@ Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
. .\bootstrap.ps1 --env fiona_env
. .\bootstrap.ps1 --env <env_name> --python <version>
. .\bootstrap.ps1 --env <env_name> -c
. .\bootstrap.ps1 --local
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 --local --no-env
```
**Rationale**: The bootstrap script sets up the Python virtual environment,
@@ -382,7 +395,12 @@ Before step 2 of that lifecycle:
### 10.1 MD File Frontmatter
**All markdown files in llm-wiki/ MUST have YAML frontmatter** with the
required `name` and `version` fields. All other fields are optional:
required `name` and `version` fields. Every page under `wiki/` also
requires the quality signals `confidence`, `llm`, `contested`, and
`contradictions`. How to set them is section 13 of the
[Fiona skill](./src/fiona/data/llm_wiki/utils/skills/fiona/SKILL.md).
All other fields are optional. fmlint enforces `name` and `version`
only.
```yaml
---
@@ -394,8 +412,11 @@ updated: YYYY-MM-DD # optional (bump when editing)
type: entity | concept | comparison | query | summary | toc
sources: [raw/articles/source-name.md] # optional
tags: [from taxonomy] # optional
# Optional quality signals:
# quality signals (required on pages under wiki/):
confidence: trusted | high | medium | low | zero
llm:
- model: none # required; model that last edited the page
- reasoning: high # when the model reports a level
contested: true
contradictions: [other-page-slug]
---
@@ -491,13 +512,14 @@ These rules **CAN** be overridden by:
| Development | project agent rule 2.1, in order |
| Any Python work | Load the [python-tdd skill](./src/fiona/data/llm_wiki/utils/skills/python-tdd/SKILL.md) |
| Before testing | `source bootstrap` (Windows: `. .\bootstrap.ps1`) |
| Local install, no venv | `bootstrap --local --no-env` |
| Step 1 | Write or check [SPEC](./SPEC.md) |
| Step 2 and 3 | Failing tests, then the smallest change |
| Step 4 | Re-read the spec; tests and sanity pass |
| Step 5 | Bump `version` and `updated` on edited markdown |
| Before commit | Run tests + linters |
| Wiki changes | Load the [Fiona skill](./src/fiona/data/llm_wiki/utils/skills/fiona/SKILL.md); update index.md + log.md |
| Frontmatter | Include name, version, title, dates |
| Frontmatter | `name` and `version` on every file; on `wiki/` pages also `confidence`, `llm`, `contested`, `contradictions` |
| Errors | Raise exceptions, don't fail silently |
---
+36
View File
@@ -98,6 +98,40 @@ python -m pip install fiona-assistant
> Make sure `fiona_env` is activated before proceeding. On Windows the
> environment lives in `.venvs\fiona_env`.
### Local install (not editable)
Install this checkout as a normal package. The default bootstrap install
is editable (`pip install -e ".[dev]"`).
```bash
source bootstrap --local
```
```powershell
. .\bootstrap.ps1 --local
```
### Same as `pip install fiona-assistant`
`--local --no-env` installs this repository the same way
`python -m pip install fiona-assistant` does. Pip builds a wheel from
this directory and installs it into your user site-packages. The
`fiona-assistant` command then runs with no virtual environment. The
flag name is `--no-env`.
```bash
source bootstrap --local --no-env
```
```powershell
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 --local --no-env
```
That command is `python -m pip install --user .` from the repository
root. The package files are the ones in this checkout. If the command
is not found, add the user scripts directory printed by bootstrap to
`PATH`.
---
## Usage
@@ -348,6 +382,8 @@ GPL-3.0-only
| Run tests | `python scripts/run_tests.py` |
| Install | `pip install fiona-assistant` |
| Dev install | `pip install -e .` |
| Local install | `bootstrap --local` |
| Install like `pip install fiona-assistant` | `bootstrap --local --no-env` |
---
+91 -9
View File
@@ -1,6 +1,6 @@
---
name: Fiona-Assistant Specification
version: 0.87.1
version: 0.90.0
title: Project Spec Sheet
created: 2026-09-23
updated: 2026-09-30
@@ -67,6 +67,7 @@ type: summary
- [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)
- [8. Non-Goals](#8-non-goals)
- [9. Priority Order](#9-priority-order)
- [10. Open Questions](#10-open-questions)
@@ -83,6 +84,8 @@ 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
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.
Each feature section starts with a `Status` line. Requirements use
`- *N.M.K.*`. Each `*acceptance*` sits under the requirement it tests.
@@ -157,8 +160,12 @@ These apply to every feature.
> Status: Implemented
Python `>= 3.11` (also 3.12 and 3.13). Install with `pip install -e .`
from the repository root. The build requires setuptools 61 or newer.
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
requires setuptools 61 or newer.
Runtime dependencies:
| Package | Minimum |
@@ -755,6 +762,7 @@ Shipped document (logical content; `wiki init` copies the file):
| `fiona.wiki.graph.consolidate_external_links` | bool | false | wiki graph |
| `fiona.wiki.graph.consolidate_external_links_depth` | int | follow the bool | wiki graph |
| `fiona.wiki.graph.consolidate_external_links_max_char` | int | 8 | wiki graph |
| `fiona.wiki.graph.node_importance_min_point` | int `>= 0` | 0 | wiki graph |
Bool pymarkdown properties use `set_boolean_property`, ints use
`set_integer_property`, strings use `set_string_property`, applied as
@@ -814,6 +822,13 @@ subtitle to the host. The default is off.
`consolidate_external_links_max_char` is `...`. That limit is
`8` when absent or not a positive integer. Turning depth above
`0` also shortens the subtitle to the host.
`node_importance_min_point` is how many different files must
point at a node before the HTML graph draws it. The count is
`unique_points` (*7.4.2.3.*). `0` turns the filter off and
every node is drawn. A missing key, or a value that is not an
integer of 0 or more, is `0`. A positive integer is *7.4.16.*
and is not built yet. The packaged `fiona-settings.json` omits
the key until that requirement is built. Absent means `0`.
A mapping key under `toc_generator.file` whose name is not one of
`min_heading`, `max_heading`, `sectionize`, `ignore_files` is an
@@ -974,8 +989,11 @@ always at the start of the file.
> Status: Implemented
Required on every markdown file: `name`, `version`. All other fields
are optional.
Required on every markdown file: `name`, `version`. Required on every
page under `wiki/`: `confidence`, `llm`, `contested`, and
`contradictions`. The Fiona skill teaches how to set those four.
fmlint enforces `name` and `version` only. All other fields are
optional.
| Field | Required | Rule |
| --- | --- | --- |
@@ -987,9 +1005,10 @@ are optional.
| `type` | no | `entity`, `concept`, `comparison`, `query`, `summary`, `toc` |
| `tags` | no | Taxonomy tags from `wiki/schema.md` |
| `sources` | no | Paths such as `raw/articles/source-name.md` |
| `confidence` | no | Planned quality signal. Not enforced. |
| `contested` | no | Planned flag. Not enforced. |
| `contradictions` | no | Optional list of other page slugs. |
| `confidence` | wiki pages | `trusted`, `high`, `medium`, `low`, or `zero`. The agent sets it on every page under `wiki/`. fmlint does not enforce it. |
| `llm` | wiki pages | `model` is required. `reasoning` is set when the model reports a level. The agent sets it on every page under `wiki/`. fmlint does not enforce it. |
| `contested` | wiki pages | `true` when a claim on the page is disputed, otherwise `false`. The agent sets it on every page under `wiki/`. fmlint does not enforce it. |
| `contradictions` | wiki pages | Other page slugs that disagree. `[]` when none. The agent sets it on every page under `wiki/`. fmlint does not enforce it. |
| `description` | SKILL.md only | Required on a file whose name is `SKILL.md`. |
`markdown.frontmatter.type_requirements` maps a `type` value to the
@@ -1016,6 +1035,23 @@ zones.
- *6.2.2.* `SKILL.md` in `python-tdd/` with `name: Python TDD` is
FML005, and `name: other-name` is FML006.
- *acceptance*: The report code matches the case above.
- *6.2.3.* Every page under `wiki/` includes `confidence`, `llm`,
`contested`, and `contradictions`. The Fiona skill requires them
and states how to choose each value. `confidence` is `trusted`
(the user stated it, or it is copied from a cited source),
`high` (more than one source agrees, or one source and no known
contradiction), `medium` (one source, or a synthesis the agent
is reasonably sure of), `low` (inference, thin evidence, or an
open gap), or `zero` (unknown, or not checked). `llm` is a list
whose `model` entry is required: the model that last edited the
page, or `none` when no model wrote it. `reasoning` is included
when that model reports a level. `contested` is `true` when any
claim on the page is disputed by a source or another page, and
`false` otherwise. `contradictions` lists the `name` of each
page that disagrees, and is `[]` when none do. fmlint enforces
`name` and `version` only.
- *acceptance*: Fiona skill section 13 marks those four fields
required on wiki pages and states the choice rules above.
### 6.3. MDL Codes
@@ -2009,6 +2045,50 @@ not.
and shared. mdoctor already reads it for rules.
- *acceptance*: Two tools in one invocation see the same object.
### 7.24. Bootstrap install modes
> Status: Implemented
`bootstrap` (bash, sourced) and `bootstrap.ps1` (PowerShell) prepare
a Python environment and install this repository. With no install
flag, both create or reuse a virtual environment and run
`python -m pip install -e ".[dev]"`. `scripts/bootstrap_install.py`
is the pip-argument source both scripts call.
- *7.24.1.* `--local` installs this repository as a normal package.
The pip arguments are `install` and `.`. They do not include `-e`
and they do not include the `dev` extra.
- *acceptance*: `pip_install_args(local=True, no_env=False)` is
`["install", "."]`.
- *7.24.2.* `--no-env` does not create or activate a virtual
environment. The install adds `--user`, so the console scripts
land in the user scripts directory and run without activating an
environment.
- *acceptance*: `pip_install_args(local=False, no_env=True)`
contains `--user`. PowerShell skips virtual environment creation
when `$NoEnv` is set. Bash skips it when `NO_ENV` is `true`.
- *7.24.3.* `--local` and `--no-env` combine. The install is
`install`, `--user`, and `.`, with no `-e`.
- *acceptance*: `pip_install_args(local=True, no_env=True)` is
`["install", "--user", "."]`.
- *7.24.4.* Neither flag keeps the default: `-e` and `.[dev]`, and
no `--user`.
- *acceptance*: `pip_install_args(local=False, no_env=False)` is
`["install", "-e", ".[dev]"]`.
- *7.24.5.* Bash adds `--break-system-packages` on every install.
PowerShell does not.
- *acceptance*: `break_system_packages=True` inserts that flag
after `--user` when both are set, and after `install` when
`--user` is absent.
- *7.24.6.* A virtual-environment install on PowerShell must be
dot-sourced so the environment stays active. `--no-env` may be
executed with `-File`, because there is no environment to keep
active. Bash is sourced for both modes.
- *acceptance*: PowerShell reports a dot-source error when
`--local` is used without `--no-env` and the script is not
dot-sourced. The message does not call `--local` an unknown
option.
---
## 8. Non-Goals
@@ -2047,7 +2127,8 @@ not.
| P2 | python-ruff fix subcommand | 7.11.2 | Planned |
| P2 | Wiki root discovery | 7.23 | Planned |
| P2 | settings setup | 7.19 | Planned |
| P3 | confidence and contested tags | 6.2 | Planned |
| P2 | Bootstrap install modes | 7.24 | Implemented |
| P3 | fmlint enforcement of quality signals | 6.2 | Planned |
| P3 | Backup archive | 7.6 | Planned |
| P3 | Documentation refresh | 7.21 | Partially Implemented |
| P4 | Non-markdown version tags | 7.14 | Planned |
@@ -2093,6 +2174,7 @@ These notes are not requirements. They point at the current tree.
| sanity engine | `src/fiona/sanity_runner/sanity_runner.py` |
| runners | `src/fiona/run_tests.py`, `src/fiona/run_sanity.py` |
| launchers | `scripts/run_tests.py`, `scripts/run_sanity.py` |
| bootstrap | `bootstrap`, `bootstrap.ps1`, `scripts/bootstrap_install.py` |
Known defects to avoid copying blindly:
+156 -70
View File
@@ -1,4 +1,5 @@
#!/bin/bash
# Modified by AI/LLM: 2026-09-30 - --local and --no-env install options.
#
# Project bootstrap script - Sets up Python development environment
#
@@ -6,21 +7,29 @@
# source bootstrap
#
# Windows (PowerShell): dot-source bootstrap.ps1 instead
# . .\bootstrap.ps1 [--env name] [--python 3.x.x] [-c|--clean]
# . .\bootstrap.ps1 [--env name] [--python 3.x.x] [-c|--clean] [--local] [--no-env]
#
# What it does:
# 1. Installs pyenv and required system dependencies if needed
# 2. Initializes pyenv and pyenv-virtualenv in the current shell
# 3. Creates a Python virtual environment named 'test_env' (or custom name)
# 4. Activates the virtual environment
# 5. Installs all project requirements from requirements.txt files
# 5. Installs this repository (editable with the dev extra, unless --local)
#
# With --clean/-c option:
# - Deletes existing environment before creating a new one
#
# With --local:
# - Installs this repository as a normal package (pip install .), not editable
#
# With --no-env:
# - Skips pyenv and the virtual environment
# - Installs with pip --user so the commands run without activating an environment
#
# Usage:
# source bootstrap [--pyenv] [-c|--clean] [--env custom_name] [--python 3.x.x]
# source bootstrap [--pyenv] [-c|--clean] [--env custom_name] [--python 3.x.x] [--local] [--no-env]
# ex. source bootstrap --pyenv -c --env my_env --python 3.10.6
# ex. source bootstrap --local --no-env
# =============================================
# VARIABLES
@@ -29,6 +38,9 @@ PYTHON_VERSION="3.13.8" # Default Python version
export PYENV_NAME="test_env" # Default environment name
FORCE_PYENV_INSTALL=false # Flag to force pyenv reinstallation
CLEAN_ENVIRONMENT=false # Flag to delete and recreate environment
LOCAL_INSTALL=false # Install this repo as a normal package, not editable
NO_ENV=false # Skip the virtual environment and pip install --user
PYTHON_BIN="python"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" # scripts root directory
# Source utilities (needed for echo_error, echo_status, etc.)
@@ -45,6 +57,14 @@ while [[ $# -gt 0 ]]; do
CLEAN_ENVIRONMENT=true
shift
;;
--local)
LOCAL_INSTALL=true
shift
;;
--no-env)
NO_ENV=true
shift
;;
--env)
if [ -n "$2" ]; then
PYENV_NAME="$2"
@@ -65,7 +85,7 @@ while [[ $# -gt 0 ]]; do
;;
*)
echo_error "Unknown option: $1"
echo "Usage: source bootstrap [--pyenv] [-c|--clean] [--env custom_name] [--python 3.x.x]"
echo "Usage: source bootstrap [--pyenv] [-c|--clean] [--env custom_name] [--python 3.x.x] [--local] [--no-env]"
return 1
;;
esac
@@ -334,52 +354,82 @@ install_requirements() {
echo_status "Installing requirements..."
# Check if pyproject.toml exists (could be in root or src/)
local pyproject_root="$SCRIPT_DIR/pyproject.toml"
local pyproject_src="$SCRIPT_DIR/src/pyproject.toml"
if [ -f "$pyproject_root" ]; then
# Install the package in development mode from root
echo_status "Installing package and dependencies from pyproject.toml..."
(cd "$SCRIPT_DIR" && pip install -e ".[dev]" --break-system-packages) || {
echo_error "Failed to install package and dependencies from pyproject.toml"
return 1
}
elif [ -f "$pyproject_src" ]; then
# Install the package in development mode from src/
echo_status "Installing package and dependencies from pyproject.toml..."
(cd "$SCRIPT_DIR/src" && pip install -e ".[dev]" --break-system-packages) || {
echo_error "Failed to install package and dependencies from pyproject.toml"
return 1
}
else
echo_warning "No pyproject.toml found"
# Fallback: look for any requirements.txt files
local req_files=()
while IFS= read -r -d '' req_file; do
req_files+=("$req_file")
done < <(find "$SCRIPT_DIR" -name "requirements.txt" -print0)
if [ ${#req_files[@]} -eq 0 ]; then
echo_status "No requirements files found"
return 0
fi
for req_file in "${req_files[@]}"; do
echo_status "Installing requirements from: $req_file"
pip install -r "$req_file" --break-system-packages || {
echo_error "Failed to install requirements from $req_file"
return 1
}
done
local project_dir=""
if [ -f "$SCRIPT_DIR/pyproject.toml" ]; then
project_dir="$SCRIPT_DIR"
elif [ -f "$SCRIPT_DIR/src/pyproject.toml" ]; then
project_dir="$SCRIPT_DIR/src"
fi
if [ -n "$project_dir" ]; then
local helper="$SCRIPT_DIR/scripts/bootstrap_install.py"
if [ ! -f "$helper" ]; then
echo_error "Missing $helper"
return 1
fi
local flags=(--break-system-packages)
if [ "$LOCAL_INSTALL" = true ]; then
echo_status "Installing this repository as a normal package..."
flags+=(--local)
else
echo_status "Installing package and dependencies from pyproject.toml..."
fi
if [ "$NO_ENV" = true ]; then
flags+=(--no-env)
fi
local pip_words=()
local word
while IFS= read -r word; do
if [ -n "$word" ]; then
pip_words+=("$word")
fi
done < <("$PYTHON_BIN" "$helper" "${flags[@]}")
if [ "${#pip_words[@]}" -eq 0 ]; then
echo_error "Failed to resolve pip install arguments"
return 1
fi
(cd "$project_dir" && "$PYTHON_BIN" -m pip "${pip_words[@]}") || {
echo_error "Failed to install package and dependencies from pyproject.toml"
return 1
}
return 0
fi
echo_warning "No pyproject.toml found"
# Fallback: look for any requirements.txt files
local req_files=()
while IFS= read -r -d '' req_file; do
req_files+=("$req_file")
done < <(find "$SCRIPT_DIR" -name "requirements.txt" -print0)
if [ ${#req_files[@]} -eq 0 ]; then
echo_status "No requirements files found"
return 0
fi
local user_args=()
if [ "$NO_ENV" = true ]; then
user_args+=(--user)
fi
for req_file in "${req_files[@]}"; do
echo_status "Installing requirements from: $req_file"
"$PYTHON_BIN" -m pip install "${user_args[@]}" -r "$req_file" --break-system-packages || {
echo_error "Failed to install requirements from $req_file"
return 1
}
done
return 0
}
upgrade_pip() {
echo_status "Upgrading pip..."
python -m pip install --upgrade pip --break-system-packages || {
local upgrade_args=(install --upgrade pip --break-system-packages)
if [ "$NO_ENV" = true ]; then
upgrade_args=(install --user --upgrade pip --break-system-packages)
fi
"$PYTHON_BIN" -m pip "${upgrade_args[@]}" || {
echo_warning "Failed to upgrade pip"
echo_warning "Continuing with requirements installation..."
}
@@ -440,35 +490,60 @@ sanitize_pytest_env() {
# =============================================
# MAIN EXECUTION
# =============================================
echo_status "Starting project bootstrap with environment: $PYENV_NAME"
if [ "$FORCE_PYENV_INSTALL" = true ]; then
echo_status "Forcing pyenv reinstallation"
if [ "$NO_ENV" = true ]; then
echo_status "Starting project bootstrap (no virtual environment)"
else
echo_status "Starting project bootstrap with environment: $PYENV_NAME"
fi
# 1. Check if Python is installed
if ! check_python_installed; then
return 1
if [ "$LOCAL_INSTALL" = true ]; then
echo_status "Local install: this repository, not editable"
fi
if [ "$NO_ENV" = true ]; then
echo_status "No virtual environment: installing with --user"
fi
# 2. Check/install pyenv
if ! check_and_install_pyenv; then
return 1
fi
if [ "$NO_ENV" = true ]; then
if ! command -v python >/dev/null 2>&1 && ! command -v python3 >/dev/null 2>&1; then
echo_error "Python is not installed. Please install Python $PYTHON_VERSION before running this script."
echo_error "Or download from: https://www.python.org/downloads/"
return 1
fi
if command -v python >/dev/null 2>&1; then
PYTHON_BIN="python"
else
PYTHON_BIN="python3"
fi
else
if [ "$FORCE_PYENV_INSTALL" = true ]; then
echo_status "Forcing pyenv reinstallation"
fi
# 3. Initialize pyenv
if ! initialize_pyenv; then
return 1
fi
# 1. Check if Python is installed
if ! check_python_installed; then
return 1
fi
# 4. Check/create virtual environment
if ! check_environment_exists; then
return 1
fi
# 2. Check/install pyenv
if ! check_and_install_pyenv; then
return 1
fi
# 5. Activate the environment
if ! activate_environment; then
return 1
# 3. Initialize pyenv
if ! initialize_pyenv; then
return 1
fi
# 4. Check/create virtual environment
if ! check_environment_exists; then
return 1
fi
# 5. Activate the environment
if ! activate_environment; then
return 1
fi
PYTHON_BIN="python"
fi
# 5.5. Sanitize pytest environment to ensure proper output parsing
@@ -477,14 +552,25 @@ sanitize_pytest_env
# 6. Upgrade pip
upgrade_pip
# 7. Install requirements (including package in dev mode with all dependencies)
install_requirements
# 7. Install this repository
if ! install_requirements; then
return 1
fi
# Final verification
echo_status "Bootstrap completed successfully!"
echo_status "Virtual environment '$PYENV_NAME' is active"
echo_status "Python: $(python --version) ($(which python))"
echo_status "Pip: $(pip --version)"
if [ "$NO_ENV" = true ]; then
scripts_dir=$("$PYTHON_BIN" -c "import sys, sysconfig; scheme = 'nt_user' if sys.platform == 'win32' else 'posix_user'; print(sysconfig.get_path('scripts', scheme))")
echo_status "Installed for the current user (no virtual environment)"
echo_status "Command directory: $scripts_dir"
echo_status "If fiona-assistant is not found, add that directory to PATH."
echo_status "Python: $("$PYTHON_BIN" --version) ($PYTHON_BIN)"
echo_status "Pip: $("$PYTHON_BIN" -m pip --version)"
else
echo_status "Virtual environment '$PYENV_NAME' is active"
echo_status "Python: $(python --version) ($(which python))"
echo_status "Pip: $(pip --version)"
fi
echo_status ""
echo_status "To verify installation, try:"
echo_status " fiona-assistant test"
+123 -47
View File
@@ -1,16 +1,25 @@
# Generated by AI/LLM: 2026-09-29 - Windows PowerShell bootstrap for Fiona development
# Modified by AI/LLM: 2026-09-30 - --local and --no-env install options.
#
# Project bootstrap for Windows. Dot-source it so the virtual environment
# stays active in the current session (same idea as `source bootstrap`):
# Project bootstrap for Windows. Dot-source a virtual-environment install so
# the environment stays active in the current session (same idea as
# `source bootstrap`):
#
# Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
# . .\bootstrap.ps1
# . .\bootstrap.ps1 --env fiona_env
# . .\bootstrap.ps1 --env fiona_env --python 3.13.8 -c
# . .\bootstrap.ps1 --local
# powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 --local --no-env
#
# Creates a repo-local venv at .venvs\<name> with the Python launcher (py)
# or python on PATH. Does not install pyenv. --pyenv is accepted so the
# Linux flag still parses; on Windows it is a no-op notice.
#
# --local installs this repository as a normal package (not editable).
# --no-env skips the virtual environment and installs with pip --user,
# so fiona-assistant can run without activating an environment.
# --no-env may be executed with -File. A venv install must be dot-sourced.
#Requires -Version 5.1
@@ -103,6 +112,8 @@ $Clean = $false
$EnvName = "test_env"
$PythonVersion = ""
$Pyenv = $false
$Local = $false
$NoEnv = $false
$bootstrapArgs = @($args)
for ($i = 0; $i -lt $bootstrapArgs.Count; $i++) {
$token = [string]$bootstrapArgs[$i]
@@ -112,6 +123,12 @@ for ($i = 0; $i -lt $bootstrapArgs.Count; $i++) {
elseif ($token -eq "-c" -or $token -eq "--clean") {
$Clean = $true
}
elseif ($token -eq "--local") {
$Local = $true
}
elseif ($token -eq "--no-env") {
$NoEnv = $true
}
elseif ($token -eq "--env") {
if (($i + 1) -ge $bootstrapArgs.Count) {
Write-FionaError "--env requires an environment name argument"
@@ -132,15 +149,17 @@ for ($i = 0; $i -lt $bootstrapArgs.Count; $i++) {
}
else {
Write-FionaError "Unknown option: $token"
Write-FionaError "Usage: . .\bootstrap.ps1 [--pyenv] [-c|--clean] [--env custom_name] [--python 3.x.x]"
Write-FionaError "Usage: . .\bootstrap.ps1 [--pyenv] [-c|--clean] [--env custom_name] [--python 3.x.x] [--local] [--no-env]"
Remove-FionaBootstrapFunctions
return
}
}
if ($MyInvocation.InvocationName -ne ".") {
if (-not $NoEnv -and $MyInvocation.InvocationName -ne ".") {
Write-FionaError "Dot-source this script so the virtual environment stays active in this session."
Write-FionaError " . .\bootstrap.ps1"
Write-FionaError "To install without a virtual environment, run:"
Write-FionaError " powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 --local --no-env"
Remove-FionaBootstrapFunctions
return
}
@@ -154,7 +173,21 @@ if (-not $repoRoot) {
$repoRoot = (Get-Location).Path
}
Write-FionaStatus "Starting project bootstrap with environment: $EnvName"
if ($NoEnv) {
Write-FionaStatus "Starting project bootstrap (no virtual environment)"
}
else {
Write-FionaStatus "Starting project bootstrap with environment: $EnvName"
}
if ($Local) {
Write-FionaStatus "Local install: this repository, not editable"
}
if ($NoEnv) {
Write-FionaStatus "No virtual environment: installing with --user"
}
if ($NoEnv -and $Clean) {
Write-FionaWarning "--clean has no effect with --no-env"
}
try {
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force -ErrorAction Stop | Out-Null
@@ -174,44 +207,49 @@ if (-not $pythonExe) {
return
}
$venvRoot = Join-Path $repoRoot ".venvs"
$venvPath = Join-Path $venvRoot $EnvName
$pipPython = $pythonExe
if (-not $NoEnv) {
$venvRoot = Join-Path $repoRoot ".venvs"
$venvPath = Join-Path $venvRoot $EnvName
if ($Clean -and (Test-Path -LiteralPath $venvPath)) {
Write-FionaStatus "Deleting existing virtual environment $EnvName..."
try {
Remove-Item -LiteralPath $venvPath -Recurse -Force
if ($Clean -and (Test-Path -LiteralPath $venvPath)) {
Write-FionaStatus "Deleting existing virtual environment $EnvName..."
try {
Remove-Item -LiteralPath $venvPath -Recurse -Force
}
catch {
Write-FionaError "Failed to delete virtual environment $EnvName"
Write-FionaError $_.Exception.Message
Remove-FionaBootstrapFunctions
return
}
}
catch {
Write-FionaError "Failed to delete virtual environment $EnvName"
Write-FionaError $_.Exception.Message
$activate = Join-Path $venvPath "Scripts\Activate.ps1"
if (-not (Test-Path -LiteralPath $activate)) {
Write-FionaStatus "Creating virtual environment $EnvName with $pythonExe..."
New-Item -ItemType Directory -Path $venvRoot -Force | Out-Null
& $pythonExe -m venv $venvPath
if ($LASTEXITCODE -ne 0) {
Write-FionaError "Failed to create virtual environment $EnvName"
Remove-FionaBootstrapFunctions
return
}
}
else {
Write-FionaStatus "Virtual environment $EnvName already exists"
}
Write-FionaStatus "Activating $EnvName..."
. $activate
if (-not $env:VIRTUAL_ENV) {
Write-FionaError "Failed to activate $EnvName"
Remove-FionaBootstrapFunctions
return
}
}
$activate = Join-Path $venvPath "Scripts\Activate.ps1"
if (-not (Test-Path -LiteralPath $activate)) {
Write-FionaStatus "Creating virtual environment $EnvName with $pythonExe..."
New-Item -ItemType Directory -Path $venvRoot -Force | Out-Null
& $pythonExe -m venv $venvPath
if ($LASTEXITCODE -ne 0) {
Write-FionaError "Failed to create virtual environment $EnvName"
Remove-FionaBootstrapFunctions
return
}
}
else {
Write-FionaStatus "Virtual environment $EnvName already exists"
}
Write-FionaStatus "Activating $EnvName..."
. $activate
if (-not $env:VIRTUAL_ENV) {
Write-FionaError "Failed to activate $EnvName"
Remove-FionaBootstrapFunctions
return
$pipPython = Join-Path $venvPath "Scripts\python.exe"
}
if ($env:PYTEST_ADDOPTS) {
@@ -244,15 +282,45 @@ if (-not (Test-Path -LiteralPath $pyproject)) {
}
Write-FionaStatus "Upgrading pip..."
& python -m pip install --upgrade pip
if ($NoEnv) {
& $pipPython -m pip install --upgrade pip --user
}
else {
& $pipPython -m pip install --upgrade pip
}
if ($LASTEXITCODE -ne 0) {
Write-FionaWarning "Failed to upgrade pip. Continuing with package installation..."
}
Write-FionaStatus "Installing package and dependencies from pyproject.toml..."
$helper = Join-Path $repoRoot "scripts\bootstrap_install.py"
if (-not (Test-Path -LiteralPath $helper)) {
Write-FionaError "Missing $helper"
Remove-FionaBootstrapFunctions
return
}
$helperArgs = @($helper)
if ($Local) {
$helperArgs += "--local"
}
if ($NoEnv) {
$helperArgs += "--no-env"
}
$pipWords = @(& $pipPython @helperArgs | Where-Object { $_ -and "$_".Trim() -ne "" })
if ($LASTEXITCODE -ne 0 -or $pipWords.Count -eq 0) {
Write-FionaError "Failed to resolve pip install arguments"
Remove-FionaBootstrapFunctions
return
}
if ($Local) {
Write-FionaStatus "Installing this repository as a normal package..."
}
else {
Write-FionaStatus "Installing package and dependencies from pyproject.toml..."
}
Push-Location $repoRoot
try {
& python -m pip install -e ".[dev]"
& $pipPython -m pip @pipWords
if ($LASTEXITCODE -ne 0) {
Write-FionaError "Failed to install package and dependencies from pyproject.toml"
Remove-FionaBootstrapFunctions
@@ -263,18 +331,26 @@ finally {
Pop-Location
}
$pythonCmd = Get-Command python -ErrorAction SilentlyContinue
$pythonWhere = if ($pythonCmd) { $pythonCmd.Source } else { "python" }
$pythonVersionText = (& python --version 2>&1 | Out-String).Trim()
$pipVersionText = (& python -m pip --version 2>&1 | Out-String).Trim()
$pythonVersionText = (& $pipPython --version 2>&1 | Out-String).Trim()
$pipVersionText = (& $pipPython -m pip --version 2>&1 | Out-String).Trim()
Write-FionaStatus "Bootstrap completed successfully!"
Write-FionaStatus "Virtual environment '$EnvName' is active"
Write-FionaStatus "Python: $pythonVersionText ($pythonWhere)"
if ($NoEnv) {
$scriptsDir = (& $pipPython -c "import sysconfig; print(sysconfig.get_path('scripts', 'nt_user'))" | Out-String).Trim()
Write-FionaStatus "Installed for the current user (no virtual environment)"
Write-FionaStatus "Command directory: $scriptsDir"
Write-FionaStatus "If fiona-assistant is not found, add that directory to PATH."
}
else {
Write-FionaStatus "Virtual environment '$EnvName' is active"
}
Write-FionaStatus "Python: $pythonVersionText ($pipPython)"
Write-FionaStatus "Pip: $pipVersionText"
Write-FionaStatus ""
Write-FionaStatus "To verify installation, try:"
Write-FionaStatus " python scripts/run_tests.py"
if (-not $NoEnv) {
Write-FionaStatus " python scripts/run_tests.py"
}
Write-FionaStatus " fiona-assistant --help"
Write-FionaStatus ""
Write-FionaStatus "Happy coding!"
+83
View File
@@ -0,0 +1,83 @@
"""Pip arguments for bootstrap install modes.
Generated by AI/LLM: 2026-09-30 - local and no-env install options.
SPEC 7.24. Both ``bootstrap`` and ``bootstrap.ps1`` call this script
and read one pip argument per stdout line.
"""
import argparse
import sys
def pip_install_args(
*,
local: bool,
no_env: bool,
break_system_packages: bool = False,
) -> list[str]:
"""Return the arguments passed to ``python -m pip``.
Args:
local: Install this repository as a normal package. When
false, the install is editable and includes the ``dev``
extra.
no_env: Add ``--user`` so the install does not need a virtual
environment.
break_system_packages: Add ``--break-system-packages``. Bash
sets this. PowerShell does not.
Returns:
The pip argument list, starting with ``install``.
"""
args = ["install"]
if no_env:
args.append("--user")
if break_system_packages:
args.append("--break-system-packages")
if local:
args.append(".")
else:
args.extend(["-e", ".[dev]"])
return args
def main(argv: list[str] | None = None) -> int:
"""Print pip arguments, one per line.
Args:
argv: Flags to parse. ``None`` reads ``sys.argv``.
Returns:
Process exit code. ``0`` after the arguments are written.
"""
parser = argparse.ArgumentParser(
description="Print pip install arguments for bootstrap.",
)
parser.add_argument(
"--local",
action="store_true",
help="install this repository as a normal package",
)
parser.add_argument(
"--no-env",
action="store_true",
help="add --user so no virtual environment is required",
)
parser.add_argument(
"--break-system-packages",
action="store_true",
help="pass --break-system-packages to pip",
)
parsed = parser.parse_args(argv)
words = pip_install_args(
local=parsed.local,
no_env=parsed.no_env,
break_system_packages=parsed.break_system_packages,
)
sys.stdout.write("\n".join(words) + "\n")
return 0
if __name__ == "__main__":
sys.exit(main())
+8
View File
@@ -41,6 +41,14 @@ The Fiona Assistant project provides command-line tools for:
. .\bootstrap.ps1 --env fiona_env --python 3.11.0
```
Install this checkout as a normal package with `--local`. Skip the
virtual environment with `--no-env` (PowerShell may use `-File`
instead of dot-sourcing):
```powershell
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 --local --no-env
```
3. Install the package in development mode:
```bash
@@ -4,8 +4,8 @@ category: productivity
description: Operate an llm-wiki with the fiona-assistant CLI.
author: nvaldez
license: MIT
version: 1.2.1
updated: 2026-09-29
version: 1.3.0
updated: 2026-09-30
---
# Fiona
@@ -404,6 +404,7 @@ unless a command above states a different message.
After you edit a page:
1. Bump frontmatter `version` and set `updated` to the edit date.
On a page under `wiki/`, set the quality signals in section 13.
Patch for a clarification, minor for a new section, major for a
breaking change.
2. A new page is listed in `wiki/index.md`.
@@ -433,6 +434,10 @@ do not edit them after that. Synthesized pages go under `wiki/`
Required on every markdown file: `name`, `version`. Bump `version`
when the page is edited. Set `updated` when you edit.
Required on every page under `wiki/`: the quality signals
`confidence`, `llm`, `contested`, and `contradictions`. Set them
in the same edit. fmlint enforces `name` and `version` only.
| Field | Required | Rule |
| --- | --- | --- |
| `name` | yes | Wiki pages use lowercase and hyphens. |
@@ -443,8 +448,43 @@ when the page is edited. Set `updated` when you edit.
| `type` | no | `entity`, `concept`, `comparison`, `query`, `summary`, `toc` |
| `tags` | no | From the taxonomy in schema.md. |
| `sources` | no | Paths such as `raw/articles/source-name.md`. |
| `confidence` | wiki pages | `trusted`, `high`, `medium`, `low`, or `zero`. See below. |
| `llm` | wiki pages | `model` is required. Add `reasoning` when the model reports a level. |
| `contested` | wiki pages | `true` when a claim is disputed, otherwise `false`. |
| `contradictions` | wiki pages | Other page slugs that disagree. `[]` when none. |
| `description` | SKILL.md only | Required when the file name is `SKILL.md`. |
### Quality signals
On every page under `wiki/`, fill these before you finish the edit.
Refresh them when you change the page. `llm.model` is the model
that made this edit.
`confidence` is how sure the page is:
- `trusted`: the user stated it, or it is copied from a cited source, with no inference.
- `high`: more than one source agrees, or one source and no known contradiction.
- `medium`: one source, or a synthesis you are reasonably sure of.
- `low`: inference, thin evidence, or an open gap.
- `zero`: unknown, or not checked.
`llm` records who wrote the page:
```yaml
llm:
- model: <model name>
- reasoning: high
```
`model` is required. Use `none` when no model wrote the page.
Add `reasoning` when the model reports a level.
`contested` is `true` when any claim on the page is disputed by a
source or by another page. Otherwise `false`.
`contradictions` lists the `name` of each page that disagrees.
Use `[]` when none do.
`SKILL.md` `name` must match `^[a-z0-9-]+$` and the parent folder.
## 14. Checks with no own command
@@ -1,8 +1,8 @@
---
name: llm-wiki-mod
title: LLM Wiki Pattern
version: 1.1.0
updated: 2026-09-29
version: 1.2.0
updated: 2026-09-30
type: concept
tags: [wiki, schema]
---
@@ -114,6 +114,9 @@ the schema disagree, the schema wins.
- File names are lowercase, with hyphens, and without spaces.
- Every markdown file has frontmatter. `name` and `version` are required.
- Every page under `wiki/` also requires `confidence`, `llm`,
`contested`, and `contradictions`. How to set them is section 13
of the [Fiona skill](./SKILL.md).
- Optional fields are `title`, `created`, `updated`, `type`, `tags`, and `sources`.
- `type` is `entity`, `concept`, `comparison`, `query`, `summary`, or `toc`.
- Tags come from the taxonomy in the schema.
+12 -2
View File
@@ -1,10 +1,15 @@
---
name: log
title: Wiki Log
version: 1.2.8
version: 1.2.9
type: summary
created: 2025-09-23
updated: 2026-09-29
updated: 2026-09-30
confidence: trusted
llm:
- model: grok-4.7
contested: false
contradictions: []
---
# Wiki Log
@@ -73,3 +78,8 @@ Chronological tracking of all actions performed on the wiki.
to the schema: canonical frontmatter, the raw / wiki / schema
layers, and the index, log, and page rules. Commands stay in
the Fiona skill.
- 2026-09-30 - Quality signals are required on pages under `wiki/`:
`confidence`, `llm` (`model`, and `reasoning` when reported),
`contested`, and `contradictions`. Fiona skill v1.3.0 teaches
how to set them. fmlint still enforces `name` and `version` only
(SPEC 6.2.3, schema v1.3.0).
+22 -8
View File
@@ -1,11 +1,16 @@
---
name: llm-wiki-schema
title: LLM Wiki Schema
version: 1.2.1
version: 1.3.0
created: 2025-09-18
updated: 2026-09-29
updated: 2026-09-30
type: summary
tags: [wiki, schema]
confidence: trusted
llm:
- model: grok-4.7
contested: false
contradictions: []
---
# LLM Wiki Schema
@@ -17,8 +22,10 @@ Personal knowledge base and inventory management.
## Conventions
- File names: lowercase, hyphens, no spaces (e.g., `llm-wiki-schema.md`)
- Every wiki page starts with YAML frontmatter (required: `name`, `version`;
optional: `title`, `created`, `updated`, `type`, `tags`, `sources`).
- Every page starts with YAML frontmatter. Required on every file:
`name`, `version`. Required on pages under `wiki/`: `confidence`,
`llm`, `contested`, `contradictions`. Optional: `title`, `created`,
`updated`, `type`, `tags`, `sources`.
- Use `[[wikilinks]]` to link between pages (minimum 2 outbound links per page).
- When updating a page, always bump the `updated` date.
- Every new page must be added to `index.md` under the correct section.
@@ -26,9 +33,13 @@ Personal knowledge base and inventory management.
## Frontmatter
`name` and `version` are required on every md file; all other fields are
optional. This is the single canonical frontmatter schema, identical to
project agent rule 10.1 (see SPEC 6.2).
`name` and `version` are required on every md file. Every page under
`wiki/` also requires the quality signals `confidence`, `llm`,
`contested`, and `contradictions`. How to set them is section 13 of
the [Fiona skill](../utils/skills/fiona/SKILL.md). All other fields
are optional. This is the single canonical frontmatter schema,
identical to project agent rule 10.1 (see SPEC 6.2). fmlint enforces
`name` and `version` only.
```yaml
---
@@ -40,8 +51,11 @@ updated: YYYY-MM-DD # bump when editing
type: entity | concept | comparison | query | summary | toc
sources: [raw/articles/source-name.md]
tags: [from taxonomy below]
# Optional quality signals:
# quality signals (required on pages under wiki/):
confidence: trusted | high | medium | low | zero
llm:
- model: none # required; model that last edited the page
- reasoning: high # when the model reports a level
contested: true
contradictions: [other-page-slug]
---
+152
View File
@@ -0,0 +1,152 @@
"""Tests for bootstrap install modes (SPEC 7.24).
Generated by AI/LLM: 2026-09-30 - local and no-env install options.
"""
import importlib.util
import pathlib
import subprocess
import pytest
ROOT = pathlib.Path(__file__).resolve().parents[1]
def _load_bootstrap_install():
"""Load scripts/bootstrap_install.py without installing the package."""
path = ROOT / "scripts" / "bootstrap_install.py"
spec = importlib.util.spec_from_file_location("bootstrap_install", path)
if spec is None or spec.loader is None:
raise RuntimeError(f"cannot load {path}")
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
@pytest.fixture(scope="module")
def bootstrap_install():
"""The pip-argument helper both bootstrap scripts call."""
return _load_bootstrap_install()
def _script(name: str) -> str:
"""Return one bootstrap script as text."""
return (ROOT / name).read_text(encoding="utf-8")
def _powershell(*args: str) -> subprocess.CompletedProcess[str]:
"""Run bootstrap.ps1 as a file, not dot-sourced."""
return subprocess.run(
[
"powershell",
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
str(ROOT / "bootstrap.ps1"),
*args,
],
capture_output=True,
text=True,
timeout=60,
check=False,
)
class TestPipInstallArgs:
"""SPEC 7.24.1 through 7.24.5: pip argument matrix."""
def test_local_installs_without_editable_mode(self, bootstrap_install):
"""--local installs '.' and does not pass -e or the dev extra."""
assert bootstrap_install.pip_install_args(local=True, no_env=False) == [
"install",
".",
]
def test_no_env_adds_user_and_keeps_editable_dev(self, bootstrap_install):
"""--no-env adds --user. Without --local the install stays editable."""
assert bootstrap_install.pip_install_args(local=False, no_env=True) == [
"install",
"--user",
"-e",
".[dev]",
]
def test_local_and_no_env_combine(self, bootstrap_install):
"""--local --no-env installs '.' with --user and without -e."""
assert bootstrap_install.pip_install_args(local=True, no_env=True) == [
"install",
"--user",
".",
]
def test_default_is_editable_dev_extra(self, bootstrap_install):
"""Neither flag keeps pip install -e '.[dev]'."""
assert bootstrap_install.pip_install_args(local=False, no_env=False) == [
"install",
"-e",
".[dev]",
]
def test_break_system_packages_after_user(self, bootstrap_install):
"""Bash inserts --break-system-packages after --user."""
args = bootstrap_install.pip_install_args(
local=True,
no_env=True,
break_system_packages=True,
)
assert args == ["install", "--user", "--break-system-packages", "."]
def test_break_system_packages_without_user(self, bootstrap_install):
"""Bash inserts --break-system-packages after install when no --user."""
args = bootstrap_install.pip_install_args(
local=False,
no_env=False,
break_system_packages=True,
)
assert args == [
"install",
"--break-system-packages",
"-e",
".[dev]",
]
def test_main_prints_one_argument_per_line(self, bootstrap_install, capsys):
"""The shell reads one pip argument per stdout line."""
assert bootstrap_install.main(["--local", "--no-env"]) == 0
captured = capsys.readouterr()
assert captured.out.splitlines() == ["install", "--user", "."]
assert captured.err == ""
class TestBootstrapScripts:
"""SPEC 7.24.2 and 7.24.6: both scripts honor the flags."""
def test_both_scripts_call_the_helper(self):
"""Bash and PowerShell pass --local and --no-env to the helper."""
for name in ("bootstrap", "bootstrap.ps1"):
text = _script(name)
assert "--local" in text
assert "--no-env" in text
assert "bootstrap_install.py" in text
def test_powershell_skips_venv_when_no_env(self):
"""PowerShell does not create a virtual environment when $NoEnv is set."""
assert "if (-not $NoEnv)" in _script("bootstrap.ps1")
def test_bash_skips_venv_when_no_env(self):
"""Bash does not create a virtual environment when NO_ENV is true."""
assert '[ "$NO_ENV" = true ]' in _script("bootstrap")
def test_powershell_local_without_no_env_must_be_dot_sourced(self):
"""--local alone is a venv install and must be dot-sourced."""
result = _powershell("--local")
combined = result.stdout + result.stderr
assert "Dot-source" in combined
assert "Unknown option" not in combined
def test_powershell_rejects_unknown_option(self):
"""An unrecognized flag is still reported as unknown."""
result = _powershell("--not-a-flag")
combined = result.stdout + result.stderr
assert "Unknown option" in combined
+6
View File
@@ -674,6 +674,12 @@ WARNING run_tests: pytest short summary missing from output; failure details com
(`feat:`, `fix:`, `docs:`, ...) per project agent rule 8.1
- [x] `fiona-assistant wiki graph` (SPEC 7.4): link parser, graph,
HTML template, and CLI in `src/wiki/graph_generator.py`
- [ ] Draw only important graph nodes until a parent is clicked
(SPEC 7.4.16)
- [ ] Setting `fiona.wiki.graph.node_importance_min_point`
- [ ] `0`, or a missing key, draws every node
- [ ] A positive integer hides a node whose `unique_points` is
below that integer until one of its parents is clicked
## P4 — Design Decisions Needed