llm-wb 0.1.0-beta.0

package/.agentic/00.chat/workflows/bootstrap-chat-workbench-repo.md

@@ -0,0 +1,212 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.workflows.bootstrap-chat-workbench-repo
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: bootstrap
+  disciplines:
+  - agentic
+  kind: workflow
+  purpose: Govern bootstrapping the portable chat workbench into an upstream repo.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: shared.standard.upstream-repo-bootstrap
+    path: .agentic/shared/standards/upstream-repo-bootstrap.md
+  - id: chat.script.bootstrap.audit-chat-bootstrap-file-set
+    path: scripts/00.chat/bootstrap/audit-chat-bootstrap-file-set/script.sh
+-->
+# Bootstrap Chat Workbench Repo Workflow
+
+## Use When
+
+Use this when seeding an upstream chat workbench repo such as `llm-workbench`
+from a source repo that already contains the chat harness.
+
+## Purpose
+
+Create the first minimal usable open-source chat workbench repo so engineers can
+read, install, test, and run the portable chat harness from the upstream repo.
+
+This workflow uses `.agentic/shared/standards/upstream-repo-bootstrap.md`.
+It also uses
+`.agentic/00.chat/standards/llm-workbench-public-beta-contract.md` for the
+public `llm-workbench` contract.
+
+## Required Gates
+
+Before writing to the upstream repo, inspect:
+
+```bash
+git -C <upstream-repo> status --short
+git -C <upstream-repo> remote -v
+git -C <upstream-repo> rev-parse --verify HEAD || true
+git -C <upstream-repo> branch --show-current || true
+find <upstream-repo> -maxdepth 2 -type f
+```
+
+Then run the portable script file set audit from the source repo:
+
+```bash
+bash scripts/00.chat/bootstrap/audit-chat-bootstrap-file-set/script.sh
+```
+
+If the upstream repo is not empty, list target paths that would be added or
+overwritten and ask for explicit approval before writing.
+
+If `HEAD` does not exist, treat the upstream repo as an empty bootstrap target.
+The initial branch must be `main` unless the user explicitly approves a
+different branch name.
+
+## Portable Chat File Set
+
+Initial candidate paths:
+
+- `AGENTS.md` as an upstream template, not a direct source-repo copy
+- `.agentic/00.chat/`
+- `.agentic/shared/standards/`
+- `.agentic/shared/workflows/` entries required by cross-layer process and
+  capability resolution
+- `package.json` chat command scripts as an upstream template, not a direct
+  source-repo copy
+- `scripts/00.chat/` canonical chat capability scripts required by the audit
+- `scripts/01.harness/` gates required by chat startup, commit,
+  governed script, and deterministic process checks
+- `docs/00.chat/`
+
+Do not copy the source repo `README.md` directly. It describes the source repo,
+not the upstream workbench.
+
+## Minimal Open-Source Product Shell
+
+The first bootstrap must include enough product surface to test the repo as an
+outside engineer would use it:
+
+- `README.md` as a public workbench overview
+- `LICENSE` when the user has chosen a license
+- `.gitignore` for local/editor/runtime clutter
+- `docs/concepts.md`
+- `docs/install.md`
+- `docs/workflows.md`
+- `docs/adapting-to-your-repo.md`
+- `examples/minimal-repo/`
+- `scripts/install.sh`
+- `scripts/uninstall.sh`
+- `tests/smoke-test-install.sh`
+- `docs/public-beta-contract.md`
+
+Starter templates for those files live in:
+
+```txt
+docs/00.chat/bootstrap/llm-workbench-template/root/
+```
+
+The install smoke test must install the workbench into a throwaway Git repo,
+verify the public command surface works, and verify the first chat startup
+creates the target repo's own `commitLogs/` inside a chat-owned worktree.
+
+Use `scripts/00.chat/bootstrap/audit-chat-bootstrap-file-set/script.sh` to distinguish
+required scripts from candidate unreferenced scripts before copying scripts
+into the upstream repo.
+
+Use `docs/00.chat/llm-workbench-acceptance-matrix.md` to verify the current
+public export boundary and the checks that enforce it.
+
+Before writing, run the dry-run planner:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/upstream/bootstrap-llm-workbench-repo/script.sh \
+  --target <upstream-repo> \
+  --dry-run
+```
+
+Only run `--apply` after reviewing a clean plan. Apply mode must refuse to
+write when the plan contains conflicts.
+
+Before commit, complete
+`.agentic/00.chat/checklists/llm-workbench-public-beta.md`.
+
+## Required Exclusions
+
+In addition to the shared standard exclusions, do not copy:
+
+- `.agentic/product/`
+- `.agentic/education/`
+- `.agentic/aws/`
+- product `src/`, `tests/`, or app docs
+- source repo `commitLogs/`
+- source repo-specific open tabs, transcripts, or local worktree paths
+
+## Initial Commit For Empty Repos
+
+For an empty upstream repo:
+
+1. Copy the approved portable file set and starter public files.
+2. Add the minimal open-source product shell.
+3. Verify `npm run chat:list` works.
+4. Verify `tests/smoke-test-install.sh` passes against a throwaway repo.
+5. Create the first upstream commit only after explicit commit approval.
+6. After the first commit exists, verify a normal chat can be started in the
+   upstream repo.
+
+Do not create or copy `commitLogs/` during bootstrap. The first upstream chat
+startup creates the upstream repo's first session log inside a chat-owned
+worktree.
+
+## Bootstrap Prompt Shape
+
+When preparing the first upstream bootstrap chat, use:
+
+```txt
+Task: Bootstrap llm-workbench with the portable chat harness
+
+Source repo: <absolute-path>
+Upstream repo: <absolute-path>
+Workflow: .agentic/00.chat/workflows/bootstrap-chat-workbench-repo.md
+Standard: .agentic/shared/standards/upstream-repo-bootstrap.md
+
+Goal:
+Create the first minimal usable open-source chat workbench in llm-workbench.
+
+Portable file set:
+<paths>
+
+Minimal product shell:
+<README, docs, examples, install scripts, smoke test>
+
+Required exclusions:
+<paths and categories>
+
+Initial Git state:
+<empty repo or existing HEAD>
+
+Starter public files:
+<README, LICENSE decision, gitignore>
+
+Boundaries:
+Inspect both repos before writing.
+Do not copy source-repo-specific product, deployment, customer, or session
+history into llm-workbench.
+Ask before writing upstream files.
+Ask before committing.
+Do not push unless explicitly approved separately.
+Do not copy source commitLogs; first upstream chat startup creates commitLogs
+inside a chat-owned worktree.
+```
+
+## Stop Conditions
+
+Stop if:
+
+- the upstream repo is not the intended repo
+- the upstream repo has existing files whose ownership is unclear
+- the upstream repo has no `HEAD` and the initial branch is not agreed
+- the portable file set cannot be separated from source-specific material
+- a required compatibility script or workflow is missing
+- starter public files are missing or would misrepresent the upstream repo
+- the install smoke test is missing or cannot prove a throwaway repo can use
+  the workbench
+- bootstrap would require push, destructive cleanup, or history rewrite

package/.agentic/00.chat/workflows/chat-cleanup.md

@@ -0,0 +1,102 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.workflows.chat-cleanup
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: cleanup
+  disciplines:
+  - agentic
+  kind: workflow
+  purpose: Govern cleanup of chat branches, worktrees, temporary refresh artifacts,
+    and empty session logs.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.readme
+    path: .agentic/00.chat/README.md
+  - id: chat.script.git.cleanup-empty-chat-branches
+    path: scripts/00.chat/git/cleanup-empty-chat-branches/script.sh
+-->
+# Chat Cleanup Workflow
+
+## Use When
+
+Use this when inspecting or cleaning chat branches, chat-owned worktrees,
+temporary preflight worktrees, or empty session logs.
+
+## Purpose
+
+Own cleanup of chat branches, chat-owned worktrees, temporary preflight
+worktrees, and empty session logs.
+
+## Required Gates
+
+Before deleting branches, removing worktrees, deleting logs, or discarding any
+work, inspect chat workspace state:
+
+```bash
+bash scripts/00.chat/reporting/report-chat-workspaces/script.sh
+```
+
+For empty chat branch cleanup, start with a dry run:
+
+```bash
+bash scripts/00.chat/git/cleanup-empty-chat-branches/script.sh --dry-run
+```
+
+Only run `--apply` after explicit user approval in the current chat:
+
+```bash
+bash scripts/00.chat/git/cleanup-empty-chat-branches/script.sh --apply
+```
+
+## Rules
+
+- Never remove dirty worktrees automatically.
+- Never delete logs with recorded commits or retention markers.
+- Never delete the current branch.
+- Never delete a branch checked out in any worktree.
+- Delete empty session logs only when the matching branch is empty and the log
+  names that branch.
+- Delete deterministic temporary preflight branches/worktrees only when their
+  corresponding operation has either been promoted or explicitly abandoned by
+  the user.
+- After a successful preflight promotion, automatically delete stale sibling
+  preflight branches/worktrees for the same chat branch only when the stale
+  branch is already an ancestor of the promoted chat branch and any associated
+  worktree is clean.
+- Report and skip stale sibling preflight branches that have unique commits,
+  dirty worktrees, multiple worktrees, or ambiguous ownership.
+- Require explicit approval for cleanup outside deterministic safe cases.
+- If a cleanup case is not covered here or by a script-level gate, stop and ask
+  whether to update the harness or approve a one-off exception.
+
+## Script Paths
+
+The canonical empty-branch cleanup script is:
+
+```txt
+scripts/00.chat/git/cleanup-empty-chat-branches/script.sh
+scripts/00.chat/reporting/report-chat-workspaces/script.sh
+```
+
+The old shared cleanup path remains as a compatibility wrapper during the
+script-layout migration. See ADR 0017 for compatibility-wrapper paths.
+
+Other cleanup helpers:
+
+```txt
+scripts/00.chat/main-refresh/apply-rehearsed-refresh/script.sh
+```
+
+## Migration Notes
+
+When migrating script paths later, preserve:
+
+- never remove dirty worktrees automatically
+- never delete logs with recorded commits or retention markers
+- delete only deterministic temporary preflight branches/worktrees
+- require explicit approval for cleanup outside deterministic safe cases

package/.agentic/00.chat/workflows/chat-commit.md

@@ -0,0 +1,56 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.workflows.chat-commit
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: chat
+  disciplines:
+  - agentic
+  kind: workflow
+  purpose: Document Chat Commit Workflow.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+    - entity-builder
+    - design-system-builder
+  used_by:
+  - id: repo.agents
+    path: AGENTS.md
+-->
+# Chat Commit Workflow
+
+## Purpose
+
+Own chat task commits, session-log commit recording, and narrow session
+bookkeeping checkpoints.
+
+## Required Gates
+
+Before committing approved task work, follow:
+
+```txt
+.agentic/00.chat/checklists/before-commit.md
+```
+
+## Rules
+
+- Use the current branch session log as the first source of truth.
+- Treat `.agentic/00.chat/checklists/before-commit.md` as the authority for
+  task-commit approval, write location, staging scope, transcript metrics,
+  checkpoint commits, and destructive-action boundaries.
+- Do not duplicate before-commit checklist rules in this workflow.
+
+## Migration Notes
+
+The executable scripts still live under `scripts/shared/` for compatibility.
+That path is implementation location, not ownership.
+
+When migrating script paths later, preserve:
+
+- explicit user approval before task commits
+- current session log as commit evidence
+- ADR disposition before task commit
+- checkpoint scope limited to the current session log
+- no automatic task staging outside approved paths

package/.agentic/00.chat/workflows/chat-promote-to-main.md

@@ -0,0 +1,169 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.workflows.chat-promote-to-main
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: local-merge
+  disciplines:
+  - agentic
+  kind: workflow
+  purpose: Govern explicit local merge from completed chat branches into main.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.workflows.readme
+    path: .agentic/00.chat/workflows/README.md
+  - id: chat.script.local-merge.verify-chat-ready-to-merge-local-main
+    path: scripts/00.chat/local-merge/verify-chat-ready-to-merge-local-main/script.sh
+-->
+# Chat Promote To Main Workflow
+
+## Use When
+
+Use this when completed chat branch work should be integrated into local `main`,
+or when deciding whether a chat branch is ready for promotion.
+
+## Purpose
+
+Treat the root worktree as the local integration console. Chat branches are
+feature branches owned by their chat worktrees. Integration into `main` is an
+  explicit local merge operation.
+
+## Required Gates
+
+Before merging, rebasing, staging, committing, pushing, deleting branches, or
+discarding work, run:
+
+```bash
+bash scripts/00.chat/worktree/dirty-worktree-check/script.sh
+```
+
+<!-- deterministic-check: allow reason="workflow defines the exact blocked response around the dirty-worktree gate output" -->
+If dirty, respond exactly:
+
+```txt
+Blocked: dirty worktree. Confirm proceed? Layer: chat. Mode: <mode>. Workflow: .agentic/00.chat/workflows/chat-promote-to-main.md
+```
+
+Do not change branches or edit files while blocked.
+
+## Intake
+
+1. Inspect all chat workspaces:
+
+   ```bash
+   bash scripts/00.chat/reporting/report-chat-workspaces/script.sh
+   ```
+
+2. Verify the target chat branch is ready to merge into local `main`:
+
+   ```bash
+   bash scripts/00.chat/local-merge/verify-chat-ready-to-merge-local-main/script.sh <chat-branch>
+   ```
+
+   This verification is read-only. It may inspect a session log from the chat
+   branch before that log exists on root `main`.
+
+3. If verification reports `State: eligible`, ask for explicit user approval
+   before merging the chat branch into local `main`.
+
+## Refresh Policy
+
+- A user request to merge or promote a chat branch to `main` also approves the
+  non-rewriting refresh from `main` that local merge requires, unless the
+  user explicitly asks to inspect before refresh.
+- Prefer merging `main` into a chat branch because it preserves recorded commit
+  SHAs and session evidence.
+- When promotion verification reports `blocked-behind` or `blocked-diverged`,
+  use the rehearsed preflight refresh flow in
+  `.agentic/00.chat/workflows/chat-refresh-from-main.md` before mutating the
+  active chat branch.
+- Rebase rewrites chat branch commits and requires explicit user approval.
+- Never refresh by discarding dirty work.
+- If conflicts appear, stop after Git reports the conflict set. Summarize the
+  conflicting files and ask before resolving them.
+
+### Behind `main`
+
+If verification reports `blocked-behind`, do not merge the chat branch into
+`main`. If the user already requested merge or promotion to `main`, refresh the
+chat branch from `main` without asking for a second approval.
+
+For the approved non-rewriting refresh, use the rehearsed preflight refresh flow
+from `.agentic/00.chat/workflows/chat-refresh-from-main.md`:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/main-refresh/rehearse-refresh-from-main/script.sh
+```
+
+If the preflight succeeds, run the required checks, apply the rehearsed refresh
+with `scripts/00.chat/main-refresh/apply-rehearsed-refresh/script.sh`, then
+rerun local merge verification.
+
+### Diverged From `main`
+
+If verification reports `blocked-diverged`, do not merge the chat branch into
+`main`. Explain that both `main` and the chat branch have unique commits.
+
+If the user already requested merge or promotion to `main`, run the rehearsed
+preflight refresh flow from `.agentic/00.chat/workflows/chat-refresh-from-main.md`
+without asking for a second approval. Rebase rewrites chat branch commits and
+requires separate explicit approval.
+
+If preflight conflicts appear, stop before resolving. Classify and record them
+using `.agentic/00.chat/standards/main-refresh-conflict-types.md`, then follow
+the preflight conflict audit and apply gates before mutating the active chat
+branch.
+
+### Dirty Chat Worktree
+
+<!-- deterministic-check: allow reason="verifier emits the state; prose governs human recovery choices" -->
+If verification reports `blocked-dirty-chat-worktree`, do not merge the chat
+branch into `main`.
+
+Do not stash, discard, stage, or commit dirty chat work automatically. Ask the
+user whether to inspect, commit, preserve, or explicitly discard the work.
+
+### Missing Or Ambiguous Evidence
+
+<!-- deterministic-check: allow reason="verifier emits the state; prose routes governed recovery and missing-governance fallback" -->
+If verification reports a missing log, missing worktree, invalid metadata,
+unrecorded commit, or log-head mismatch, do not merge. Follow the verifier's
+required action and rerun verification.
+
+If the required recovery path is not covered by this workflow, a script, a gate,
+or a standard, stop and report the missing governance gap before acting.
+
+## Promotion Policy
+
+Before promoting a chat branch into local `main`:
+
+- Root `main` must be clean.
+- The chat worktree must be clean.
+- The session log must record the latest task commit or explicitly state why no
+  task commit exists.
+- The chat branch must include latest local `main`. If a refresh is needed, the
+  initial merge or promotion request approves the non-rewriting refresh from
+  `main`.
+- Relevant checks for the changed layer must pass.
+- User approval is required before merging into `main`.
+
+For an approved local merge, run from the root integration worktree:
+
+```bash
+git merge --no-ff <chat-branch>
+```
+
+Pushes to `origin` require separate explicit approval.
+
+## Cleanup Policy
+
+- Empty abandoned chat branches may be deleted with their matching commit log
+  only when the log has no recorded commits and no retention marker.
+- Superseded chat branches may have their branch and worktree removed, but
+  their commit log stays as historical evidence.
+- Logs with recorded commits or retention markers must not be deleted
+  automatically.