llm-wb 0.1.0-beta.0

package/.agentic/00.chat/README.md

@@ -0,0 +1,78 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: governance
+  disciplines:
+  - agentic
+  kind: layer-readme
+  purpose: Explain the chat lifecycle governance layer and its canonical surfaces.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: repo.agents
+    path: AGENTS.md
+  - id: chat.migration-plan
+    path: .agentic/00.chat/migration-plan.md
+-->
+# 00.chat Layer
+
+## Purpose
+
+Own chat lifecycle governance for this harness.
+
+This layer covers chat creation, session metadata, chat-owned worktrees,
+session logs, commit checkpoints, main-refresh coordination, closeout,
+cleanup, shortcuts, and on-demand chat reports.
+
+<!-- deterministic-check: allow reason="prompt routing may be manual or repo-specific; no universal script can decide whether a context router exists" -->
+This layer does not assign a whole chat one durable layer, mode, or workflow.
+Prompt interpretation uses the current request, repo assistant instructions,
+and any repo-provided context router if one exists. When a router returns a
+context packet, the chat layer may record the latest packet ID and summary for
+continuity, but chat lifecycle metadata remains about branch, worktree, session
+log, metrics, transcript, and git state.
+
+## Source Of Truth
+
+- Active chat state: current branch session log under `commitLogs/`
+- Chat lifecycle workflows: `.agentic/00.chat/workflows/`
+- Chat lifecycle checklists: `.agentic/00.chat/checklists/`
+- Chat lifecycle skills: `.agentic/00.chat/skills/`
+- Chat lifecycle standards: `.agentic/00.chat/standards/`
+- Chat command shortcuts: `.agentic/00.chat/commands/`
+- Chat lifecycle migration plan: `.agentic/00.chat/migration-plan.md`
+- Public chat commands: `package.json` `chat:*` scripts
+- Shared harness governance helpers: `scripts/01.harness/`
+
+## Migration Policy
+
+Move chat-specific instructions here. Retired compatibility paths should stay
+retired unless an active session recovery explicitly requires a governed
+restore.
+
+Use `npm run chat:*` package scripts for public chat-layer command entrypoints.
+The package scripts delegate to canonical capability scripts under
+`scripts/00.chat/`.
+
+Do not add new chat lifecycle scripts under `scripts/shared/git/` or
+`scripts/shared/chat/`. Those locations were retired as compatibility surfaces;
+new chat-owned behavior belongs under `scripts/00.chat/<domain>/<capability>/`.
+
+Use `bash scripts/00.chat/migration/audit-chat-layer-migration/script.sh` to inspect the
+current migration state before moving more chat lifecycle behavior.
+
+Use `bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/session-log/record-main-refresh-conflict/script.sh`
+to append the required session-log audit trail for governed main-refresh
+conflict recovery.
+
+## Reporting Policy
+
+Do not maintain an always-generated aggregate `commitLogs/README.md`.
+
+Generate chat/session summaries only on request, using the on-demand reporting
+skill or script. Individual session logs remain the durable source evidence.

package/.agentic/00.chat/checklists/before-commit.md

