paqad-ai 1.2.1 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # paqad-ai
 
+## 1.4.0
+
+### Minor Changes
+
+- [#75](https://github.com/Eliyce/paqad-ai/pull/75) [`283d973`](https://github.com/Eliyce/paqad-ai/commit/283d9736621e7571013a377408a8ec6416b54df9) Thanks [@HLasani](https://github.com/HLasani)! - Gate every agent turn on the entry-file load, not just code-mutating tool
+  calls. Onboarded projects previously could answer read-only prompts (Q&A,
+  "what is this project", explanations) without loading `CLAUDE.md`,
+  `.paqad/framework-path.txt`, or `docs/instructions/{rules,stack,design-system}`
+  — the framework's rules and Decision Pause Contract silently never entered
+  context.
+
+  The Claude Code adapter now installs a `UserPromptSubmit` hook
+  (`runtime/hooks/agent-entry-prompt-gate.sh`) alongside the existing
+  `PreToolUse` hook. Both gates share sentinel-freshness logic via
+  `runtime/hooks/lib/agent-entry-sentinel.sh` so they cannot drift.
+
+  Soft mode (default): the hook prints a high-priority reminder on stdout; Claude
+  Code injects it into the model context before the turn is planned. Hard mode
+  (`PAQAD_AGENT_ENTRY_MODE=hard`): the hook exits non-zero and blocks the turn
+  until the sentinel is written.
+
+  Re-running onboarding / `paqad upgrade` refreshes the wiring in
+  `.claude/settings.json` idempotently. Resolves Eliyce/paqad-ai#74.
+
+## 1.3.0
+
+### Minor Changes
+
+- [#67](https://github.com/Eliyce/paqad-ai/pull/67) [`c4312aa`](https://github.com/Eliyce/paqad-ai/commit/c4312aab1366c6c25138e6de38cff935c862ccb1) Thanks [@HLasani](https://github.com/HLasani)! - Add `paqad-ai dashboard` and `paqad-ai status` — the living single-pane health overview for an onboarded paqad project.
+
+  `paqad-ai dashboard` starts a local web server (port 5372, auto-incrementing) on the same bundle as `paqad-ai graph`. The graph view is now one section inside the dashboard, opened via the architecture card; the existing `paqad-ai graph` command is unchanged and is still a direct shortcut to the graph route. Sections rendered in Phase 1: project profile, rules, workflows, decisions (living), module health (living), module docs, architecture, design system, stack, registries, tools, tech-debt, stack drift, framework version, RAG status, and — when present — pentest and session continuity. Each card shows a score badge, a one-line state-derived summary, a `?` helper popover, and up to three compact metrics. Score is existence + freshness only (file present + last-modified ≤ 30d = 100%, decays linearly to 0 at the 180d cliff); no content-quality heuristics in Phase 1. The summary band surfaces up to five "Needs your attention" items, critical-first. The card border pulses (200ms accent) when SSE re-fetch updates a section — the one allowed animation.
+
+  `paqad-ai status` is the same `buildReport()` pipeline, but one-shot — no server, no long-running process. Defaults to a deterministic Markdown rendering for humans / PR descriptions; `--format json` emits the stable `schemaVersion: 1` contract for agent prompts.
+
+  Zero install footprint: the bundle ships inside the package (mirroring the existing `runtime/graph-ui/` pattern), no new files are written into the user's project, scoring is computed on the fly, and no new MCP server or background process is introduced. Reuses every `--color-mod-*` design token already present in `graph-ui/src/index.css` — no new design tokens.
+
+  Closes [#64](https://github.com/Eliyce/paqad-ai/issues/64).
+
+### Patch Changes
+
+- [#71](https://github.com/Eliyce/paqad-ai/pull/71) [`c530fa3`](https://github.com/Eliyce/paqad-ai/commit/c530fa34d032f7f454f49386bc66987e32cb726a) Thanks [@HLasani](https://github.com/HLasani)! - Stop leaking absolute install paths into committed onboarding artifacts ([#69](https://github.com/Eliyce/paqad-ai/issues/69)). The hooks manifest (`.claude/settings.hooks.json`, `.codex/hooks.json`, `.gemini/hooks.json`, etc.) now stores only the package-relative `source` and resolves the hook script at runtime, instead of baking in `/opt/homebrew/lib/node_modules/paqad-ai/...` or `~/.npm/_npx/<hash>/...` from the onboarding user's machine. A teammate cloning the repo (different OS user, different package manager, Mac vs. Windows) can now run Paqad without every hook 404'ing, and usernames/machine layout no longer end up in source control. Adds a portability test that scans all generated config across every adapter × fixture combination for leaked absolute paths.
+
 ## 1.2.1
 
 ### Patch Changes

package/README.md

@@ -512,6 +512,39 @@ paqad-ai graph --no-watch               # Disable live reload on .paqad/ changes
 
 **Pre-conditions:** the current directory must contain a `.paqad/` from a previous `paqad-ai onboard`. RAG is optional — without it the graph still renders fully, with similarity and chunk nodes disabled behind a clear banner.
 
+### `paqad-ai dashboard`
+
+The single-pane "where am I on this project?" view. Same bundle as `paqad-ai graph` — the graph view is now one section inside the dashboard, opened by the architecture card.
+
+```bash
+paqad-ai dashboard                       # Opens http://127.0.0.1:5372/#/dashboard
+paqad-ai dashboard --no-open             # Print the URL and skip auto-open
+paqad-ai dashboard --port 8080           # Custom port (auto-increments if busy)
+paqad-ai dashboard --no-watch            # Disable live reload on .paqad/ changes
+```
+
+**What you get:**
+
+- Overall completeness score (existence + freshness, no content-quality heuristics)
+- A card per section: project profile, rules, workflows, decisions (living), module health (living), module docs, architecture, design system / stack / registries / tools / tech-debt, stack drift, framework version, RAG status, and — when present — pentest and session continuity
+- Per-card score badge using the same `mod-green` / `mod-amber` / `mod-red` / `mod-unknown` tokens as the graph view
+- Helper text behind a `?` affordance on every card (what this means + what good looks like)
+- Summary band with up to five "Needs your attention" items, ordered critical-first
+- Live reload — same SSE pattern as the graph view, the card border pulses when its section changes
+- `paqad-ai graph` and `paqad-ai dashboard` share the bundle; switching between routes is a hash-router nav
+
+### `paqad-ai status`
+
+One-shot LLM-friendly snapshot of the same report — no server, no long-running process. Use this from an agent prompt.
+
+```bash
+paqad-ai status                          # Markdown (default) to stdout
+paqad-ai status --format json            # Full DashboardReport contract
+paqad-ai status --project-root <path>    # Snapshot a different project
+```
+
+The JSON shape is stable (`schemaVersion: 1`) and identical to the payload served by `GET /api/dashboard` on the dashboard server.
+
 ### Security workflows
 
 Security and retest flows are part of the framework runtime and agent workflows in this package version. They are not exposed as standalone top-level CLI commands in `paqad-ai` today.
@@ -598,22 +631,24 @@ Entry files stay thin. Knowledge lives in shared instruction bundles that extern
 
 ## Workflow overview
 
-| Workflow             | How to trigger                         | What happens                                              |
-| -------------------- | -------------------------------------- | --------------------------------------------------------- |
-| **Onboarding**       | `paqad-ai onboard`                     | Detect stack → confirm → generate everything              |
-| **Health check**     | `paqad-ai doctor`                      | Validate artifacts, config, docs                          |
-| **Spec compliance**  | `paqad-ai compliance ...`              | Extract obligations, check evidence, generate skeletons   |
-| **Refresh**          | `paqad-ai refresh`                     | Re-detect stack, update derived docs                      |
-| **Update**           | `paqad-ai update`                      | Regenerate framework files after version bump             |
-| **RAG**              | `paqad-ai rag ...`                     | Build, inspect, clear, and benchmark hybrid retrieval     |
-| **Project graph**    | `paqad-ai graph`                       | Interactive browser view of modules, files, chunks, deps  |
-| **Documentation**    | Ask agent: _"create documentation"_    | Stack → architecture → design system → modules            |
-| **Pentest**          | Ask agent: _"run pentest"_             | 5-step scan → findings → report                           |
-| **Retest**           | Ask agent: _"retest pentest"_          | Replay findings → fixed / still-open / needs-verification |
-| **Capabilities**     | `paqad-ai capabilities add/remove`     | Toggle content / coding / security                        |
-| **Pack management**  | `paqad-ai packs install/remove`        | Install, validate, scaffold stack packs                   |
-| **Pattern library**  | `paqad-ai patterns ...`                | Query, prune, and export reusable solutions               |
-| **Custom workflows** | YAML at `docs/instructions/workflows/` | Your own resumable skill sequences                        |
+| Workflow              | How to trigger                         | What happens                                              |
+| --------------------- | -------------------------------------- | --------------------------------------------------------- |
+| **Onboarding**        | `paqad-ai onboard`                     | Detect stack → confirm → generate everything              |
+| **Health check**      | `paqad-ai doctor`                      | Validate artifacts, config, docs                          |
+| **Spec compliance**   | `paqad-ai compliance ...`              | Extract obligations, check evidence, generate skeletons   |
+| **Refresh**           | `paqad-ai refresh`                     | Re-detect stack, update derived docs                      |
+| **Update**            | `paqad-ai update`                      | Regenerate framework files after version bump             |
+| **RAG**               | `paqad-ai rag ...`                     | Build, inspect, clear, and benchmark hybrid retrieval     |
+| **Project graph**     | `paqad-ai graph`                       | Interactive browser view of modules, files, chunks, deps  |
+| **Project dashboard** | `paqad-ai dashboard`                   | Living single-pane health overview, per-section scoring   |
+| **Project status**    | `paqad-ai status [--format json]`      | One-shot LLM-friendly snapshot of the dashboard           |
+| **Documentation**     | Ask agent: _"create documentation"_    | Stack → architecture → design system → modules            |
+| **Pentest**           | Ask agent: _"run pentest"_             | 5-step scan → findings → report                           |
+| **Retest**            | Ask agent: _"retest pentest"_          | Replay findings → fixed / still-open / needs-verification |
+| **Capabilities**      | `paqad-ai capabilities add/remove`     | Toggle content / coding / security                        |
+| **Pack management**   | `paqad-ai packs install/remove`        | Install, validate, scaffold stack packs                   |
+| **Pattern library**   | `paqad-ai patterns ...`                | Query, prune, and export reusable solutions               |
+| **Custom workflows**  | YAML at `docs/instructions/workflows/` | Your own resumable skill sequences                        |
 
 ---