llm-wb 0.1.0-beta.0

package/.agentic/shared/standards/upstream-repo-bootstrap.md

@@ -0,0 +1,131 @@
+<!-- agentic-artifact:
+schema: agentic-artifact/v2
+id: shared.standards.upstream-repo-bootstrap
+version: 1
+status: active
+layer: 06.shared
+domain: bootstrap
+disciplines:
+- agentic
+kind: standard
+purpose: Define the Upstream Repo Bootstrap Standard standard.
+portability:
+  class: required
+  targets:
+  - llm-workbench
+  - entity-builder
+  - design-system-builder
+used_by:
+- id: repo.agents
+  path: AGENTS.md
+-->
+
+# Upstream Repo Bootstrap Standard
+
+## Purpose
+
+Use this when seeding a reusable upstream repo from a source repo that already
+contains working harness, product, infrastructure, or process artifacts.
+
+The standard applies across layers. Layer workflows define the specific
+portable file set for chat, frontend, CRUD factory, AWS CI/CD, or other
+upstream repo types.
+
+For public `llm-workbench` bootstrap or sync work, also apply
+`.agentic/00.chat/standards/llm-workbench-public-beta-contract.md`.
+
+## Ownership
+
+- The source repo provides working evidence and candidate files.
+- The upstream repo owns reusable behavior after bootstrap.
+- The layer-specific bootstrap workflow owns the portable file set.
+- Source-repo-specific product, deployment, customer, environment, credential,
+  path, and session-history details stay out of the upstream repo.
+
+## Required Inspection
+
+Before writing to the upstream repo, inspect and record:
+
+- source repo absolute path
+- upstream repo absolute path
+- target upstream repo purpose
+- whether the upstream repo is empty or already initialized
+- whether the upstream repo has a valid `HEAD`
+- current branch name, or the intended initial branch for an unborn `HEAD`
+- candidate portable paths
+- deterministic audit output for the layer-specific portable file set, when a
+  layer provides one
+- required exclusions
+- source paths that must remain private or source-specific
+- whether any target paths would be overwritten
+- whether the bootstrap creates a minimal usable product surface or only an
+  internal file baseline
+
+## Approval Boundaries
+
+- Read-only inspection does not approve writes.
+- Writing or overwriting upstream files requires explicit approval.
+- Creating an upstream commit requires explicit approval.
+- Pushing upstream changes requires separate explicit approval.
+- Deleting, moving, or rewriting upstream history requires separate explicit
+  approval and a workflow that governs that action.
+
+## Empty Repo Bootstrap
+
+For an empty upstream repo with no valid `HEAD`:
+
+- establish the initial branch before running workflows that require a current
+  branch
+- add starter public files required by the layer workflow
+- create an initial commit before attempting normal chat startup in the
+  upstream repo
+- do not push the initial commit without separate explicit approval
+
+Do not pre-copy source repo `commitLogs/`. The upstream repo's first chat
+startup creates its own `commitLogs/<date>/<session>/README.md` after the
+initial commit exists.
+
+## Required Exclusions
+
+Exclude by default:
+
+- `commitLogs/`
+- chat transcripts and local session artifacts
+- source repo product code
+- source repo deployment, cloud, or environment-specific rules
+- credentials, tokens, local profiles, and machine-specific paths
+- customer, tenant, or private business data
+- generated reports unless the layer workflow explicitly defines them as
+  reusable source material
+
+## Required Output
+
+A bootstrap workflow must produce or record:
+
+- source repo and upstream repo paths
+- file set copied or proposed
+- exclusions applied
+- initial branch and initial commit status for empty upstream repos
+- product-shell files created, when the upstream repo is intended for external
+  use
+- whether `commitLogs/` was created by a first upstream chat or intentionally
+  left absent until then
+- checks run
+- commit status
+- push status
+- follow-up needed before downstream repos can install or sync the upstream
+  repo
+
+## Stop Conditions
+
+Stop before writing when:
+
+- upstream ownership is ambiguous
+- the portable file set is not defined by a layer workflow or deterministic
+  audit when the layer provides one
+- target repo contains files that would be overwritten without approval
+- source-specific or private material cannot be cleanly separated
+- an externally usable upstream repo lacks install docs, examples, or smoke
+  tests defined by its layer workflow
+- the requested bootstrap would require a copy, commit, push, delete, move, or
+  overwrite action not governed by the current workflow