@@ -0,0 +1,195 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.checklists.before-commit
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: git
+  disciplines:
+  - agentic
+  kind: checklist
+  purpose: Define the required checks before committing approved chat task work.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.workflows.chat-commit
+    path: .agentic/00.chat/workflows/chat-commit.md
+-->
+# Chat Before-Commit Checklist
+
+Use this before committing approved chat task work.
+
+## Write Location
+
+Run from the chat-owned worktree:
+
+```bash
+bash scripts/00.chat/worktree/check-write-location/script.sh
+```
+
+Task commits must not be prepared from the root integration worktree.
+Preserve unrelated user changes in a dirty worktree.
+
+## Branch Prerequisites
+
+Run:
+
+```bash
+bash scripts/00.chat/session-log/check-commit-prerequisites/script.sh
+```
+
+<!-- deterministic-check: allow reason="requires human approval before merge or cherry-pick repair" -->
+If this reports missing workflow, checklist, or gate files, pause the task
+commit. Ask for approval before merging or cherry-picking the commit that
+introduced the missing files, then rerun this checklist.
+
+## Deterministic Process Drift
+
+Run:
+
+```bash
+bash scripts/01.harness/check-deterministic-process-drift.sh --staged
+```
+
+<!-- deterministic-check: allow reason="requires human review and approval before editing process prose" -->
+If this flags staged process prose, propose moving the deterministic part into a
+script or gate, or keeping the prose with an allow marker and reason.
+
+## Artifact Metadata
+
+Run:
+
+```bash
+bash scripts/01.harness/artifact-metadata/check-headers/script.sh --staged-added
+```
+
+New scripts and harness/process Markdown documents must declare metadata
+headers before entering the repo. Existing files are backfilled in focused
+batches.
+
+## Optional Commit Gates
+
+If this repo defines an optional layer-level commit gate, run that gate
+according to the repo's local instructions. The base llm-workbench install does
+not require any product, deployment, retrieval, or rulebook layer.
+
+## llm-workbench Public-Beta Contract
+
+If the change touches public export, install/uninstall, chat startup, assistant
+adapters, transcript metrics, cost metrics, public templates, or portability
+validation, complete:
+
+```bash
+.agentic/00.chat/checklists/llm-workbench-public-beta.md
+```
+
+## Commit Log Deletions
+
+Run:
+
+```bash
+bash scripts/00.chat/session-log/check-commitlog-deletions/script.sh
+```
+
+Empty, unsaved session logs may be deleted by intentional cleanup. Do not delete
+commit logs that record commits or are explicitly marked for retention.
+
+## Session Log
+
+- Initial intent is present.
+- Questions asked during the chat are summarized, or explicitly recorded as none.
+- Issues raised during the chat are summarized with their resolutions, or
+  explicitly recorded as none.
+- Decisions made during the chat are summarized, or explicitly recorded as none.
+- Commit summary is recorded before or immediately after each commit.
+
+For structured manual session-log entries, use:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/session-log/update-chat-log/script.sh <entry-type> <summary> <detail>
+```
+
+## ADR Disposition
+
+- If the chat made a durable harness architecture decision, create or update an
+  ADR under `docs/harness/architecture/adrs/`.
+- If no ADR is needed, record a short reason in the session log.
+
+## Gate
+
+Run:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/session-log/prepare-chat-session-before-commit/script.sh
+```
+
+Do not commit if the gate fails.
+
+## After Commit
+
+Run:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/session-log/record-chat-commit/script.sh <sha> <message> <summary> [adr-impact]
+```
+
+Record every commit in the chat. The latest recorded commit is treated as the
+current endpoint for chat duration and session metrics.
+
+The recorder should estimate chat-token metrics from `CHAT_TRANSCRIPT_BYTES`,
+neutral transcript metadata, or an explicit assistant adapter such as Codex
+JSONL discovery. Never substitute the session log file size. If no transcript
+source can be supplied or discovered, portable mode records token metrics as
+unavailable. Strict mode may still stop before recording the commit when exact
+metrics are required.
+
+The recorder may estimate chat cost from the estimated chat-token metric and the
+checked-in pricing snapshot. Treat `estimated_chat_cost` as an approximate
+planning metric, not a billing record, because transcript-derived token counts
+do not split input, cached input, and output tokens.
+
+<!-- deterministic-check: allow reason="checkpoint helper enforces narrow file scope; prose states the human-readable policy" -->
+If `record-chat-commit.sh` leaves only session bookkeeping dirty, prior explicit
+write permission for the chat authorizes the bookkeeping checkpoint commit:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/session-log/checkpoint-chat-session-log/script.sh
+```
+
+<!-- deterministic-check: allow reason="checkpoint helper enforces file scope; prose states the human-readable policy" -->
+This commit must contain only the current chat session log and no other paths.
+Stop and ask if any other path is staged, unstaged, or would be committed.
+
+## Approval
+
+Do not create a task commit without explicit user approval in the current chat.
+The only commit allowed by prior write permission alone is the narrow session
+bookkeeping checkpoint described above.
+
+The chat-owned worktree is reusable and intentionally left in place after each
+chat. Cleanup requires explicit user approval or a deterministic cleanup script
+that preserves logs with recorded work or retention markers.
+
+After explicit approval to stage task paths, stage only approved
+repository-relative paths in the chat-owned worktree:
+
+```bash
+git add -- <path>...
+```
+
+If approved work was accidentally edited outside the chat-owned worktree, treat
+that as recovery. Import only explicit approved paths into the chat-owned
+worktree before continuing:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action \
+  scripts/00.chat/recovery/import-active-paths-to-chat-worktree/script.sh \
+  --session-log <session-log> \
+  --source-worktree <active-worktree> \
+  -- <path>...
+```
+
+Chat-owned worktree execution does not authorize pushes, merges, rebases, branch
+deletion, history rewrite, discarding work, or destructive actions.

package/.agentic/00.chat/checklists/llm-workbench-public-beta.md

@@ -0,0 +1,94 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.checklists.llm-workbench-public-beta
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: portability
+  disciplines:
+  - agentic
+  kind: checklist
+  purpose: Check llm-workbench public-beta portability before committing related work.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.standards.llm-workbench-public-beta-contract
+    path: .agentic/00.chat/standards/llm-workbench-public-beta-contract.md
+  - id: chat.checklists.before-commit
+    path: .agentic/00.chat/checklists/before-commit.md
+-->
+# llm-workbench Public-Beta Checklist
+
+Use this before committing changes that touch public export, install/uninstall,
+chat startup, assistant adapters, transcript metrics, cost metrics, public
+templates, or portability validation.
+
+## Contract
+
+Read `.agentic/00.chat/standards/llm-workbench-public-beta-contract.md`.
+
+Confirm the change preserves:
+
+- no durable whole-chat `layer`, `mode`, or `workflow` classification
+- standalone public export with self-consistent metadata
+- no mandatory RAG/rulebook or Codex behavior in generic chat surfaces
+- provider-neutral transcript and cost defaults
+- safe blank and existing repo install/uninstall behavior
+- thin assistant adapters
+- CLI/code-assistant robustness, including JSON startup and executable-bit loss
+
+## Temporary Eval
+
+- A temporary eval or failing smoke case was written before the patch.
+- The eval failed before the implementation.
+- The implementation made the eval pass.
+- Durable edge cases were promoted into the permanent portability suite.
+- Temporary eval files were removed before closeout.
+
+## Required Validation
+
+Run:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/upstream/validate-llm-workbench-portability/script.sh
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/upstream/bootstrap-llm-workbench-repo/smoke-test.sh
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/startup/start-chat-session/smoke-test.sh
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/session-log/record-chat-commit/smoke-test.sh
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/command/package-scripts/smoke-test.sh
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/command/dispatcher/smoke-test.sh
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/01.harness/artifact-metadata/check-headers/smoke-test.sh
+bash scripts/01.harness/artifact-metadata/check-headers/script.sh --all
+bash scripts/01.harness/check-governed-script-command-drift.sh
+```
+
+Also run:
+
+```bash
+bash scripts/01.harness/check-deterministic-process-drift.sh --paths <changed-governed-files>
+bash -n <changed-shell-scripts-and-templates>
+git diff --check
+```
+
+## Public Export Review
+
+When export/install behavior changed:
+
+- materialize the generated public workbench
+- inspect the generated public top-level tree
+- verify source-only trees are absent
+- install into a blank repo
+- install into an existing repo
+- run `check-headers --all` in the generated public repo
+- run `check-headers --all` in an installed target
+
+## Closeout
+
+Report:
+
+- changed files summary
+- exact validation commands run
+- skipped checks and why
+- whether temporary eval files remain
+- whether changes are committed or still uncommitted

