From c7d834e6f02897b6a8901852e864b5fade25e2fa Mon Sep 17 00:00:00 2001 From: 0xLeif Date: Sun, 12 Jul 2026 13:05:00 -0600 Subject: [PATCH 1/3] Update(governance): adopt SpecSync 5 and Trust 1 --- .attest.json | 4 + .augur.toml | 3 + .claude/commands/specsync/create-change.md | 10 +++ .claude/commands/specsync/create-spec.md | 40 ++++++++++ .claude/skills/spec-sync/SKILL.md | 75 +++++++++++++++++++ .codex/skills/spec-sync/SKILL.md | 75 +++++++++++++++++++ .cursor/commands/specsync-create-change.md | 9 +++ .cursor/commands/specsync-create-spec.md | 35 +++++++++ .cursor/skills/spec-sync/SKILL.md | 75 +++++++++++++++++++ .gemini/commands/specsync/create-change.toml | 11 +++ .gemini/commands/specsync/create-spec.toml | 35 +++++++++ .gemini/skills/spec-sync/SKILL.md | 75 +++++++++++++++++++ .github/workflows/trust.yml | 23 ++++++ .specsync/adoption-report.json | 9 +++ .specsync/change.lock | 0 .../approvals.json | 3 + .../change.md | 26 +++++++ .../context.md | 8 ++ .../design.md | 10 +++ .../docs.md | 8 ++ .../plan.md | 12 +++ .../research.md | 10 +++ .../state.json | 46 ++++++++++++ .../tasks.md | 15 ++++ .../testing.md | 10 +++ .specsync/config.toml | 1 + .specsync/sdd.json | 40 ++++++++++ .specsync/version | 2 +- .trust.toml | 22 ++++++ AGENTS.md | 12 +++ fledge.toml | 9 +++ specs/sql/requirements.md | 24 ++++-- 32 files changed, 731 insertions(+), 6 deletions(-) create mode 100644 .attest.json create mode 100644 .augur.toml create mode 100644 .claude/commands/specsync/create-change.md create mode 100644 .claude/commands/specsync/create-spec.md create mode 100644 .claude/skills/spec-sync/SKILL.md create mode 100644 .codex/skills/spec-sync/SKILL.md create mode 100644 .cursor/commands/specsync-create-change.md create mode 100644 .cursor/commands/specsync-create-spec.md create mode 100644 .cursor/skills/spec-sync/SKILL.md create mode 100644 .gemini/commands/specsync/create-change.toml create mode 100644 .gemini/commands/specsync/create-spec.toml create mode 100644 .gemini/skills/spec-sync/SKILL.md create mode 100644 .github/workflows/trust.yml create mode 100644 .specsync/adoption-report.json create mode 100644 .specsync/change.lock create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/approvals.json create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/change.md create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/context.md create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/design.md create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/docs.md create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/plan.md create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/research.md create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/tasks.md create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/testing.md create mode 100644 .specsync/sdd.json create mode 100644 .trust.toml create mode 100644 AGENTS.md create mode 100644 fledge.toml diff --git a/.attest.json b/.attest.json new file mode 100644 index 0000000..ba4a063 --- /dev/null +++ b/.attest.json @@ -0,0 +1,4 @@ +{ + "requireAttestation": true, + "requireTestsPassed": true +} diff --git a/.augur.toml b/.augur.toml new file mode 100644 index 0000000..031b459 --- /dev/null +++ b/.augur.toml @@ -0,0 +1,3 @@ +[thresholds] +review = 35 +block = 65 diff --git a/.claude/commands/specsync/create-change.md b/.claude/commands/specsync/create-change.md new file mode 100644 index 0000000..04707cc --- /dev/null +++ b/.claude/commands/specsync/create-change.md @@ -0,0 +1,10 @@ +--- +description: Create and guide a verified spec-sync SDD change through its deterministic interview +argument-hint: +--- + +1. Run `specsync change new "$ARGUMENTS" --json`. +2. Read the returned `questions` array and interview the user one question at a time. +3. Record each answer with `specsync change answer --json`. +4. Continue until the question list is empty, then show the selected artifacts and next action. +5. Do not approve, implement, verify, accept, or archive until the corresponding human gate or work stage is reached. diff --git a/.claude/commands/specsync/create-spec.md b/.claude/commands/specsync/create-spec.md new file mode 100644 index 0000000..a424e76 --- /dev/null +++ b/.claude/commands/specsync/create-spec.md @@ -0,0 +1,40 @@ +--- +description: Scaffold a new spec-sync module spec from a module name or a natural-language feature description (full scaffold by default, or minimal with --minimal) +argument-hint: [--minimal] +--- + +Create a new spec-sync module spec. + +Arguments: `$ARGUMENTS` + +1. Parse the arguments above: the first whitespace-separated token is the + module name. If the arguments also contain `--minimal` (in any position), + remove it and remember that minimal mode was requested. +2. Look at whatever text remains. It will be one of: + - **A bare module name** — a short identifier like `auth-service` or + `billing`. Use it as-is. + - **A free-text feature description** — a sentence or phrase describing + what to build, e.g. `"I want a feature that lets users export their + data as CSV"`. In this case, invent a short, kebab-case module name that + captures the idea (e.g. `csv-export`). If the right name is ambiguous, + ask the user to confirm or rename it before continuing. Keep the full + description at hand — you'll use it in step 5. +3. If minimal mode was requested, run: + ``` + specsync new + ``` + This creates a minimal spec only (no companion files). +4. Otherwise (default), run: + ``` + specsync scaffold + ``` + This creates the spec, companion files (`tasks.md`, `requirements.md`, + `context.md`, `testing.md`, and `design.md` if `companions.design` is + enabled), a registry entry, and auto-detects related source files. +5. Open the newly created `specs//.spec.md` and fill + in the `Purpose`, `Requirements`, and `Public API` sections. If a free-text + description was given in step 2, use it directly to draft these sections — + ask clarifying questions if it's underspecified, but do not leave the + sections as unfilled placeholder text. Do the same for `requirements.md` + (acceptance criteria) and `tasks.md` (initial task breakdown), if present. +6. Run `specsync check` to confirm the new spec passes validation. diff --git a/.claude/skills/spec-sync/SKILL.md b/.claude/skills/spec-sync/SKILL.md new file mode 100644 index 0000000..de24d12 --- /dev/null +++ b/.claude/skills/spec-sync/SKILL.md @@ -0,0 +1,75 @@ +--- +name: spec-sync +description: Keep markdown module specs in specs// synchronized with source code using spec-sync. Use this whenever creating, editing, or reviewing code in a module that has (or should have) a spec, or whenever the user mentions specs, spec-sync, companion files (tasks.md/requirements.md/context.md/testing.md/design.md), or asks to add/update a module's documentation. +--- + +# Spec-Sync Workflow + +This project uses [spec-sync](https://github.com/CorvidLabs/spec-sync) for bidirectional spec-to-code validation. Specs live in `specs//.spec.md`. + +## Companion files + +## Verified SDD change lifecycle (5.0) + +For every meaningful source, test, public documentation, schema, or configuration change: + +1. Run `specsync change new "" --json` and conduct the returned interview with the user. +2. Use `specsync change answer --json` until no questions remain. +3. Complete the adaptively selected artifacts and semantic deltas. Requirements use stable + `REQ--` IDs, a normative SHALL statement, and acceptance criteria. +4. Ask the user for the definition approval, then run `specsync change approve `. +5. Run `specsync change start ` before editing implementation code. +6. Keep tasks and artifacts current, then run `specsync change verify `. +7. Present verification evidence and ask for closing approval. Only after explicit approval, + run `specsync change accept `; archive separately with `specsync change archive `. + +Never invent or self-grant either human approval. If an approved definition changes, its digest +becomes stale and must be approved again. `specsync check` validates canonical specs plus approved +active deltas, requirement-to-test evidence, change coverage, and CI gates. + +Each canonical spec may have policy-selected companion files. Read and update the ones present; do not create empty companions only for ceremony: + +- **`tasks.md`** — Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. +- **`requirements.md`** — Acceptance criteria and user stories. These are permanent invariants, not tasks — do not check them off. Update if requirements change. +- **`context.md`** — Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. +- **`testing.md`** — Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. +- **`design.md`** *(opt-in)* — Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. + +## Before modifying any module + +1. Read the relevant spec in `specs//.spec.md` +2. Read whichever companion files are present (`requirements.md`, `tasks.md`, `context.md`, `testing.md`, `design.md`, or project-defined files) +3. After changes, run `specsync check` to verify specs still pass + +## After completing work + +1. Mark completed items in `tasks.md` — check off finished tasks, add new ones discovered +2. Update `context.md` — record decisions made, update current status +3. If requirements changed, update `requirements.md` acceptance criteria +4. If test coverage changed, update `testing.md` with new test files or edge cases +5. If UI/layout changed, update `design.md` with revised layout, components, or tokens + +## Before creating a PR + +Run `specsync check --strict` — all specs must pass with zero warnings. + +## When adding new modules + +Run `specsync scaffold ` to create a spec, companion files, a registry +entry, and auto-detected source files — or `specsync new ` for a +minimal spec-only draft. Complete the spec before writing code. The +`/specsync:create-spec` command (or tool-equivalent) runs this for you, and +accepts either a bare module name or a natural-language feature description +(e.g. `/specsync:create-spec "I want a feature that lets users export their +data as CSV"`) — pass a description and it will pick a module name and use +the description to draft the spec's Purpose and Requirements. + +## Key commands + +- `specsync check` — validate all specs against source code +- `specsync check --json` — machine-readable validation output +- `specsync coverage` — show which modules lack specs +- `specsync score` — quality score for each spec (0-100) +- `specsync scaffold ` — full scaffold: spec + companions + registry entry + source detection +- `specsync new ` — quick-create a minimal spec (add `--full` for companions) +- `specsync resolve --remote` — verify cross-project dependencies diff --git a/.codex/skills/spec-sync/SKILL.md b/.codex/skills/spec-sync/SKILL.md new file mode 100644 index 0000000..de24d12 --- /dev/null +++ b/.codex/skills/spec-sync/SKILL.md @@ -0,0 +1,75 @@ +--- +name: spec-sync +description: Keep markdown module specs in specs// synchronized with source code using spec-sync. Use this whenever creating, editing, or reviewing code in a module that has (or should have) a spec, or whenever the user mentions specs, spec-sync, companion files (tasks.md/requirements.md/context.md/testing.md/design.md), or asks to add/update a module's documentation. +--- + +# Spec-Sync Workflow + +This project uses [spec-sync](https://github.com/CorvidLabs/spec-sync) for bidirectional spec-to-code validation. Specs live in `specs//.spec.md`. + +## Companion files + +## Verified SDD change lifecycle (5.0) + +For every meaningful source, test, public documentation, schema, or configuration change: + +1. Run `specsync change new "" --json` and conduct the returned interview with the user. +2. Use `specsync change answer --json` until no questions remain. +3. Complete the adaptively selected artifacts and semantic deltas. Requirements use stable + `REQ--` IDs, a normative SHALL statement, and acceptance criteria. +4. Ask the user for the definition approval, then run `specsync change approve `. +5. Run `specsync change start ` before editing implementation code. +6. Keep tasks and artifacts current, then run `specsync change verify `. +7. Present verification evidence and ask for closing approval. Only after explicit approval, + run `specsync change accept `; archive separately with `specsync change archive `. + +Never invent or self-grant either human approval. If an approved definition changes, its digest +becomes stale and must be approved again. `specsync check` validates canonical specs plus approved +active deltas, requirement-to-test evidence, change coverage, and CI gates. + +Each canonical spec may have policy-selected companion files. Read and update the ones present; do not create empty companions only for ceremony: + +- **`tasks.md`** — Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. +- **`requirements.md`** — Acceptance criteria and user stories. These are permanent invariants, not tasks — do not check them off. Update if requirements change. +- **`context.md`** — Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. +- **`testing.md`** — Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. +- **`design.md`** *(opt-in)* — Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. + +## Before modifying any module + +1. Read the relevant spec in `specs//.spec.md` +2. Read whichever companion files are present (`requirements.md`, `tasks.md`, `context.md`, `testing.md`, `design.md`, or project-defined files) +3. After changes, run `specsync check` to verify specs still pass + +## After completing work + +1. Mark completed items in `tasks.md` — check off finished tasks, add new ones discovered +2. Update `context.md` — record decisions made, update current status +3. If requirements changed, update `requirements.md` acceptance criteria +4. If test coverage changed, update `testing.md` with new test files or edge cases +5. If UI/layout changed, update `design.md` with revised layout, components, or tokens + +## Before creating a PR + +Run `specsync check --strict` — all specs must pass with zero warnings. + +## When adding new modules + +Run `specsync scaffold ` to create a spec, companion files, a registry +entry, and auto-detected source files — or `specsync new ` for a +minimal spec-only draft. Complete the spec before writing code. The +`/specsync:create-spec` command (or tool-equivalent) runs this for you, and +accepts either a bare module name or a natural-language feature description +(e.g. `/specsync:create-spec "I want a feature that lets users export their +data as CSV"`) — pass a description and it will pick a module name and use +the description to draft the spec's Purpose and Requirements. + +## Key commands + +- `specsync check` — validate all specs against source code +- `specsync check --json` — machine-readable validation output +- `specsync coverage` — show which modules lack specs +- `specsync score` — quality score for each spec (0-100) +- `specsync scaffold ` — full scaffold: spec + companions + registry entry + source detection +- `specsync new ` — quick-create a minimal spec (add `--full` for companions) +- `specsync resolve --remote` — verify cross-project dependencies diff --git a/.cursor/commands/specsync-create-change.md b/.cursor/commands/specsync-create-change.md new file mode 100644 index 0000000..49402f3 --- /dev/null +++ b/.cursor/commands/specsync-create-change.md @@ -0,0 +1,9 @@ +Create a verified spec-sync SDD change. + +Arguments: $ARGUMENTS + +1. Run `specsync change new "$ARGUMENTS" --json`. +2. Read the returned `questions` array and interview the user one question at a time. +3. Record each answer with `specsync change answer --json`. +4. Continue until the question list is empty, then show the selected artifacts and next action. +5. Do not approve, implement, verify, accept, or archive until the corresponding human gate or work stage is reached. diff --git a/.cursor/commands/specsync-create-spec.md b/.cursor/commands/specsync-create-spec.md new file mode 100644 index 0000000..0f20b4c --- /dev/null +++ b/.cursor/commands/specsync-create-spec.md @@ -0,0 +1,35 @@ +Create a new spec-sync module spec. + +Arguments: $ARGUMENTS + +1. Parse the arguments above: the first whitespace-separated token is the + module name. If the arguments also contain `--minimal` (in any position), + remove it and remember that minimal mode was requested. +2. Look at whatever text remains. It will be one of: + - **A bare module name** — a short identifier like `auth-service` or + `billing`. Use it as-is. + - **A free-text feature description** — a sentence or phrase describing + what to build, e.g. `"I want a feature that lets users export their + data as CSV"`. In this case, invent a short, kebab-case module name that + captures the idea (e.g. `csv-export`). If the right name is ambiguous, + ask the user to confirm or rename it before continuing. Keep the full + description at hand — you'll use it in step 5. +3. If minimal mode was requested, run: + ``` + specsync new + ``` + This creates a minimal spec only (no companion files). +4. Otherwise (default), run: + ``` + specsync scaffold + ``` + This creates the spec, companion files (`tasks.md`, `requirements.md`, + `context.md`, `testing.md`, and `design.md` if `companions.design` is + enabled), a registry entry, and auto-detects related source files. +5. Open the newly created `specs//.spec.md` and fill + in the `Purpose`, `Requirements`, and `Public API` sections. If a free-text + description was given in step 2, use it directly to draft these sections — + ask clarifying questions if it's underspecified, but do not leave the + sections as unfilled placeholder text. Do the same for `requirements.md` + (acceptance criteria) and `tasks.md` (initial task breakdown), if present. +6. Run `specsync check` to confirm the new spec passes validation. diff --git a/.cursor/skills/spec-sync/SKILL.md b/.cursor/skills/spec-sync/SKILL.md new file mode 100644 index 0000000..de24d12 --- /dev/null +++ b/.cursor/skills/spec-sync/SKILL.md @@ -0,0 +1,75 @@ +--- +name: spec-sync +description: Keep markdown module specs in specs// synchronized with source code using spec-sync. Use this whenever creating, editing, or reviewing code in a module that has (or should have) a spec, or whenever the user mentions specs, spec-sync, companion files (tasks.md/requirements.md/context.md/testing.md/design.md), or asks to add/update a module's documentation. +--- + +# Spec-Sync Workflow + +This project uses [spec-sync](https://github.com/CorvidLabs/spec-sync) for bidirectional spec-to-code validation. Specs live in `specs//.spec.md`. + +## Companion files + +## Verified SDD change lifecycle (5.0) + +For every meaningful source, test, public documentation, schema, or configuration change: + +1. Run `specsync change new "" --json` and conduct the returned interview with the user. +2. Use `specsync change answer --json` until no questions remain. +3. Complete the adaptively selected artifacts and semantic deltas. Requirements use stable + `REQ--` IDs, a normative SHALL statement, and acceptance criteria. +4. Ask the user for the definition approval, then run `specsync change approve `. +5. Run `specsync change start ` before editing implementation code. +6. Keep tasks and artifacts current, then run `specsync change verify `. +7. Present verification evidence and ask for closing approval. Only after explicit approval, + run `specsync change accept `; archive separately with `specsync change archive `. + +Never invent or self-grant either human approval. If an approved definition changes, its digest +becomes stale and must be approved again. `specsync check` validates canonical specs plus approved +active deltas, requirement-to-test evidence, change coverage, and CI gates. + +Each canonical spec may have policy-selected companion files. Read and update the ones present; do not create empty companions only for ceremony: + +- **`tasks.md`** — Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. +- **`requirements.md`** — Acceptance criteria and user stories. These are permanent invariants, not tasks — do not check them off. Update if requirements change. +- **`context.md`** — Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. +- **`testing.md`** — Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. +- **`design.md`** *(opt-in)* — Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. + +## Before modifying any module + +1. Read the relevant spec in `specs//.spec.md` +2. Read whichever companion files are present (`requirements.md`, `tasks.md`, `context.md`, `testing.md`, `design.md`, or project-defined files) +3. After changes, run `specsync check` to verify specs still pass + +## After completing work + +1. Mark completed items in `tasks.md` — check off finished tasks, add new ones discovered +2. Update `context.md` — record decisions made, update current status +3. If requirements changed, update `requirements.md` acceptance criteria +4. If test coverage changed, update `testing.md` with new test files or edge cases +5. If UI/layout changed, update `design.md` with revised layout, components, or tokens + +## Before creating a PR + +Run `specsync check --strict` — all specs must pass with zero warnings. + +## When adding new modules + +Run `specsync scaffold ` to create a spec, companion files, a registry +entry, and auto-detected source files — or `specsync new ` for a +minimal spec-only draft. Complete the spec before writing code. The +`/specsync:create-spec` command (or tool-equivalent) runs this for you, and +accepts either a bare module name or a natural-language feature description +(e.g. `/specsync:create-spec "I want a feature that lets users export their +data as CSV"`) — pass a description and it will pick a module name and use +the description to draft the spec's Purpose and Requirements. + +## Key commands + +- `specsync check` — validate all specs against source code +- `specsync check --json` — machine-readable validation output +- `specsync coverage` — show which modules lack specs +- `specsync score` — quality score for each spec (0-100) +- `specsync scaffold ` — full scaffold: spec + companions + registry entry + source detection +- `specsync new ` — quick-create a minimal spec (add `--full` for companions) +- `specsync resolve --remote` — verify cross-project dependencies diff --git a/.gemini/commands/specsync/create-change.toml b/.gemini/commands/specsync/create-change.toml new file mode 100644 index 0000000..b4b7de6 --- /dev/null +++ b/.gemini/commands/specsync/create-change.toml @@ -0,0 +1,11 @@ +description = "Create and guide a verified spec-sync SDD change through its deterministic interview" + +prompt = """ +Arguments: {{args}} + +1. Run `specsync change new "$ARGUMENTS" --json`. +2. Read the returned `questions` array and interview the user one question at a time. +3. Record each answer with `specsync change answer --json`. +4. Continue until the question list is empty, then show the selected artifacts and next action. +5. Do not approve, implement, verify, accept, or archive until the corresponding human gate or work stage is reached. +""" diff --git a/.gemini/commands/specsync/create-spec.toml b/.gemini/commands/specsync/create-spec.toml new file mode 100644 index 0000000..73789f1 --- /dev/null +++ b/.gemini/commands/specsync/create-spec.toml @@ -0,0 +1,35 @@ +description = "Scaffold a new spec-sync module spec from a module name or a natural-language feature description (full scaffold by default, or minimal with --minimal)" + +prompt = """ +Create a new spec-sync module spec. + +Arguments: {{args}} + +1. Parse the arguments above: the first whitespace-separated token is the + module name. If the arguments also contain --minimal (in any position), + remove it and remember that minimal mode was requested. +2. Look at whatever text remains. It will be one of: + - A bare module name - a short identifier like auth-service or billing. + Use it as-is. + - A free-text feature description - a sentence or phrase describing what + to build, e.g. "I want a feature that lets users export their data as + CSV". In this case, invent a short, kebab-case module name that captures + the idea (e.g. csv-export). If the right name is ambiguous, ask the user + to confirm or rename it before continuing. Keep the full description at + hand - you'll use it in step 5. +3. If minimal mode was requested, run: + specsync new + This creates a minimal spec only (no companion files). +4. Otherwise (default), run: + specsync scaffold + This creates the spec, companion files (tasks.md, requirements.md, + context.md, testing.md, and design.md if companions.design is enabled), + a registry entry, and auto-detects related source files. +5. Open the newly created specs//.spec.md and fill + in the Purpose, Requirements, and Public API sections. If a free-text + description was given in step 2, use it directly to draft these sections - + ask clarifying questions if it's underspecified, but do not leave the + sections as unfilled placeholder text. Do the same for requirements.md + (acceptance criteria) and tasks.md (initial task breakdown), if present. +6. Run specsync check to confirm the new spec passes validation. +""" diff --git a/.gemini/skills/spec-sync/SKILL.md b/.gemini/skills/spec-sync/SKILL.md new file mode 100644 index 0000000..de24d12 --- /dev/null +++ b/.gemini/skills/spec-sync/SKILL.md @@ -0,0 +1,75 @@ +--- +name: spec-sync +description: Keep markdown module specs in specs// synchronized with source code using spec-sync. Use this whenever creating, editing, or reviewing code in a module that has (or should have) a spec, or whenever the user mentions specs, spec-sync, companion files (tasks.md/requirements.md/context.md/testing.md/design.md), or asks to add/update a module's documentation. +--- + +# Spec-Sync Workflow + +This project uses [spec-sync](https://github.com/CorvidLabs/spec-sync) for bidirectional spec-to-code validation. Specs live in `specs//.spec.md`. + +## Companion files + +## Verified SDD change lifecycle (5.0) + +For every meaningful source, test, public documentation, schema, or configuration change: + +1. Run `specsync change new "" --json` and conduct the returned interview with the user. +2. Use `specsync change answer --json` until no questions remain. +3. Complete the adaptively selected artifacts and semantic deltas. Requirements use stable + `REQ--` IDs, a normative SHALL statement, and acceptance criteria. +4. Ask the user for the definition approval, then run `specsync change approve `. +5. Run `specsync change start ` before editing implementation code. +6. Keep tasks and artifacts current, then run `specsync change verify `. +7. Present verification evidence and ask for closing approval. Only after explicit approval, + run `specsync change accept `; archive separately with `specsync change archive `. + +Never invent or self-grant either human approval. If an approved definition changes, its digest +becomes stale and must be approved again. `specsync check` validates canonical specs plus approved +active deltas, requirement-to-test evidence, change coverage, and CI gates. + +Each canonical spec may have policy-selected companion files. Read and update the ones present; do not create empty companions only for ceremony: + +- **`tasks.md`** — Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. +- **`requirements.md`** — Acceptance criteria and user stories. These are permanent invariants, not tasks — do not check them off. Update if requirements change. +- **`context.md`** — Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. +- **`testing.md`** — Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. +- **`design.md`** *(opt-in)* — Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. + +## Before modifying any module + +1. Read the relevant spec in `specs//.spec.md` +2. Read whichever companion files are present (`requirements.md`, `tasks.md`, `context.md`, `testing.md`, `design.md`, or project-defined files) +3. After changes, run `specsync check` to verify specs still pass + +## After completing work + +1. Mark completed items in `tasks.md` — check off finished tasks, add new ones discovered +2. Update `context.md` — record decisions made, update current status +3. If requirements changed, update `requirements.md` acceptance criteria +4. If test coverage changed, update `testing.md` with new test files or edge cases +5. If UI/layout changed, update `design.md` with revised layout, components, or tokens + +## Before creating a PR + +Run `specsync check --strict` — all specs must pass with zero warnings. + +## When adding new modules + +Run `specsync scaffold ` to create a spec, companion files, a registry +entry, and auto-detected source files — or `specsync new ` for a +minimal spec-only draft. Complete the spec before writing code. The +`/specsync:create-spec` command (or tool-equivalent) runs this for you, and +accepts either a bare module name or a natural-language feature description +(e.g. `/specsync:create-spec "I want a feature that lets users export their +data as CSV"`) — pass a description and it will pick a module name and use +the description to draft the spec's Purpose and Requirements. + +## Key commands + +- `specsync check` — validate all specs against source code +- `specsync check --json` — machine-readable validation output +- `specsync coverage` — show which modules lack specs +- `specsync score` — quality score for each spec (0-100) +- `specsync scaffold ` — full scaffold: spec + companions + registry entry + source detection +- `specsync new ` — quick-create a minimal spec (add `--full` for companions) +- `specsync resolve --remote` — verify cross-project dependencies diff --git a/.github/workflows/trust.yml b/.github/workflows/trust.yml new file mode 100644 index 0000000..7f8e350 --- /dev/null +++ b/.github/workflows/trust.yml @@ -0,0 +1,23 @@ +name: trust + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + trust: + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - uses: actions/checkout@v5 + with: + fetch-depth: 0 + - name: Install native verification tools + run: sudo apt-get update && sudo apt-get install -y jq sqlite3 + - name: CorvidLabs Trust gate + id: trust + uses: CorvidLabs/trust@9d32b5786d2e9e4d39fc581c0091c721ee3d4226 # v1.0.0 diff --git a/.specsync/adoption-report.json b/.specsync/adoption-report.json new file mode 100644 index 0000000..6a6d7c1 --- /dev/null +++ b/.specsync/adoption-report.json @@ -0,0 +1,9 @@ +{ + "bootstrap_policy": { + "base_commit": "a4e307b1607bb9b2cad4d62488d634643552526e", + "digest": "2f696488563fdab00793ed51018de70841e6cbf81d4d8d0e9a868b1435d52161", + "path": ".specsync/sdd.json" + }, + "generated_at": 1783882979, + "requirements_needing_ids": [] +} diff --git a/.specsync/change.lock b/.specsync/change.lock new file mode 100644 index 0000000..e69de29 diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/approvals.json b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/approvals.json new file mode 100644 index 0000000..08ac789 --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/approvals.json @@ -0,0 +1,3 @@ +{ + "approvals": [] +} diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/change.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/change.md new file mode 100644 index 0000000..8cf4b4e --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/change.md @@ -0,0 +1,26 @@ +--- +id: CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin +state: draft +type: migration +base_commit: a4e307b1607bb9b2cad4d62488d634643552526e +--- + +# Adopt SpecSync 5.0.1 and Trust 1.0.0 governance for the SQLite Fledge plugin + +## Intent + +Adopt SpecSync 5.0.1 and Trust 1.0.0 governance for the SQLite Fledge plugin + +## Affected Canonical Specs + +- `sql` + +## Acceptance Criteria + +- SpecSync strict checks pass at explicit advisory threshold 0 for the extensionless Bash executable; existing requirements have deterministic IDs; all four integrations are installed; Trust doctor and verification pass; syntax +- 26 database safety tests +- and manifest validation remain green. + +## No-spec Rationale + +Not applicable diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/context.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/context.md new file mode 100644 index 0000000..595105b --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/context.md @@ -0,0 +1,8 @@ +--- +change: CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin +artifact: context +--- + +# Context + +The SQLite plugin manages project-local initialization, transactional migrations, guarded ad-hoc queries, and schema inspection through fledge-v1. The rollout adopts its active contract without weakening persistence or destructive-query safety. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/design.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/design.md new file mode 100644 index 0000000..4a4b554 --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/design.md @@ -0,0 +1,10 @@ +--- +change: CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin +artifact: design +--- + +# Design + +Assign deterministic IDs to the active requirements, stamp SpecSync 5.0.1, and install all integrations. + +Trust runs Bash syntax, all 26 database safety tests, and manifest validation through Fledge. Risk blocks, provenance is progressive, coverage is advisory 0 with rationale, and Atlas stays disabled because Pages remains independent. The workflow pins Trust 1.0.0 immutably. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/docs.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/docs.md new file mode 100644 index 0000000..62aaee6 --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/docs.md @@ -0,0 +1,8 @@ +--- +change: CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin +artifact: docs +--- + +# Docs + +The managed `AGENTS.md` block documents the unified verification path. Existing public database behavior and safety guidance remains unchanged. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/plan.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/plan.md new file mode 100644 index 0000000..17fafd3 --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/plan.md @@ -0,0 +1,12 @@ +--- +change: CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin +artifact: plan +--- + +# Plan + +1. Preserve the active initialization, migration, query, and schema contract. +2. Assign stable requirements and adopt SpecSync 5.0.1 at threshold 0. +3. Install all integrations and add the complete native database lane. +4. Add standard Trust policy and immutable workflow. +5. Validate locally and preserve existing test and Pages workflows. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/research.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/research.md new file mode 100644 index 0000000..9d32a24 --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/research.md @@ -0,0 +1,10 @@ +--- +change: CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin +artifact: research +--- + +# Research + +The hermetic Python harness covers 26 initialization, migration ordering/idempotence/rollback, parameter binding and injection, destructive-operation blocking and override, DML counts, schema, version, and help cases. + +SpecSync does not measure the extensionless Bash executable, so coverage is explicitly advisory 0 and the native syntax/database suite is blocking. ShellCheck's pre-existing informational jq-quoting findings are not enforced by current CI and remain isolated. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json new file mode 100644 index 0000000..0fa0cd3 --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json @@ -0,0 +1,46 @@ +{ + "schema_version": 1, + "id": "CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin", + "slug": "adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin", + "title": "Adopt SpecSync 5.0.1 and Trust 1.0.0 governance for the SQLite Fledge plugin", + "description": "Adopt SpecSync 5.0.1 and Trust 1.0.0 governance for the SQLite Fledge plugin", + "kind": "migration", + "state": "draft", + "base_commit": "a4e307b1607bb9b2cad4d62488d634643552526e", + "created_at": 1783883062, + "updated_at": 1783883069, + "affected_specs": [ + "sql" + ], + "affected_paths": [ + "bin/", + "test/", + "plugin.toml", + "fledge.toml", + ".github/", + ".specsync/", + "specs/", + ".trust.toml" + ], + "no_spec_change": false, + "no_spec_change_rationale": null, + "acceptance_criteria": [ + "SpecSync strict checks pass at explicit advisory threshold 0 for the extensionless Bash executable; existing requirements have deterministic IDs; all four integrations are installed; Trust doctor and verification pass; syntax", + "26 database safety tests", + "and manifest validation remain green." + ], + "selected_artifacts": [ + "context", + "research", + "design", + "plan", + "tasks", + "testing", + "docs" + ], + "dependencies": [], + "answers": { + "architecture_risk": "yes", + "public_contract": "no" + } +} diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/tasks.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/tasks.md new file mode 100644 index 0000000..b6d86c4 --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/tasks.md @@ -0,0 +1,15 @@ +--- +change: CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin +artifact: tasks +--- + +# Tasks + +- [x] Preserve the active SQLite specification and assign deterministic IDs. +- [x] Adopt and stamp SpecSync 5.0.1 with threshold-0 rationale. +- [x] Install all four integrations. +- [x] Add the three-step database safety lane and Trust policy. +- [x] Add the immutable Trust 1.0.0 workflow. +- [x] Validate syntax, 26 tests, manifest, integrations, and Trust. +- [ ] Record definition approval and execute the verified lifecycle. +- [ ] Confirm hosted checks and preserve branch requirements. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/testing.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/testing.md new file mode 100644 index 0000000..b07a71d --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/testing.md @@ -0,0 +1,10 @@ +--- +change: CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin +artifact: testing +--- + +# Testing + +Local acceptance requires Bash syntax, all 26 database safety cases, manifest validation, strict SpecSync checks at threshold 0, four integrations, healthy Trust doctor, and a clean diff. + +Hosted acceptance requires the new `trust` job and existing integration-test job to pass on Ubuntu while Pages remains independent. diff --git a/.specsync/config.toml b/.specsync/config.toml index 2c8002e..0f9226b 100644 --- a/.specsync/config.toml +++ b/.specsync/config.toml @@ -1,3 +1,4 @@ +# SpecSync 5 configuration specs_dir = "specs" source_dirs = ["bin"] exclude_dirs = [] diff --git a/.specsync/sdd.json b/.specsync/sdd.json new file mode 100644 index 0000000..8b970b6 --- /dev/null +++ b/.specsync/sdd.json @@ -0,0 +1,40 @@ +{ + "version": 1, + "enabled": true, + "require_change_for_meaningful_files": true, + "meaningful_paths": [ + "src/", + "tests/", + "site/", + ".github/", + "Cargo.toml", + "Cargo.lock", + "action.yml", + "package.json", + "bun.lock", + "package-lock.json", + "pnpm-lock.yaml", + "yarn.lock", + "Package.swift", + "Package.resolved", + "go.mod", + "go.sum", + "pyproject.toml", + "uv.lock", + "requirements.txt", + ".specsync/sdd.json", + ".specsync/config.toml", + ".specsync/config.json", + ".specsync/version", + "bin/" + ], + "ignored_paths": [ + ".specsync/", + "specs/" + ], + "verification_commands": [ + "bash -n bin/fledge-sql && python3 test/test.py" + ], + "custom_artifacts": {}, + "principles_file": null +} diff --git a/.specsync/version b/.specsync/version index f77856a..6b244dc 100644 --- a/.specsync/version +++ b/.specsync/version @@ -1 +1 @@ -4.3.1 +5.0.1 diff --git a/.trust.toml b/.trust.toml new file mode 100644 index 0000000..9f026c7 --- /dev/null +++ b/.trust.toml @@ -0,0 +1,22 @@ +schema_version = 1 +profile = "standard" + +[lifecycle] +command = ["fledge", "lanes", "run", "verify"] + +[contract] +enabled = true +require_coverage = 0 +skip_reason = "SpecSync does not measure the extensionless Bash executable; syntax and 26 database safety tests are blocking" + +[risk] +threshold = "block" + +[provenance] +mode = "soft" +policy = ".attest.json" +skip_reason = "" + +[atlas] +enabled = false +skip_reason = "Standalone Pages publication remains independently managed" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3da08a2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,12 @@ + +## CorvidLabs trust toolchain + +This repository uses one trust gate. Every session must use it and must not bypass or weaken it. + +- Run `fledge trust verify` before calling a change complete. +- Keep module specs synchronized with implementation changes. +- Treat an Augur block verdict as a hard stop that must be surfaced and de-risked. +- Record and verify provenance with Attest after the repository's verification lane passes. +- Keep generated trust configuration and this managed block in place. + + diff --git a/fledge.toml b/fledge.toml new file mode 100644 index 0000000..8a95aab --- /dev/null +++ b/fledge.toml @@ -0,0 +1,9 @@ +# fledge.toml — project task definitions +[tasks] +syntax = "bash -n bin/fledge-sql" +test = "python3 test/test.py" +manifest = "grep -q 'binary = \"bin/fledge-sql\"' plugin.toml && grep -q 'protocol = \"fledge-v1\"' plugin.toml" + +[lanes.verify] +description = "Syntax-check and test the guarded SQLite plugin" +steps = ["syntax", "test", "manifest"] diff --git a/specs/sql/requirements.md b/specs/sql/requirements.md index 896b91e..2bd4c05 100644 --- a/specs/sql/requirements.md +++ b/specs/sql/requirements.md @@ -11,11 +11,25 @@ spec: sql.spec.md ## Acceptance Criteria -- `fledge sql init` creates a database file and stores the path -- `fledge sql migrate` applies unapplied .sql files in order and tracks them -- `fledge sql query` executes SQL and returns formatted results -- `fledge sql schema` shows all tables, indexes, and views -- All commands use fledge-v1 protocol for I/O +### REQ-sql-001 + +`fledge sql init` creates the selected project database and stores its path through the host protocol. + +### REQ-sql-002 + +`fledge sql migrate` applies unapplied SQL files in filename order, transactionally, and records them idempotently. + +### REQ-sql-003 + +`fledge sql query` executes SQL against the initialized database and returns formatted results. + +### REQ-sql-004 + +`fledge sql schema` shows user tables, indexes, and views for the initialized database. + +### REQ-sql-005 + +All commands use the fledge-v1 protocol for input, output, persistence, and host execution. ## Constraints From 6a58ec1709b19cd796e908177dd06979e115d5f7 Mon Sep 17 00:00:00 2001 From: 0xLeif Date: Sun, 12 Jul 2026 16:23:02 -0600 Subject: [PATCH 2/3] Fix: preserve SDD acceptance criteria as one statement --- .../state.json | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json index 0fa0cd3..b0e15eb 100644 --- a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json @@ -25,9 +25,7 @@ "no_spec_change": false, "no_spec_change_rationale": null, "acceptance_criteria": [ - "SpecSync strict checks pass at explicit advisory threshold 0 for the extensionless Bash executable; existing requirements have deterministic IDs; all four integrations are installed; Trust doctor and verification pass; syntax", - "26 database safety tests", - "and manifest validation remain green." + "SpecSync strict checks pass at explicit advisory threshold 0 for the extensionless Bash executable; existing requirements have deterministic IDs; all four integrations are installed; Trust doctor and verification pass; syntax, 26 database safety tests, and manifest validation remain green." ], "selected_artifacts": [ "context", From 077008d67ad9610d6fe87f74656fabd2b6520329 Mon Sep 17 00:00:00 2001 From: 0xLeif Date: Tue, 14 Jul 2026 05:14:02 -0600 Subject: [PATCH 3/3] fix(governance): complete SpecSync contract and lifecycle evidence --- .../approvals.json | 24 +++++- .../change.md | 10 ++- .../context.md | 7 +- .../deltas/sql.md | 76 +++++++++++++++++++ .../design.md | 13 +++- .../docs.md | 5 +- .../plan.md | 12 +-- .../research.md | 11 ++- .../state.json | 18 ++++- .../tasks.md | 15 ++-- .../testing.md | 26 ++++++- .../verification.json | 28 +++++++ .specsync/sdd.json | 34 ++++----- .trust.toml | 2 +- fledge.toml | 5 +- specs/sql/requirements.md | 69 +++++++++++++++-- specs/sql/sql.spec.md | 42 +++++++--- specs/sql/tasks.md | 2 + specs/sql/testing.md | 22 +++--- test/governance.py | 56 ++++++++++++++ 20 files changed, 400 insertions(+), 77 deletions(-) create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/deltas/sql.md create mode 100644 .specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/verification.json create mode 100644 test/governance.py diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/approvals.json b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/approvals.json index 08ac789..be04498 100644 --- a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/approvals.json +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/approvals.json @@ -1,3 +1,25 @@ { - "approvals": [] + "approvals": [ + { + "gate": "definition", + "actor": "user:0xLeif", + "timestamp": 1784027433, + "digest": "b4880dedcdf0c9a6918f23ad18530a2c0e4a4a8a6af624d01fb81d7299c25fb4", + "note": "Definition approved after complete current-contract audit and successful repository-specific native verification; no hosted or closing result is claimed." + }, + { + "gate": "definition", + "actor": "user:0xLeif", + "timestamp": 1784027489, + "digest": "59fdaf85b9142cdf08598887c401ad2c0d06b06f1eab95d9c4c378cddb623589", + "note": "Fresh definition approval after adding exact native evidence mapping for REQ-sql-001 through REQ-sql-011." + }, + { + "gate": "acceptance", + "actor": "user:0xLeif", + "timestamp": 1784027518, + "digest": "a66525519d8705526254f204226b557d8467d2bc09d736b2f066ed450a551a70", + "note": "Closing approval recorded after strict SpecSync validation, complete REQ-sql-001..REQ-sql-011 evidence, and successful four-step native verification; hosted CI is not claimed." + } + ] } diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/change.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/change.md index 8cf4b4e..ec5c052 100644 --- a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/change.md +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/change.md @@ -1,6 +1,6 @@ --- id: CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin -state: draft +state: accepted type: migration base_commit: a4e307b1607bb9b2cad4d62488d634643552526e --- @@ -17,9 +17,11 @@ Adopt SpecSync 5.0.1 and Trust 1.0.0 governance for the SQLite Fledge plugin ## Acceptance Criteria -- SpecSync strict checks pass at explicit advisory threshold 0 for the extensionless Bash executable; existing requirements have deterministic IDs; all four integrations are installed; Trust doctor and verification pass; syntax -- 26 database safety tests -- and manifest validation remain green. +- The active specification accurately covers every existing command, option, safety guard, result form, dependency, and error boundary without changing runtime behavior. +- REQ-sql-001 through REQ-sql-011 are deterministic and the repository-specific SDD policy covers every implementation, test, documentation, workflow, and governance surface. +- SpecSync strict forced validation passes at the explicit advisory threshold for the extensionless Bash executable, with all four agent integrations installed. +- The Fledge lane passes governance validation, Bash syntax, all 26 hermetic database cases, and manifest validation; Trust doctor and verification also pass. +- Exact-head hosted checks pass, the branch remains conflict-free, and no unresolved review thread remains before promotion. ## No-spec Rationale diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/context.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/context.md index 595105b..d44c8a8 100644 --- a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/context.md +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/context.md @@ -5,4 +5,9 @@ artifact: context # Context -The SQLite plugin manages project-local initialization, transactional migrations, guarded ad-hoc queries, and schema inspection through fledge-v1. The rollout adopts its active contract without weakening persistence or destructive-query safety. +The extensionless Bash plugin manages project-local initialization, transactional +migrations, guarded queries, parameter binding, result formatting, schema +inspection, and version/help output through fledge-v1. The original rollout +captured only the four headline database commands and used generic SDD paths. +This migration completes the current contract and repository-specific policy +without changing the executable, existing CI, or Pages publication. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/deltas/sql.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/deltas/sql.md new file mode 100644 index 0000000..925390c --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/deltas/sql.md @@ -0,0 +1,76 @@ +## MODIFIED + +### SPEC SECTION Purpose +SQLite database management for Fledge projects, including project-local initialization, transactional migrations, guarded queries, parameter binding, result formatting, schema inspection, and version/help output through fledge-v1 host capabilities. + +### REQUIREMENT REQ-sql-001 +`fledge sql init` SHALL create the selected project database and store its path through the host protocol. + +Acceptance Criteria +- The hermetic init case verifies database creation and the host-observed success output. + +### REQUIREMENT REQ-sql-002 +`fledge sql migrate` SHALL apply unapplied SQL files in filename order, transactionally, and record them idempotently. + +Acceptance Criteria +- Migration apply, repeat, failure, rollback-state, and tracking-row cases all pass. + +### REQUIREMENT REQ-sql-003 +`fledge sql query` SHALL use a selected or stored database and support column, list, CSV, and JSON output, including the documented empty-result forms. + +Acceptance Criteria +- The native query cases exercise formatted and JSON results against temporary databases. + +### REQUIREMENT REQ-sql-004 +Query parameters SHALL validate their names and bind arbitrary values as data without allowing quotes, semicolons, or SQL-looking values to become SQL syntax. + +Acceptance Criteria +- Simple, quoted, double-quoted, injection-shaped, malformed, and invalid-name parameter cases pass. + +### REQUIREMENT REQ-sql-005 +User-supplied multi-statement queries SHALL be rejected, while one trailing semicolon SHALL be accepted. + +Acceptance Criteria +- The multi-statement rejection and trailing-semicolon acceptance cases pass. + +### REQUIREMENT REQ-sql-006 +`DROP`, `ALTER`, and `TRUNCATE` SHALL be rejected unless the caller explicitly passes `--allow-destructive`. + +Acceptance Criteria +- All three guarded keywords and the explicit override are verified by the native suite. + +### REQUIREMENT REQ-sql-007 +`INSERT`, `UPDATE`, and `DELETE` SHALL return a successful JSON object containing the row count reported by `changes()` in the same SQLite session. + +Acceptance Criteria +- Insert, update, delete, and explicit change-count cases pass. + +### REQUIREMENT REQ-sql-008 +`fledge sql schema` SHALL show tables, indexes, and views with SQL definitions in text or JSON form, using a selected or stored database. + +Acceptance Criteria +- The schema case verifies the temporary database table in JSON output. + +### REQUIREMENT REQ-sql-009 +Missing initialization, invalid parameter syntax or names, failed migrations, and SQLite query/schema errors SHALL produce clear diagnostics and non-zero exits; missing or empty migration directories SHALL remain successful no-ops. + +Acceptance Criteria +- The hermetic failure and no-op cases assert the documented diagnostics and exit boundaries. + +### REQUIREMENT REQ-sql-010 +Help SHALL expose every supported command and guarded-query flag, version SHALL read the manifest version, and unknown commands SHALL fail with guidance. + +Acceptance Criteria +- Version and help cases verify the manifest version and both guarded-query flags. + +### REQUIREMENT REQ-sql-011 +All host execution, persistence, prompts, diagnostics, and user output SHALL use the fledge-v1 protocol. + +Acceptance Criteria +- The full harness mediates every case as a fledge-v1 host and fails on malformed protocol traffic. + +### SPEC SECTION Change Log +| Version | Date | Changes | +|---------|------|---------| +| 1 | 2026-05-06 | Initial spec | +| 2 | 2026-07-14 | Document the existing guarded-query, parameter, output-format, schema, version, and help behavior for SpecSync 5.0.1 adoption; runtime behavior is unchanged. | diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/design.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/design.md index 4a4b554..5f1a5cc 100644 --- a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/design.md +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/design.md @@ -5,6 +5,15 @@ artifact: design # Design -Assign deterministic IDs to the active requirements, stamp SpecSync 5.0.1, and install all integrations. +Keep the executable untouched. Expand the active canonical spec and deterministic +requirements to the complete observed contract, stamp SpecSync 5.0.1, and keep +Claude, Cursor, Codex, and Gemini integrations installed. -Trust runs Bash syntax, all 26 database safety tests, and manifest validation through Fledge. Risk blocks, provenance is progressive, coverage is advisory 0 with rationale, and Atlas stays disabled because Pages remains independent. The workflow pins Trust 1.0.0 immutably. +The SDD policy names only this repository's implementation, test, docs, manifest, +Fledge, workflow, tool-policy, lifecycle, and agent surfaces. A deterministic +governance test prevents generic paths or incomplete requirement IDs from returning. + +Trust runs governance validation, Bash syntax, all 26 database safety tests, and +manifest validation through Fledge. Risk blocks, provenance is progressive, +coverage is advisory 0 with the unsupported-file rationale, and Atlas stays +disabled because Pages remains independent. The workflow pins Trust 1.0.0 immutably. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/docs.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/docs.md index 62aaee6..5cceac8 100644 --- a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/docs.md +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/docs.md @@ -5,4 +5,7 @@ artifact: docs # Docs -The managed `AGENTS.md` block documents the unified verification path. Existing public database behavior and safety guidance remains unchanged. +The active spec and requirement companion now document all existing guarded-query, +parameter, output, schema, diagnostic, version, and help behavior. The managed +`AGENTS.md` block documents the unified verification path. Public README and Pages +content, runtime behavior, and existing workflows remain unchanged by this migration. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/plan.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/plan.md index 17fafd3..28a53ca 100644 --- a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/plan.md +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/plan.md @@ -5,8 +5,10 @@ artifact: plan # Plan -1. Preserve the active initialization, migration, query, and schema contract. -2. Assign stable requirements and adopt SpecSync 5.0.1 at threshold 0. -3. Install all integrations and add the complete native database lane. -4. Add standard Trust policy and immutable workflow. -5. Validate locally and preserve existing test and Pages workflows. +1. Audit the executable and 26-case harness without changing runtime behavior. +2. Complete the active contract and assign stable IDs to every observed behavior. +3. Replace generic SDD paths with exact repository surfaces and stamp SpecSync 5.0.1. +4. Keep all integrations and add deterministic governance validation to the native lane. +5. Retain the standard Trust policy, immutable action pin, existing CI, and independent Pages publication. +6. Use supported definition, verification, and closing lifecycle commands only after native validation. +7. Require exact-head hosted green checks, no conflicts, and no unresolved threads before promotion. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/research.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/research.md index 9d32a24..0330499 100644 --- a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/research.md +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/research.md @@ -7,4 +7,13 @@ artifact: research The hermetic Python harness covers 26 initialization, migration ordering/idempotence/rollback, parameter binding and injection, destructive-operation blocking and override, DML counts, schema, version, and help cases. -SpecSync does not measure the extensionless Bash executable, so coverage is explicitly advisory 0 and the native syntax/database suite is blocking. ShellCheck's pre-existing informational jq-quoting findings are not enforced by current CI and remain isolated. +The implementation audit found eleven stable contract areas: initialization, +migrations, query formats, bound parameters, multi-statement rejection, +destructive-DDL approval, DML change counts, schema formats, diagnostics, help +and version, and fledge-v1 host mediation. The canonical spec and requirements +now describe those existing behaviors rather than only the headline commands. + +SpecSync 5.0.1 reports 0/0 measurable files and LOC for the governed extensionless +Bash executable. Coverage therefore remains explicitly advisory rather than +misrepresenting 0/0 as 100%; full semantic mapping, syntax, 26 hermetic cases, +manifest validation, and a repository-specific governance check are blocking. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json index b0e15eb..ce368c8 100644 --- a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/state.json @@ -5,10 +5,10 @@ "title": "Adopt SpecSync 5.0.1 and Trust 1.0.0 governance for the SQLite Fledge plugin", "description": "Adopt SpecSync 5.0.1 and Trust 1.0.0 governance for the SQLite Fledge plugin", "kind": "migration", - "state": "draft", + "state": "accepted", "base_commit": "a4e307b1607bb9b2cad4d62488d634643552526e", "created_at": 1783883062, - "updated_at": 1783883069, + "updated_at": 1784027518, "affected_specs": [ "sql" ], @@ -20,12 +20,22 @@ ".github/", ".specsync/", "specs/", - ".trust.toml" + ".trust.toml", + ".augur.toml", + ".attest.json", + ".claude/", + ".cursor/", + ".codex/", + ".gemini/" ], "no_spec_change": false, "no_spec_change_rationale": null, "acceptance_criteria": [ - "SpecSync strict checks pass at explicit advisory threshold 0 for the extensionless Bash executable; existing requirements have deterministic IDs; all four integrations are installed; Trust doctor and verification pass; syntax, 26 database safety tests, and manifest validation remain green." + "The active specification accurately covers every existing command, option, safety guard, result form, dependency, and error boundary without changing runtime behavior.", + "REQ-sql-001 through REQ-sql-011 are deterministic and the repository-specific SDD policy covers every implementation, test, documentation, workflow, and governance surface.", + "SpecSync strict forced validation passes at the explicit advisory threshold for the extensionless Bash executable, with all four agent integrations installed.", + "The Fledge lane passes governance validation, Bash syntax, all 26 hermetic database cases, and manifest validation; Trust doctor and verification also pass.", + "Exact-head hosted checks pass, the branch remains conflict-free, and no unresolved review thread remains before promotion." ], "selected_artifacts": [ "context", diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/tasks.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/tasks.md index b6d86c4..34d98fd 100644 --- a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/tasks.md +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/tasks.md @@ -5,11 +5,14 @@ artifact: tasks # Tasks -- [x] Preserve the active SQLite specification and assign deterministic IDs. -- [x] Adopt and stamp SpecSync 5.0.1 with threshold-0 rationale. +- [x] Audit the current executable and hermetic harness without modifying product behavior. +- [x] Complete the active SQLite specification and assign REQ-sql-001 through REQ-sql-011. +- [x] Adopt and stamp SpecSync 5.0.1 with the truthful extensionless-file threshold rationale. - [x] Install all four integrations. -- [x] Add the three-step database safety lane and Trust policy. +- [x] Replace generic SDD paths with repository-specific meaningful surfaces. +- [x] Add deterministic governance validation to the existing database safety lane. +- [x] Configure the standard Trust policy without changing existing CI or Pages workflows. - [x] Add the immutable Trust 1.0.0 workflow. -- [x] Validate syntax, 26 tests, manifest, integrations, and Trust. -- [ ] Record definition approval and execute the verified lifecycle. -- [ ] Confirm hosted checks and preserve branch requirements. +- [x] Prepare complete portable lifecycle artifacts for supported approval and verification commands. + +Closing approval and hosted CI success are intentionally not claimed as preparation tasks. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/testing.md b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/testing.md index b07a71d..423c1c7 100644 --- a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/testing.md +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/testing.md @@ -5,6 +5,28 @@ artifact: testing # Testing -Local acceptance requires Bash syntax, all 26 database safety cases, manifest validation, strict SpecSync checks at threshold 0, four integrations, healthy Trust doctor, and a clean diff. +Local acceptance requires the repository-specific governance check, Bash syntax, +all 26 hermetic database cases, manifest validation, strict forced SpecSync checks +at the explicit extensionless-file threshold, all four integrations, healthy +Trust doctor, full Trust verification, and a clean diff. -Hosted acceptance requires the new `trust` job and existing integration-test job to pass on Ubuntu while Pages remains independent. +The native suite covers every REQ-sql contract area without a live service or +network dependency. Lifecycle evidence must be produced by supported SpecSync +commands after this lane passes, not by pre-completing approval or hosted-CI tasks. + +Requirement evidence maps to the passing native cases as follows: + +- `REQ-sql-001`: initialization creates the temporary database through the host. +- `REQ-sql-002`: migration apply, idempotence, failure rollback, and tracking-row cases. +- `REQ-sql-003`: query output and JSON-result cases against temporary databases. +- `REQ-sql-004`: simple, quoted, double-quoted, injection-shaped, malformed, and invalid-name parameters. +- `REQ-sql-005`: multi-statement rejection and trailing-semicolon acceptance. +- `REQ-sql-006`: DROP, ALTER, TRUNCATE, and explicit destructive override cases. +- `REQ-sql-007`: insert, update, delete, and same-session change-count cases. +- `REQ-sql-008`: schema JSON includes the expected temporary table definition. +- `REQ-sql-009`: migration, parameter, and guarded-query error/no-op boundaries. +- `REQ-sql-010`: manifest-backed version and complete guarded-query help cases. +- `REQ-sql-011`: the harness mediates all 26 cases as a fledge-v1 host. + +Hosted acceptance requires the exact-head `trust`, existing integration tests, +and other applicable checks to pass on Ubuntu while Pages remains independent. diff --git a/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/verification.json b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/verification.json new file mode 100644 index 0000000..32cd5a8 --- /dev/null +++ b/.specsync/changes/CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin/verification.json @@ -0,0 +1,28 @@ +{ + "timestamp": 1784027512, + "commit": "6a58ec1709b19cd796e908177dd06979e115d5f7", + "contract_digest": "59fdaf85b9142cdf08598887c401ad2c0d06b06f1eab95d9c4c378cddb623589", + "workspace_digest": "bf6874112cf66803014806f01b6ed382a8fcb343e9b47a1e2e573d3985923c8c", + "acceptance_input_digest": "f709c7318c56aaf544a810a6360522bdb121551491b81f63bc39b8fe60e477ba", + "passed": true, + "commands": [ + { + "command": "fledge lanes run verify", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-sql-001", + "REQ-sql-002", + "REQ-sql-003", + "REQ-sql-004", + "REQ-sql-005", + "REQ-sql-006", + "REQ-sql-007", + "REQ-sql-008", + "REQ-sql-009", + "REQ-sql-010", + "REQ-sql-011" + ] +} diff --git a/.specsync/sdd.json b/.specsync/sdd.json index 8b970b6..c92e604 100644 --- a/.specsync/sdd.json +++ b/.specsync/sdd.json @@ -3,37 +3,29 @@ "enabled": true, "require_change_for_meaningful_files": true, "meaningful_paths": [ - "src/", - "tests/", - "site/", + "bin/", + "test/", + "docs/", + "plugin.toml", + "fledge.toml", + ".trust.toml", + ".augur.toml", + ".attest.json", ".github/", - "Cargo.toml", - "Cargo.lock", - "action.yml", - "package.json", - "bun.lock", - "package-lock.json", - "pnpm-lock.yaml", - "yarn.lock", - "Package.swift", - "Package.resolved", - "go.mod", - "go.sum", - "pyproject.toml", - "uv.lock", - "requirements.txt", ".specsync/sdd.json", ".specsync/config.toml", - ".specsync/config.json", ".specsync/version", - "bin/" + ".claude/", + ".cursor/", + ".codex/", + ".gemini/" ], "ignored_paths": [ ".specsync/", "specs/" ], "verification_commands": [ - "bash -n bin/fledge-sql && python3 test/test.py" + "fledge lanes run verify" ], "custom_artifacts": {}, "principles_file": null diff --git a/.trust.toml b/.trust.toml index 9f026c7..9cae97d 100644 --- a/.trust.toml +++ b/.trust.toml @@ -7,7 +7,7 @@ command = ["fledge", "lanes", "run", "verify"] [contract] enabled = true require_coverage = 0 -skip_reason = "SpecSync does not measure the extensionless Bash executable; syntax and 26 database safety tests are blocking" +skip_reason = "SpecSync 5.0.1 reports 0/0 measurable files for the governed extensionless Bash executable; its complete contract is mapped in the active spec and the syntax plus 26-case hermetic database suite are blocking" [risk] threshold = "block" diff --git a/fledge.toml b/fledge.toml index 8a95aab..5ae452e 100644 --- a/fledge.toml +++ b/fledge.toml @@ -3,7 +3,8 @@ syntax = "bash -n bin/fledge-sql" test = "python3 test/test.py" manifest = "grep -q 'binary = \"bin/fledge-sql\"' plugin.toml && grep -q 'protocol = \"fledge-v1\"' plugin.toml" +governance = "python3 test/governance.py" [lanes.verify] -description = "Syntax-check and test the guarded SQLite plugin" -steps = ["syntax", "test", "manifest"] +description = "Validate governance, syntax, the guarded SQLite behavior, and the plugin manifest" +steps = ["governance", "syntax", "test", "manifest"] diff --git a/specs/sql/requirements.md b/specs/sql/requirements.md index 2bd4c05..55a7248 100644 --- a/specs/sql/requirements.md +++ b/specs/sql/requirements.md @@ -13,27 +13,84 @@ spec: sql.spec.md ### REQ-sql-001 -`fledge sql init` creates the selected project database and stores its path through the host protocol. +`fledge sql init` SHALL create the selected project database and store its path through the host protocol. + +Acceptance Criteria +- The hermetic init case verifies database creation and the host-observed success output. ### REQ-sql-002 -`fledge sql migrate` applies unapplied SQL files in filename order, transactionally, and records them idempotently. +`fledge sql migrate` SHALL apply unapplied SQL files in filename order, transactionally, and record them idempotently. + +Acceptance Criteria +- Migration apply, repeat, failure, rollback-state, and tracking-row cases all pass. ### REQ-sql-003 -`fledge sql query` executes SQL against the initialized database and returns formatted results. +`fledge sql query` SHALL use a selected or stored database and support column, list, CSV, and JSON output, including the documented empty-result forms. + +Acceptance Criteria +- The native query cases exercise formatted and JSON results against temporary databases. ### REQ-sql-004 -`fledge sql schema` shows user tables, indexes, and views for the initialized database. +Query parameters SHALL validate their names and bind arbitrary values as data without allowing quotes, semicolons, or SQL-looking values to become SQL syntax. + +Acceptance Criteria +- Simple, quoted, double-quoted, injection-shaped, malformed, and invalid-name parameter cases pass. ### REQ-sql-005 -All commands use the fledge-v1 protocol for input, output, persistence, and host execution. +User-supplied multi-statement queries SHALL be rejected, while one trailing semicolon SHALL be accepted. + +Acceptance Criteria +- The multi-statement rejection and trailing-semicolon acceptance cases pass. + +### REQ-sql-006 + +`DROP`, `ALTER`, and `TRUNCATE` SHALL be rejected unless the caller explicitly passes `--allow-destructive`. + +Acceptance Criteria +- All three guarded keywords and the explicit override are verified by the native suite. + +### REQ-sql-007 + +`INSERT`, `UPDATE`, and `DELETE` SHALL return a successful JSON object containing the row count reported by `changes()` in the same SQLite session. + +Acceptance Criteria +- Insert, update, delete, and explicit change-count cases pass. + +### REQ-sql-008 + +`fledge sql schema` SHALL show tables, indexes, and views with SQL definitions in text or JSON form, using a selected or stored database. + +Acceptance Criteria +- The schema case verifies the temporary database table in JSON output. + +### REQ-sql-009 + +Missing initialization, invalid parameter syntax or names, failed migrations, and SQLite query/schema errors SHALL produce clear diagnostics and non-zero exits; missing or empty migration directories SHALL remain successful no-ops. + +Acceptance Criteria +- The hermetic failure and no-op cases assert the documented diagnostics and exit boundaries. + +### REQ-sql-010 + +Help SHALL expose every supported command and guarded-query flag, version SHALL read the manifest version, and unknown commands SHALL fail with guidance. + +Acceptance Criteria +- Version and help cases verify the manifest version and both guarded-query flags. + +### REQ-sql-011 + +All host execution, persistence, prompts, diagnostics, and user output SHALL use the fledge-v1 protocol. + +Acceptance Criteria +- The full harness mediates every case as a fledge-v1 host and fails on malformed protocol traffic. ## Constraints -- Must work without any dependencies beyond sqlite3 +- Runtime dependencies are Bash, `jq`, `sqlite3`, and a fledge-v1 host - Shell script implementation (no compile step) ## Out of Scope diff --git a/specs/sql/sql.spec.md b/specs/sql/sql.spec.md index 554af66..94cce02 100644 --- a/specs/sql/sql.spec.md +++ b/specs/sql/sql.spec.md @@ -1,6 +1,6 @@ --- module: sql -version: 1 +version: 3 status: active files: - bin/fledge-sql @@ -13,7 +13,7 @@ depends_on: [] ## Purpose -SQLite database management for fledge projects. Provides project-local database initialization, migration tracking, ad-hoc queries, and schema inspection. Wraps the `sqlite3` CLI via the fledge-v1 protocol's `exec` capability. +SQLite database management for Fledge projects, including project-local initialization, transactional migrations, guarded queries, parameter binding, result formatting, schema inspection, and version/help output through fledge-v1 host capabilities. ## Public API @@ -21,10 +21,22 @@ SQLite database management for fledge projects. Provides project-local database | Command | Args | Description | |---------|------|-------------| -| `init` | `[--path ]` | Create a SQLite database. Default: `.fledge/data.db`. Stores path via `store`. | -| `migrate` | `[--dir ]` | Run `*.sql` files from `migrations/` in filename order. Tracks in `_migrations` table. | -| `query` | `` | Execute SQL, display results as formatted table. | -| `schema` | | Dump schema via `sqlite_master`. | +| `init` | `[--path ]` | Prompt with `.fledge/data.db` when no path is supplied, create parent directories and the database if absent, and store the absolute path. Existing databases are retained and stored. | +| `migrate` | `[--dir ]` | Run previously unapplied `*.sql` files from `migrations/` (or the selected directory) in filename order and track them in `_migrations`. A missing/empty directory is a successful no-op. | +| `query` | `[--path ] [--json\|--csv\|--list] [--allow-destructive] [--param name=value]... ` | Execute one SQL statement against the selected or stored database. Default output is header/column format; empty JSON results are `[]`, while other empty results are `(no results)`. | +| `schema` | `[--path ] [--json]` | Return tables, indexes, and views with non-null SQL from `sqlite_master`, ordered by name. | +| `version` | `--version`, `-V` | Read the plugin version from `plugin.toml`. | +| `help` | `--help`, `-h` | Print command and guarded-query usage. Unknown commands report an error and exit non-zero. | + +### Query safety and results + +- More than one user-supplied statement is rejected; one trailing semicolon is accepted. +- `DROP`, `ALTER`, and `TRUNCATE` are rejected unless `--allow-destructive` is present. +- Parameter names accept an optional `@` or `:` prefix and otherwise must match + `[A-Za-z_][A-Za-z0-9_]*`. Values are encoded as hexadecimal SQLite parameters, + so quotes and SQL-looking content remain values. +- `INSERT`, `UPDATE`, and `DELETE` return `{"ok":true,"changes":N}` using + `changes()` from the same SQLite session. ### Protocol Messages Used @@ -40,14 +52,17 @@ SQLite database management for fledge projects. Provides project-local database ## Invariants -1. The plugin never creates a database without user confirmation (either `--path` flag or interactive prompt). +1. The plugin never creates a database without a supplied path or a completed host prompt. 2. Migrations are idempotent — re-running `migrate` skips already-applied files. 3. The `_migrations` table is created automatically on first `migrate` run. 4. Migration files are sorted by filename (lexicographic) and applied in order. 5. Each migration runs inside a transaction — if it fails, none of that file's changes persist. 6. The stored DB path is project-scoped via the fledge-v1 `store` capability. 7. `query` and `schema` fail with a clear error if no database has been initialized. -8. All `sqlite3` invocations go through the fledge-v1 `exec` message, never direct shell execution. +8. All `sqlite3` invocations go through the fledge-v1 `exec` message, never direct host execution. +9. User-supplied multi-statement queries and unapproved destructive DDL are rejected before host execution. +10. Bound parameter names are validated and their values cannot become SQL syntax. +11. DML change counts come from the same SQLite session as the modifying statement. ## Behavioral Examples @@ -83,9 +98,12 @@ $ fledge sql schema |-------|------|----------| | `sqlite3 not found` | `sqlite3` not on PATH | Log error, exit 1 | | `No database initialized` | `query`/`schema`/`migrate` before `init` | Log error with hint to run `fledge sql init` | -| `Migration failed` | SQL error in a migration file | Roll back that file's transaction, log error with filename and line, exit 1 | -| `Database already exists` | `init` when DB file exists | Log warning, skip creation | -| `No migrations directory` | `migrate` when `migrations/` doesn't exist | Log info, exit 0 | +| `Migration failed` | SQL error in a migration file | Roll back that file's transaction, report the filename and SQLite diagnostic, and exit non-zero. | +| `Database already exists` | `init` when DB file exists | Retain the file, store its path, and report that it already exists. | +| `No migrations directory` | `migrate` when the selected directory does not exist | Report the missing directory and exit successfully. | +| `Unsafe query` | The user supplies multiple statements or guarded destructive DDL without the override | Reject before sending an execution request. | +| `Invalid parameter` | `--param` lacks `name=value` or uses an invalid name | Report the invalid binding and exit non-zero. | +| `Query or schema failure` | SQLite returns a non-zero status | Surface the SQLite diagnostic and exit non-zero. | ## Dependencies @@ -97,3 +115,5 @@ $ fledge sql schema | Version | Date | Changes | |---------|------|---------| | 1 | 2026-05-06 | Initial spec | +| 2 | 2026-07-14 | Document the existing guarded-query, parameter, output-format, schema, version, and help behavior for SpecSync 5.0.1 adoption; runtime behavior is unchanged. | +| 2026-07-14 | CHG-0001-adopt-specsync-5-0-1-and-trust-1-0-0-governance-for-the-sqlite-fledge-plugin: Adopt SpecSync 5.0.1 and Trust 1.0.0 governance for the SQLite Fledge plugin | diff --git a/specs/sql/tasks.md b/specs/sql/tasks.md index d3bf599..c0cf310 100644 --- a/specs/sql/tasks.md +++ b/specs/sql/tasks.md @@ -10,3 +10,5 @@ spec: sql.spec.md - [x] Implement migrate subcommand - [x] Implement query subcommand - [x] Implement schema subcommand +- [x] Preserve and document the existing guarded-query, parameter-binding, output-format, version, and help behavior for SpecSync 5.0.1 adoption +- [x] Assign deterministic IDs to the complete current contract without changing runtime behavior diff --git a/specs/sql/testing.md b/specs/sql/testing.md index 11f5823..6bcacfa 100644 --- a/specs/sql/testing.md +++ b/specs/sql/testing.md @@ -4,12 +4,16 @@ spec: sql.spec.md ## Test Plan -### Integration Tests - -- Pipe fledge-v1 init message to the plugin binary, verify JSON output -- Test `init` creates a database file -- Test `migrate` applies .sql files and records them -- Test `migrate` is idempotent -- Test `query` returns formatted results -- Test `schema` returns table definitions -- Test error cases: missing sqlite3, no DB initialized, bad SQL +### Hermetic integration suite + +`python3 test/test.py` acts as the fledge-v1 host and executes 26 cases against +temporary SQLite databases. It covers initialization, ordered and idempotent +migrations, transactional rollback, every query format, safe parameter binding, +SQL-injection-shaped values, destructive-operation and multi-statement guards, +DML change counts, schema JSON, version, help, and invalid parameter input. + +### Verification lane + +`fledge lanes run verify` runs the deterministic governance check, Bash syntax, +the 26-case database suite, and manifest validation. No external database, +network service, or persistent project data is used. diff --git a/test/governance.py b/test/governance.py new file mode 100644 index 0000000..bc063aa --- /dev/null +++ b/test/governance.py @@ -0,0 +1,56 @@ +#!/usr/bin/env python3 +"""Validate repository-specific SpecSync policy and complete SQL requirements.""" + +import json +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +EXPECTED_MEANINGFUL_PATHS = [ + "bin/", + "test/", + "docs/", + "plugin.toml", + "fledge.toml", + ".trust.toml", + ".augur.toml", + ".attest.json", + ".github/", + ".specsync/sdd.json", + ".specsync/config.toml", + ".specsync/version", + ".claude/", + ".cursor/", + ".codex/", + ".gemini/", +] +REQUIREMENT_IDS = [f"REQ-sql-{number:03d}" for number in range(1, 12)] +SPEC_BEHAVIORS = [ + "--allow-destructive", + "--param name=value", + "multi-statement", + "changes()", + "version", + "Unknown commands", +] + + +def main() -> None: + """Fail when the rollout policy or canonical contract becomes incomplete.""" + policy = json.loads((ROOT / ".specsync/sdd.json").read_text(encoding="utf-8")) + assert policy["meaningful_paths"] == EXPECTED_MEANINGFUL_PATHS + assert policy["verification_commands"] == ["fledge lanes run verify"] + + requirements = (ROOT / "specs/sql/requirements.md").read_text(encoding="utf-8") + for requirement_id in REQUIREMENT_IDS: + assert requirements.count(requirement_id) == 1, f"missing or duplicate {requirement_id}" + + canonical_spec = (ROOT / "specs/sql/sql.spec.md").read_text(encoding="utf-8").lower() + for behavior in SPEC_BEHAVIORS: + assert behavior.lower() in canonical_spec, f"canonical spec omits {behavior}" + + print("governance policy and REQ-sql-001..REQ-sql-011 validated") + + +if __name__ == "__main__": + main()