package/.agentic/shared/workflows/README.md

@@ -0,0 +1,35 @@
+<!-- agentic-artifact:
+schema: agentic-artifact/v2
+id: shared.workflows.readme
+version: 1
+status: active
+layer: 06.shared
+domain: process
+disciplines:
+- agentic
+kind: readme
+purpose: Index the active shared process workflows.
+portability:
+  class: required
+  targets:
+  - llm-workbench
+  - entity-builder
+  - design-system-builder
+used_by:
+- id: repo.agents
+  path: AGENTS.md
+- id: chat.migration-plan
+  path: .agentic/00.chat/migration-plan.md
+-->
+
+# Shared Workflows
+
+Shared workflows govern cross-layer process that does not belong to one
+specialized layer. Chat lifecycle ownership belongs in `.agentic/00.chat/`.
+
+## Workflows
+
+- `change-shared-process.md` - change cross-layer git, commit, merge, handoff,
+  deployment, release, or context-preservation process.
+- `capability-resolution-workflow.md` - propose or resolve capabilities before
+  implementation.

package/.agentic/shared/workflows/capability-resolution-workflow.md

@@ -0,0 +1,189 @@
+<!-- agentic-artifact:
+schema: agentic-artifact/v2
+id: shared.workflows.capability-resolution-workflow
+version: 1
+status: active
+layer: 06.shared
+domain: governance
+disciplines:
+- agentic
+kind: workflow
+purpose: Govern the Capability Resolution Workflow workflow.
+portability:
+  class: required
+  targets:
+  - llm-workbench
+  - entity-builder
+  - design-system-builder
+used_by:
+- id: repo.agents
+  path: AGENTS.md
+-->
+
+# Capability Resolution Workflow
+
+## Purpose
+
+Resolve a user request into the smallest safe execution path for the harness.
+
+Capability resolution happens after chat-start session discovery and before any workflow-specific gates are executed.
+
+The resolution order is:
+
+```text
+task -> layer -> mode -> workflow -> gates
+```
+
+## Resolution Fields
+
+### Layer
+
+Layer identifies the ownership area affected by the request.
+
+Allowed values:
+
+- `shared`
+- `chat`
+- `harness`
+- `education`
+- `product`
+- `mixed`
+- `unknown`
+
+Use `.agentic/routing-policy.yaml` as the source of truth for layer
+definitions.
+
+### Mode
+
+Mode identifies the kind of work the user is asking the agent to perform.
+
+Mode is independent of layer. The same mode can apply to chat, shared,
+harness, education, or product work.
+
+Allowed values:
+
+- `discovery`
+- `planning`
+- `execution`
+- `implementation`
+- `unknown`
+
+## Mode Definitions
+
+### discovery
+
+Use when the user wants explanation, discussion, brainstorming, conceptual guidance, or read-only inspection of files, logs, repository state, runtime state, or configuration.
+
+Default action: read-only response or inspection.
+
+### planning
+
+Use when the user wants a proposal, architecture, implementation plan, migration plan, or ordered change list.
+
+Default action: read-only planning.
+
+### execution
+
+Use when the user wants the agent to use an existing capability, workflow, gate, script, tool, or documented process without changing or adding capabilities.
+
+Default action: follow the selected workflow's gates before running the existing capability.
+
+### implementation
+
+Use when the user wants the agent to create, edit, move, delete, format, or otherwise modify files, or add/change capabilities, workflows, gates, scripts, tools, documentation, or process rules.
+
+Default action: require explicit write permission for the current chat before editing.
+
+### unknown
+
+Use when the mode cannot be resolved with enough confidence.
+
+Default action: stop and ask one clarifying question before selecting a workflow or editing files.
+
+## Workflow Selection
+
+Select a workflow only after both layer and mode are known.
+
+Workflow selection must respect both dimensions:
+
+- Layer determines ownership.
+- Mode determines posture and permissions.
+
+Examples:
+
+```text
+Layer: harness
+Mode: planning
+Workflow: upstream llm-workbench harness-maintenance process
+```
+
+```text
+Layer: chat
+Mode: implementation
+Workflow: .agentic/00.chat/workflows/chat-refresh-from-main.md
+```
+
+```text
+Layer: product
+Mode: implementation
+Workflow: .agentic/product/workflows/default.md
+```
+
+## Gates
+
+Gates run after workflow selection and before action.
+
+At minimum:
+
+- `execution` must use an existing capability, workflow, gate, script, tool, or documented process. If the capability must be created or changed first, treat the request as `implementation`.
+- `implementation` requires explicit write permission for the current chat.
+- `unknown` must not proceed to edits or commands that mutate state.
+- If a required action, recovery path, workaround, or substitution is not
+  governed by the selected workflow, gate, script, or standard, stop and report
+  the missing governance gap before acting.
+
+Workflows may define stricter gates.
+
+## Ambiguity
+
+Stop if any of these are ambiguous:
+
+- layer
+- mode
+- workflow
+- required permissions
+- whether a requested action mutates state
+
+Ask exactly one clarifying question, then resume resolution from the earliest ambiguous field.
+
+If a request contains more than one mode, split it into ordered phases and resolve each phase separately.
+
+Example:
+
+```text
+Phase 1: discovery
+Phase 2: implementation
+```
+
+## Prompt Routing Fixtures
+
+Prompt-level routing examples belong to the repo's context router when one
+exists. Use that router's fixtures and context-packet checks when prompt
+routing behavior changes.
+
+Add or update routing fixtures when:
+
+- prompt routing behavior surprises the user or agent
+- a prompt selector bug is fixed
+- a new layer or mode concept is introduced
+- routing rules are changed and existing behavior should be preserved
+
+## Session Metadata
+
+Chat session metadata records lifecycle continuity: session log, branch,
+worktree, transcript metrics, and latest context-packet references.
+
+Do not write durable chat-session `layer`, `mode`, or `workflow` fields. When a
+prompt needs those values, resolve them for the current prompt through this
+repo's assistant instructions and any repo-provided context router, then retain
+the packet reference as continuity evidence if a router returns one.