package/.agentic/00.chat/commands/README.md

@@ -0,0 +1,108 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.commands.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: command
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain the terminal chat command shortcut surface.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.command.dispatcher.readme
+    path: scripts/00.chat/command/dispatcher/README.md
+  - id: chat.script.command.dispatcher
+    path: scripts/00.chat/command/dispatcher/script.sh
+-->
+# Chat Commands
+
+## Purpose
+
+Chat commands are small named shortcuts for governed chat lifecycle actions.
+They make repeated actions easy to trigger without moving process rules into
+`AGENTS.md`.
+
+## Public CLI Entry Point
+
+The public user-facing CLI is:
+
+```bash
+llm-wb <command> [args...]
+```
+
+Use `npx llm-wb ...` when the package is not installed globally or linked into
+the current shell.
+
+Current public CLI shortcuts include:
+
+- `init` - installs the workbench into the current or specified Git repo.
+- `new <prompt>` - starts a new chat session from an explicit prompt.
+- `list` - lists installed workbench command names.
+- `sessions list` - lists active chat sessions and branches.
+- `commit -m <message>` - runs commit gates, commits task work, records the
+  commit, and checkpoints session evidence.
+- `merge-main` - verifies readiness and merges the chat branch into local
+  `main` without pushing.
+
+## Dispatcher Entry Point
+
+The canonical dispatcher is:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/command/dispatcher/script.sh <command> [args...]
+```
+
+Its capability README is:
+
+```txt
+scripts/00.chat/command/dispatcher/README.md
+```
+
+## Commands
+
+- `new <prompt>` - starts a new chat session from an explicit prompt.
+- `open window [worktree-path|session-log]` - opens a new VS Code window for the
+  current or specified chat-owned worktree.
+- `close` - prints or copies a governed prompt for committing approved work, if
+  needed, then promoting the chat branch into local `main`.
+
+## Chat Message Auto-Start
+
+When a chat starts in this repo and no matching chat session exists for the
+current branch, the chat-start workflow treats the opening user message as the
+new chat summary and runs the resolver:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/startup/resolve-current-chat-session/script.sh "<opening user message>"
+```
+
+If the opening message is exactly `new`, the agent asks what the chat should be
+about before creating a session.
+
+## Adding A Command
+
+Add a new executable script at:
+
+```txt
+scripts/00.chat/command/<name>/script.sh
+```
+
+Use lowercase command names when possible. Keep the command script narrow:
+
+- delegate to existing governed scripts when the action is deterministic
+- print or copy a prompt when the action needs agent judgment or user approval
+- preserve existing approval boundaries for commits, merges, pushes, branch
+  deletion, destructive actions, and history rewriting
+
+Update the dispatcher smoke test named in its capability README when adding a
+command that should remain part of the stable shortcut surface.
+
+The old `scripts/shared/chat/commands/<name>.sh` compatibility path has been
+retired. Do not add new commands there; add canonical
+`scripts/00.chat/command/<name>/script.sh` entrypoints and package-script
+shortcuts instead.

