From dee39116a171c81704ed7af1cbc25f4b79f2995a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kim=20Harjam=C3=A4ki?= Date: Wed, 8 Jul 2026 15:13:32 +0300 Subject: [PATCH 1/2] docs(36-01): append freshness footer to README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index b8869fb..b5e3408 100644 --- a/README.md +++ b/README.md @@ -111,3 +111,5 @@ Non-loopback model endpoints are rejected unless `allowNonLoopback` is explicitl ## License MIT - see [LICENSE](LICENSE) + + From ce1b1484ddc358555bf494e029b4f925d50d642c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kim=20Harjam=C3=A4ki?= Date: Wed, 8 Jul 2026 15:20:37 +0300 Subject: [PATCH 2/2] docs(36-03): add docs/wiki tree (Home, Architecture, Operations, Decisions) - Architecture.md documents the governance/blackboard flow (AgenticBlackboard) - Operations.md verified install/build/test/release-gate/CI commands - Decisions.md indexes phase history, ADR convention, and open PRs --- docs/wiki/Architecture.md | 53 +++++++++++++++++++++++++++++++ docs/wiki/Decisions.md | 27 ++++++++++++++++ docs/wiki/Home.md | 32 +++++++++++++++++++ docs/wiki/Operations.md | 65 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 177 insertions(+) create mode 100644 docs/wiki/Architecture.md create mode 100644 docs/wiki/Decisions.md create mode 100644 docs/wiki/Home.md create mode 100644 docs/wiki/Operations.md diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md new file mode 100644 index 0000000..cabdd53 --- /dev/null +++ b/docs/wiki/Architecture.md @@ -0,0 +1,53 @@ +# Architecture + +## Governance / blackboard flow + +`universal-refiner` (the active MCP server) intercepts a raw prompt from an AI CLI, runs it +through context and refinement, and — via `AgenticBlackboard` (`src/core/blackboard.ts`) — +publishes and reads shared state so concurrent agent sessions can coordinate rather than act +on disjoint local knowledge. + +```mermaid +flowchart LR + CLI["AI CLI\n(Claude / Cursor / Gemini)"] -->|"stdio"| PI["PromptImprover\n(universal-refiner)"] + subgraph Engine["Governance & Refinement Engine"] + Scout["Context Scout\nlanguage/framework detectors"] + RAG["RAG Snippets\nFlexSearch retrieval"] + Memory[("SQLite Memory\nLocalBrain")] + Semantic["Local Semantic Model\ngemma3:12b / 1b"] + end + subgraph BB["AgenticBlackboard (blackboard.json)"] + Intents["Active agent intents\n(agentName, toolType, expiresAt)"] + Logs["System logs\n(per-project)"] + LastRefine["Last refinement record\n(gain metric)"] + end + PI --> Scout --> RAG --> Memory --> Semantic --> PI + PI -->|"publish intent"| BB + BB -->|"read concurrent intents"| PI + PI --> Out["Augmented Prompt"] + Out -.->|"event store"| Memory +``` + + + +## Component breakdown + +- **Context Scout** — startup detectors identify language, framework, and architectural + signals so refinement is tailored to the current codebase (`src/detectors/project-scout.ts`). +- **RAG Snippets** — FlexSearch-based retrieval over the local codebase injects relevant + examples into the refined prompt. +- **AgenticBlackboard** — a JSON-file-backed shared store (`.refiner/blackboard.json`, + project-scoped, with a global fallback under `~/.refiner`) recording active agent intents + (`agentName`, `toolType`, `intent`, `expiresAt`), system logs, and the last refinement's + gain metric. A serialized write queue (`writeQueue`) and listener registry prevent + concurrent-write corruption when multiple CLI sessions touch the same project. +- **LocalBrain (SQLite)** — persistent storage for reusable refinement rules, learned + patterns, and prompt history. +- **Local Semantic Model** — an optional OpenAI-compatible local endpoint (`gemma3:12b`, + falling back to `gemma3:1b`) that produces the final refined prompt; rule-based refinement + continues if neither the local model nor MCP sampling is available. +- **Governance gate** — generated lessons and templates remain pending until reviewed through + the MCP learning-review tools (see the root README's Local Semantic Model section) — the + blackboard records the intent and history that gate reviews against. + + diff --git a/docs/wiki/Decisions.md b/docs/wiki/Decisions.md new file mode 100644 index 0000000..14d9c5c --- /dev/null +++ b/docs/wiki/Decisions.md @@ -0,0 +1,27 @@ +# Decisions + +## ADR convention + +`docs/adr/README.md` establishes the convention (sequential numbering, Context/Decision/ +Consequences) but **no numbered ADR files exist in the repo yet**. Decisions to date live in +`.planning/phases/` and the `docs/` architecture specs instead. + +## Phase history (`.planning/phases/`, this repo's own GSD project) + +| Phase | Topic | +|---|---| +| 01 | FS watcher | + +See [`docs/promptimprover-autogen-architecture-spec.md`](../promptimprover-autogen-architecture-spec.md), +[`docs/enterprise-release-gates.md`](../enterprise-release-gates.md), and +[`docs/operator-testing.md`](../operator-testing.md) for the broader design record beyond the +single formal phase. + +## Open decisions tracked in this Phase 36 refresh + +- **PR #27** (`fix/dashboard-loopback-xss`) — bind dashboard to loopback and escape HTML in + trace rendering; open, not yet merged. +- **PR #28** (`ci/sha-pin-and-least-privilege`) — pins third-party GitHub Actions to commit + SHAs and least-privilege permissions; open, not yet merged. + + diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..8c8c4a6 --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,32 @@ +# PromptImprover Wiki + +## Role in the CAS portfolio + +`Promptimprover` is part of the **Governance plane** of the Coding-Autopilot-System +three-plane model (Control / Execution / Governance). It is an MCP-first prompt governance +layer: it sits between an AI CLI and execution tools, adds repo-aware context, applies +refinement rules, and — via its `AgenticBlackboard` — coordinates intent and history across +concurrent agent sessions rather than treating each prompt as disposable chat. + +| Plane | This repo's responsibility | +|---|---| +| Control | *(not this repo — see `gsd-orchestrator`)* | +| Execution | *(not this repo — see `autogen`)* | +| Governance | Prompt refinement, cross-agent blackboard coordination, learning-review workflow | + +## Quickstart + +- [README.md](../../README.md) — Quickstart, Local Semantic Model, Proof Points +- [Architecture](./Architecture.md) — governance/blackboard flow +- [Operations](./Operations.md) — verified install/build/test/release-gate commands +- [Decisions](./Decisions.md) — phase history and ADR convention + +## Ecosystem links + +Part of the [Coding-Autopilot-System](https://github.com/Coding-Autopilot-System) org: +[gsd-orchestrator](https://github.com/Coding-Autopilot-System/gsd-orchestrator) (control plane) · +[autogen](https://github.com/Coding-Autopilot-System/autogen) (execution plane) · +[cas-contracts](https://github.com/Coding-Autopilot-System/cas-contracts) (shared schemas) · +[cas-evals](https://github.com/Coding-Autopilot-System/cas-evals) (evidence gate) + + diff --git a/docs/wiki/Operations.md b/docs/wiki/Operations.md new file mode 100644 index 0000000..e7c2f58 --- /dev/null +++ b/docs/wiki/Operations.md @@ -0,0 +1,65 @@ +# Operations + +## Setup + +```powershell +git clone https://github.com/Coding-Autopilot-System/Promptimprover.git +cd Promptimprover +.\build_and_install.ps1 +``` + +Linux/macOS: + +```sh +git clone https://github.com/Coding-Autopilot-System/Promptimprover.git +cd Promptimprover +./build_and_install.sh +``` + +Both installers run a deterministic dependency install, run the full test suite, build the +package, install it globally, and verify the `universal-refiner` command. + +## Build and test (`universal-refiner/`) + +```bash +npm ci +npm run build +npm run test:coverage +``` + +## Full local release gate + +```powershell +cd C:\PersonalRepo\portfolio\Promptimprover\universal-refiner +npm.cmd run release:verify +``` + +`release:verify` chains build, coverage tests, acceptance suites (MCP, semantic fallback, +tracked-turn, stdio-MCP), e2e (Playwright), stress/recovery/soak checks, security audit +(production + full) and secret scanning, package dry-run, and packaged runtime startup smoke — +per `universal-refiner/package.json`. + +## CI (`.github/workflows/ci.yml`, `ubuntu-latest`, working directory `universal-refiner/`) + +**`build-and-test`** job (15-minute timeout): +1. `actions/checkout@v7` +2. `actions/setup-node@v6` (Node 22) +3. `npm ci --no-fund` +4. `npm rebuild better-sqlite3` (native module rebuild) +5. `npm run build` +6. `npm run test:coverage` + +**`acceptance`** job (15-minute timeout, matrix `model-order: [primary, reversed]`): +1. Same checkout/setup/install/rebuild/build steps as above +2. Acceptance suite run against each model-order permutation + +A separate `.github/workflows/codeql.yml` runs CodeQL analysis (badge in the root `README.md`). + +## Global MCP registration doctor + +```powershell +powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\register-global.ps1 -Check +powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\register-global.ps1 -Apply +``` + +