package/.agentic/shared/workflows/change-shared-process.md

@@ -0,0 +1,92 @@
+<!-- agentic-artifact:
+schema: agentic-artifact/v2
+id: shared.workflows.change-shared-process
+version: 1
+status: active
+layer: 06.shared
+domain: process
+disciplines:
+- agentic
+kind: workflow
+purpose: Govern changes to cross-layer shared process.
+portability:
+  class: required
+  targets:
+  - llm-workbench
+  - entity-builder
+  - design-system-builder
+used_by:
+- id: repo.agents
+  path: AGENTS.md
+-->
+
+# Change Shared Process Workflow
+
+## Use When
+
+Use this when a request changes cross-layer git, commit, merge, handoff,
+deployment, release, or context-preservation process.
+
+Chat lifecycle changes belong to `.agentic/00.chat/`.
+
+## Required Gates
+
+Before editing files:
+
+```bash
+bash scripts/00.chat/worktree/dirty-worktree-check/script.sh --allow-session-bookkeeping
+```
+
+`bookkeeping-only` is acceptable after explicit write permission for the chat.
+<!-- deterministic-check: allow reason="workflow defines exact blocked response around dirty-worktree gate output" -->
+If dirty, respond exactly:
+
+```txt
+Blocked: dirty worktree. Confirm proceed? Layer: shared. Mode: <mode>. Workflow: .agentic/shared/workflows/change-shared-process.md
+```
+
+Do not edit files while blocked.
+
+## Rules
+
+- Use the current branch session log as the first source of truth.
+- Keep `AGENTS.md` as a router; put procedure in shared workflows, checklists,
+  gates, or scripts.
+- Prefer deterministic scripts for repeatable checks.
+- Do not create a task commit, push, delete branches, rewrite history, discard
+  work, overwrite work, or perform destructive actions without explicit user
+  approval.
+- Chat task work must run in the chat-owned worktree recorded in the current
+  session log. The root worktree is the local integration console and must not
+  receive task edits, staging, formatting, or commits.
+- After explicit write permission for the chat, routine session bookkeeping may
+  be staged without another prompt when limited to the current chat session log.
+- Preserve unrelated user changes in a dirty worktree.
+- Before any commit, complete `.agentic/00.chat/checklists/before-commit.md`.
+
+## Chat Harness Delegation
+
+Shared-process changes still run inside the chat harness. Before writing, run:
+
+```bash
+bash scripts/00.chat/worktree/check-write-location/script.sh
+```
+
+<!-- deterministic-check: allow reason="ensure-chat-worktree enforces worktree creation and verification; workflow states when agents should invoke it" -->
+If a session log exists but its worktree is missing, recreate or verify it with:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/worktree/ensure-chat-worktree/script.sh <session-log>
+```
+
+The chat-owned worktree has its own files and index. Stage only approved
+repository-relative paths inside that worktree. The root worktree remains the
+local convergence console.
+
+Do not duplicate chat lifecycle, commit recording, transcript metrics,
+bookkeeping checkpoint, or commit-log deletion rules here. Use the canonical
+before-commit checklist for those gates:
+
+```
+.agentic/00.chat/checklists/before-commit.md
+```

package/.cursor/rules/llm-workbench.mdc

@@ -0,0 +1,17 @@
+---
+description: Use the llm-workbench chat harness
+alwaysApply: true
+---
+
+At the start of a chat, follow `.agentic/00.chat/workflows/chat-start.md`.
+Use the current branch's `commitLogs/<session>/README.md` as the first source
+of truth for chat lifecycle, branch, worktree, context-packet references,
+commits, and metrics.
+
+Do not assign the whole chat a durable layer, mode, or workflow. When a prompt
+needs layer, mode, workflow, corpus, or rule context, use the current user
+request, this repo's assistant instructions, and any repo-provided context
+router if one exists.
+
+Default mode after governed chat-start bootstrap is read-only until the user
+explicitly grants write permission for task files.

package/.github/copilot-instructions.md

@@ -0,0 +1,16 @@
+# Copilot Instructions
+
+This repo uses the `llm-workbench` chat harness.
+
+At the start of a chat, follow `.agentic/00.chat/workflows/chat-start.md`.
+Use the current branch's `commitLogs/<session>/README.md` as the first source
+of truth for chat lifecycle, branch, worktree, context-packet references,
+commits, and metrics.
+
+Do not assign the whole chat a durable layer, mode, or workflow. When a prompt
+needs layer, mode, workflow, corpus, or rule context, use the current user
+request, this repo's assistant instructions, and any repo-provided context
+router if one exists.
+
+Do not push, rewrite history, discard work, or overwrite work without explicit
+human approval.

package/AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md
+
+## Purpose
+
+This repo is governed by the llm-workbench chat harness. Keep this file small.
+Do not add project-specific or procedural rules here.
+
+## Before Acting
+
+0. Skip steps 1-7 if the user starts a chat with `ignore chat start`.
+1. Follow `.agentic/00.chat/workflows/chat-start.md`.
+2. Use the current branch's `commitLogs/<session>/README.md` session metadata
+   as the first source of truth for chat lifecycle, branch, worktree, latest
+   context packet references, commits, and metrics.
+3. Do not assign the whole chat a durable layer, mode, or workflow. Use the
+   current user request, this repo's assistant instructions, and any
+   repo-provided context router if one exists when a prompt needs layer, mode,
+   workflow, corpus, or rule context.
+4. Use `chat_lifecycle_workflow` for chat startup/session lifecycle gates; use
+   the latest context packet only as continuity evidence for future prompt-level
+   context queries.
+5. Follow the applicable chat lifecycle gate and any prompt-level context-router
+   packet checks before editing files.
+6. Stop when repo state, branch state, task ownership, prompt-level routing,
+   chat lifecycle state, or governance coverage is ambiguous or absent.
+7. Missing governance is a stop condition. If a required action, recovery path,
+   workaround, or substitution is not governed by the current workflow, gate,
+   script, or standard, stop before acting.
+8. Follow shared approval rules before commits or destructive actions; never
+   push, delete branches, rewrite history, discard work, or overwrite work
+   without explicit user approval.
+9. Default mode is read-only after governed chat-start bootstrap. The
+   chat-start workflow may create or verify the chat branch, worktree, and
+   session log from the opening prompt without separate permission unless the
+   prompt starts with `ignore chat start`. Do not create, edit, move, delete,
+   stage, commit, or format task files unless the user explicitly grants write
+   permission for this chat.
+
+## Operating Layers
+
+* `.agentic/00.chat/` governs chat lifecycle, including chat sessions, chat
+  worktrees, session logs, chat refresh, closeout, cleanup, shortcuts,
+  reporting, and upstream reusable lessons.
+* `.agentic/shared/` governs cross-layer process primitives, including git
+  approval rules, handoff, context compaction, and upstream repo bootstrap
+  standards.
+* Workbench maintenance belongs upstream in `llm-workbench`; target repos should
+  promote reusable harness lessons upstream instead of editing the harness in
+  place.
+
+## Source Of Truth
+
+* Session state: current branch's `commitLogs/<session>/README.md`
+* Chat lifecycle process: `.agentic/00.chat/`
+* Shared operating process: `.agentic/shared/`
+* Executable checks: `scripts/`
+* Human documentation: `docs/`
+* Commit/task logs: `commitLogs/`
+
+## Size Rule
+
+Keep `AGENTS.md` short. If a rule only applies to a specific workflow,
+checklist, standard, script, or install path, move it into that artifact.

package/CLAUDE.md

@@ -0,0 +1,16 @@
+# CLAUDE.md
+
+This repo uses the `llm-workbench` chat harness.
+
+At the start of a chat, follow `.agentic/00.chat/workflows/chat-start.md`.
+Use the current branch's `commitLogs/<session>/README.md` as the first source
+of truth for chat lifecycle, branch, worktree, context-packet references,
+commits, and metrics.
+
+Do not assign the whole chat a durable layer, mode, or workflow. When a prompt
+needs layer, mode, workflow, corpus, or rule context, use the current user
+request, this repo's assistant instructions, and any repo-provided context
+router if one exists.
+
+Default mode after governed chat-start bootstrap is read-only until the user
+explicitly grants write permission for task files.

package/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+Thanks for taking an interest in `llm-workbench`.
+
+This repo is a portable chat harness for governed agentic development. The
+main goal is to make chat startup, worktree use, commit gates, refreshes, and
+reusable lesson promotion repeatable enough that another engineer can install
+the harness into their own Git repo and understand what will happen.
+
+## Good First Contributions
+
+Good early contributions are usually small and inspectable:
+
+- clearer onboarding docs
+- safer install or uninstall behavior
+- better smoke tests
+- clearer names for scripts, workflows, or concepts
+- fixes where a documented command no longer matches the script it describes
+
+Avoid broad rewrites unless there is an issue or discussion that explains the
+new shape. The harness is intentionally explicit, so small changes are easier
+to review and safer for downstream repos.
+
+## Before Changing Harness Behavior
+
+If a change affects chat startup, branch/worktree handling, commit gates,
+refresh from `main`, local merge readiness, install/uninstall, or reusable
+lesson promotion, update the relevant docs and tests in the same change.
+
+At minimum, check:
+
+```bash
+npm run test:install
+bash tests/smoke-test-cli.sh
+```
+
+If you add or move a script, keep its nearby README current. The README should
+teach a new reader what the script does, when it runs, what it writes, and what
+approval boundaries it respects.
+
+## Pull Requests
+
+Please include:
+
+- what changed
+- why it changed
+- how you tested it
+- any behavior that downstream repos should notice
+
+Do not include private repo paths, local transcripts, API keys, customer data,
+or project-specific secrets in issues or pull requests.
+
+## Style
+
+Prefer plain Bash and Markdown unless a stronger reason exists. Keep public
+docs educational: assume the reader is new to this harness and explain the
+purpose of each moving part before asking them to rely on it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gordon Rose
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LLM_WORKBENCH.md

@@ -0,0 +1,17 @@
+# LLM Workbench Instructions
+
+This generic adapter is for CLI agents and assistants without a native
+repository-instruction filename, including Mistral-backed tools.
+
+At the start of a chat, follow `.agentic/00.chat/workflows/chat-start.md`.
+Use the current branch's `commitLogs/<session>/README.md` as the first source
+of truth for chat lifecycle, branch, worktree, context-packet references,
+commits, and metrics.
+
+Do not assign the whole chat a durable layer, mode, or workflow. When a prompt
+needs layer, mode, workflow, corpus, or rule context, use the current user
+request, this repo's assistant instructions, and any repo-provided context
+router if one exists.
+
+Default mode after governed chat-start bootstrap is read-only until the user
+explicitly grants write permission for task files.