package/.agentic/00.chat/migration-plan.md

@@ -0,0 +1,132 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.migration-plan
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: migration
+  disciplines:
+  - agentic
+  kind: migration-plan
+  purpose: Track migration from legacy chat lifecycle paths to canonical 00.chat paths.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.migration.audit-chat-layer-migration
+    path: scripts/00.chat/migration/audit-chat-layer-migration/script.sh
+  - id: harness.architecture.adr.0017-organize-scripts-by-owner-domain-and-capability
+-->
+# 00.chat Migration Plan
+
+## Purpose
+
+Guide future chats as chat lifecycle governance finishes moving from
+compatibility paths into `.agentic/00.chat/`.
+
+The goal is controlled migration, not a big-bang rename. Legacy paths may stay
+in historical references, but operative chat lifecycle governance belongs in
+`.agentic/00.chat/`.
+
+## Current Canonical Surfaces
+
+- Layer overview: `.agentic/00.chat/README.md`
+- Workflow index: `.agentic/00.chat/workflows/README.md`
+- Before-commit checklist: `.agentic/00.chat/checklists/before-commit.md`
+- Main refresh conflict type standard:
+  `.agentic/00.chat/standards/main-refresh-conflict-types.md`
+- Reporting skill: `.agentic/00.chat/skills/session-summary.md`
+- Public chat commands: `package.json` `chat:*` scripts
+
+## Migrated Workflow Ownership
+
+- Chat startup: `.agentic/00.chat/workflows/chat-start.md`
+- Chat task commits: `.agentic/00.chat/workflows/chat-commit.md`
+- Refresh from main: `.agentic/00.chat/workflows/chat-refresh-from-main.md`
+- Promote to main: `.agentic/00.chat/workflows/chat-promote-to-main.md`
+- Cleanup: `.agentic/00.chat/workflows/chat-cleanup.md`
+- Reporting: `.agentic/00.chat/workflows/chat-reporting.md`
+
+## Retired Compatibility Paths
+
+These old shared paths are retired. Historical references may mention them, but
+operative instructions, audits, and package scripts should point to the
+canonical chat layer:
+
+- `.agentic/shared/workflows/chat-start-interview.md`
+- `.agentic/shared/workflows/main-updated.md`
+- `.agentic/shared/workflows/local-convergence.md`
+- `.agentic/shared/checklists/before-commit.md`
+- `.agentic/shared/workflows/default.md`
+
+Script compatibility wrappers under `scripts/shared/chat/` and
+`scripts/shared/git/` have been retired. Keep historical references for audit
+context, but operative instructions and package scripts should point to
+canonical `scripts/00.chat/...` capability paths.
+
+## Migration Rules
+
+- Move ownership prose before moving executable paths.
+- Keep retired workflow/checklist paths absent unless an active session recovery
+  explicitly requires a governed restore.
+- Preserve exact blocked responses when changing workflow ownership.
+- Keep scripts deterministic; do not replace scriptable gates with prose.
+- Maintain focused smoke tests for startup, classification, refresh, commit,
+  reporting, and cleanup behavior before moving scripts.
+- Do not migrate destructive cleanup commands without dry-run and explicit
+  approval gates.
+- Do not reintroduce tracked aggregate `commitLogs/README.md`.
+
+## Completed Migration Queue
+
+1. Added canonical chat lifecycle workflows under `.agentic/00.chat/workflows/`.
+2. Added chat-layer command, cleanup, reporting, and conflict-recording package
+   scripts in `package.json`.
+3. Migrated chat lifecycle implementation paths to canonical
+   `scripts/00.chat/...` capabilities and retired old `scripts/shared/chat/`
+   and `scripts/shared/git/` wrappers.
+4. Added audit coverage for the chat-layer package script surface.
+5. Kept focused smoke tests for startup, classification, refresh, commit,
+   reporting, cleanup, commands, and package scripts.
+6. Audited active session metadata and retired redundant shared chat lifecycle
+   pointers, duplicate before-commit compatibility checklist, and placeholder
+   default workflows.
+7. Added governed cleanup for temporary preflight branches and worktrees when a
+   rehearsed main refresh is applied. The apply helper removes the promoted
+   preflight branch/worktree, removes clean stale sibling preflights that are
+   already ancestors of the promoted chat branch, and reports unsafe stale
+   preflights without deleting them.
+8. Narrowed `.agentic/shared/workflows/change-shared-process.md` so it keeps
+   shared-process ownership and chat harness entry gates, while delegating
+   chat lifecycle commit recording, transcript metrics, bookkeeping checkpoint,
+   and commit-log deletion rules to `.agentic/00.chat/checklists/before-commit.md`.
+9. Added a deterministic main-refresh conflict classifier based on the conflict
+   type standard and the first recorded main-refresh recovery evidence.
+10. Added a preflight conflict audit verification gate that compares conflict
+    paths with `## Main Refresh Conflicts` entries before applying a resolved
+    preflight refresh.
+
+## Deferred Migration Queue
+
+No deferred migration items remain. Future conflict types or verification
+expansions should be added only when new main-refresh recovery evidence exposes
+a gap in the current standard or scripts.
+
+Do not treat deferred items as permission to improvise. Complete them only when
+their stated evidence, policy, or workflow precondition exists.
+
+## Audit
+
+Run:
+
+```bash
+bash scripts/00.chat/migration/audit-chat-layer-migration/script.sh
+```
+
+The audit reports required canonical files, retired compatibility paths that
+should stay absent, and remaining retired compatibility references in
+source/process files. It also inventories policy references to the retired
+aggregate summary so future chats can tell intentional "do not recreate this"
+guidance apart from generated-artifact regression. It does not treat historical
+session logs as migration blockers.

package/.agentic/00.chat/skills/session-summary.md

@@ -0,0 +1,48 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.skills.session-summary
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: chat
+  disciplines:
+  - agentic
+  kind: guide
+  purpose: Document Session Summary Skill.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+    - entity-builder
+    - design-system-builder
+  used_by:
+  - id: repo.agents
+    path: AGENTS.md
+-->
+# Session Summary Skill
+
+## Use When
+
+Use when the user asks for a commit log summary, chat metrics, session metrics,
+or a report across `commitLogs/`.
+
+## Instructions
+
+Generate summaries on demand. Do not create or update `commitLogs/README.md`.
+
+Use:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/reporting/generate-commit-log-summary/script.sh
+```
+
+The script prints the current aggregate summary to stdout.
+
+If the user asks for a file artifact, write to an explicitly requested path
+outside `commitLogs/README.md`, for example:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/reporting/generate-commit-log-summary/script.sh --output /tmp/chat-summary.md
+```
+
+Individual session logs under `commitLogs/` are the source evidence.