Phase 1 — Widgets: the @gadhs/pi distribution

On this page

Summary

Phase 1 delivers the "one package to rule them all": @gadhs/pi, bundling our custom extensions with pinned upstream ones, so onboarding is a single pi install. Phase 2 (guidance injections — the model-agnostic replacement for vendor context files) depends on the seam shipped here but not on its content: the pipe ships as a no-op with test hooks proving injected instructions land verbatim in the composed system prompt.

Operator constraints in force: the agent runs in yolo mode until auto mode (modes + permission system) is operational; no cross-project interfacing (including the upstream claude-quickstart macro-feedback issue, which is drafted but held) until then.

Design

See Architecture. Non-negotiables: upstream security code is never patched; all model calls go through pi’s composed provider; the judge is advisory-only on ask decisions.

Work items

  1. Bootstrap scaffold — monorepo, toolchain, hooks, Antora, standards copy, GitLab templates, ADR-001/002, this plan.
    Status: Done (2026-08-26) — commit 3bbe437; tracking issues #1–#11 created

  2. @gadhs/pi-vertex-anthropic to standards — rename/rescope, thin README stub + Antora page, unit tests for option mapping & config loading, contract test with a fake Vertex client.
    Status: Done (2026-08-26) — MR !6 merged; 28 tests + guarded live smoke

  3. @gadhs/pi-modes core — config loader (bundled default + user override), mode registry, mode switching (pi.setModel/setThinkingLevel), per-mode system-prompt addendum + tool filter, /mode commands + cycle shortcut, state persistence.
    Status: Done (2026-08-26) — MR !1 merged (2a7cc7c / 5ca0e39)

  4. Guidance-injection seam — global + per-mode guidance blocks composed into the system prompt; no-op default; test hooks (canary block asserted byte-for-byte in the composed prompt); precedence order documented.
    Status: Done (2026-08-26) — MR !2 merged (fe97d06 / 2a53be4); live canaries verified

  5. Model-judge authorizer — registerAuthorizer("gadhs-mode-judge", …) on permissions:ready; composed-provider model call; fail-closed verdict parser (property-tested); per-mode judge policy (default deny-only); disposer lifecycle.
    Status: Done (2026-08-26) — commit 647ed1e (direct-to-main; process violation self-reported in #4, guard added)

  6. Permission-system bootstrap — seed a conservative default config.json + authorizerChain for @gotgenes/pi-permission-system when absent; document the default policy.
    Status: Done (2026-08-26) — MR !4 merged; live first-run verified

  7. @gadhs/pi meta assembly — pin + bundle upstreams, verify each bundled entrypoint loads from node_modules paths, defaults/prompts dirs, publish dry-run against the GitLab registry.
    Status: Done (2026-08-26) — MR !5 merged; consumer-simulation verified; publish dry-runs green

  8. Auto-mode dogfood gate — run this repo’s own development under modes
    permission enforcement (exit yolo). Acceptance: judge adjudicates ask decisions with a Vertex model; deterministic denies hold; operator signs off.
    Status: Done (2026-08-31) — #9 closed with operator sign-off. The repo develops itself under its own stack; friction became fixes and eval cases (routine allowlist, /tmp whitelist, settings-read split, ask/plan tools, sticky model); gates green (521 tests, corpus 119/122 x3 zero unsafe, consumer-sim 10/10, publish dry-runs)

  9. CI pipeline — GitLab CI running task validate (+ signature check) on org runners; publish job for the registry.
    Status: Done (2026-08-26) — MR !7 merged. Pipeline-green + test-publish rehearsal DEFERRED: DHS runner fleet capacity outage (operator directive: local task validate is the merge gate until the fleet recovers; see #8)

Post-plan increments (same phase, operator-directed)

  • TUI: Orchard themes, status line, inline adjudication/subagent traces.
    Status: Done (2026-08-29) — #25 closed; live-verified

  • Typed subagent results (output_schema contracts, one validator).
    Status: Done (2026-08-29) — #20 closed; false-positive regression pinned

  • Session continuity: model/thinking restore, ADC rotation + auth retry.
    Status: Done (2026-08-29) — #26/#27 closed; live-verified

  • Workflow guards at the tool_call seam (deterministic; #29).
    Status: Done (2026-08-29) — commit/authoring/GitLab/setup guards, all live-verified

  • Guidance payload: packaged digests + language profiles + /gadhs-init (#28).
    Status: Done (2026-08-29) — canary-verified injection

  • Governed auto-memory + /remember, /memory.
    Status: Done (2026-08-30) — #30 closed

  • count tool: exact match counts, because models miscount by eye.
    Status: Done (2026-08-30) — validated over four gibberish fixtures; chosen unprompted every trial

  • Scratch-space allowance: /tmp, /var/tmp, /var/folders writable in auto/manual, read-only in plan.
    Status: Done (2026-08-30) — credential patterns still outrank by specificity

  • yield: structured subagent results, all-issues-at-once schema feedback, in-child retries, sidecar collection for large/background payloads.
    Status: Done (2026-08-30) — live-verified (agent=Explore phase=yielded)

  • Human-legible status line and traces (no counters, no shouting).
    Status: Done (2026-08-30) — per-mode icon + colour; amber reserved for attention states

  • Agent-callable plan mode: enter_plan_mode / exit_plan_mode, three outcomes, plan rendered before the approval dialog.
    Status: Done (2026-08-30) — fail-closed path live-verified; the unrendered plan was found by the operator using it, not by tests

  • ask: put a question to the human mid-task, every mode, free-text escape always offered.
    Status: Done (2026-08-30) — verified interactively and headless

  • Reflection pause sunset of PRECOMMIT_TOKEN: one review per commit, keyed by the staged diff, in every repo.
    Status: Done (2026-08-30) — live-verified 2 commits / 2 pauses

  • Workflow guards apply in every mode, yolo included (opt-out removed).
    Status: Done (2026-08-30) — yolo had silently dropped the pause, attribution, SPDX-at-write and the debt gate

  • Cold-reader reflection review: an independent model, never weaker than the author, reviews the staged diff against J1-J8.
    Status: Done (2026-08-30) — caught 4 planted defects with file:line, incl. a comment asserting a guarantee the diff did not establish

Deferred

  • @gotgenes/pi-subagents-worktrees — REJECTED for v2 (2026-08-29, #10): worktree children load none of our permission stack; --no-verify rescue path. Revisit only with a writing subagent + both upstream fixes.

  • Upstream language-profile macro-feedback issue — drafted, held until the auto-mode dogfood gate passes (operator instruction).

Exit criteria

pi install npm:@gadhs/pi on a clean machine yields: Vertex Claude models (per-model regions) available after /login + env, modes switchable with per-mode models, permission enforcement active with the judge advising on ask, web access and subagents loaded — and this repo’s own development runs under that stack (dogfood gate passed).

Edit this page · latest