llm-wb 0.1.0-beta.0

package/.agentic/00.chat/workflows/chat-refresh-from-main.md

@@ -0,0 +1,242 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.workflows.chat-refresh-from-main
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: main-refresh
+  disciplines:
+  - agentic
+  kind: workflow
+  purpose: Govern refreshing a chat branch from local main without losing work or bypassing
+    recovery paths.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: shared.workflows.change-shared-process
+    path: .agentic/shared/workflows/change-shared-process.md
+  - id: harness.architecture.adr.0011-use-chat-owned-worktrees-for-local-convergence
+-->
+# Chat Refresh From Main Workflow
+
+## Use When
+
+Use this after `main` changes, or when a chat branch may need to absorb newer
+accepted work from `main`.
+
+## Purpose
+
+Keep `main` as the canonical accepted baseline while preserving chat branch
+history, user work, and session evidence.
+
+## Required Gates
+
+Before changing branches, merging, rebasing, staging, or committing, run:
+
+```bash
+bash scripts/00.chat/main-refresh/classify-refresh-readiness/script.sh
+```
+
+<!-- deterministic-check: allow reason="refresh-readiness classifier determines dirty state; workflow defines the human-facing blocked response" -->
+If the classifier reports `unsupported-dirty`, respond exactly:
+
+```txt
+Blocked: required action is not governed.
+Action needed: refresh chat branch from main
+Blocking condition: unsupported dirty state before main refresh
+Missing governance: .agentic/00.chat/workflows/chat-refresh-from-main.md does not define a deterministic recovery path for this dirty state
+Confirm update the harness or approve a one-off exception?
+```
+
+Do not edit files, change branches, stash, restore, merge, rebase, stage, or
+commit while blocked.
+
+## Main Update Intake
+
+1. Confirm `main` exists locally:
+
+   ```bash
+   git show-ref --verify --quiet refs/heads/main
+   ```
+
+<!-- deterministic-check: allow reason="show-main-update-status reports remote presence; workflow keeps the human fetch policy visible" -->
+2. If a remote exists, fetch before comparing:
+
+   ```bash
+   git fetch --prune
+   git branch -vv --all
+   ```
+
+<!-- deterministic-check: allow reason="show-main-update-status emits the local-only freshness warning deterministically" -->
+3. If no remote exists, state that freshness is only local.
+
+4. Inspect branch relationship:
+
+   ```bash
+   bash scripts/00.chat/main-refresh/show-main-update-status/script.sh
+   ```
+
+5. Inspect active branch metadata and changed-path overlap:
+
+   ```bash
+   bash scripts/00.chat/local-merge/list-active-chat-branches/script.sh
+   bash scripts/00.chat/local-merge/report-chat-branch-overlaps/script.sh
+   ```
+
+## Refresh Policy
+
+- New chat branches should start from `main`.
+- Existing active chat branches should be compared with `main` before more
+  work is added.
+- Main refresh is branch maintenance. Keep it separate from task commits.
+- Prefer merging `main` into an active chat branch because it preserves history
+  and does not rewrite published or session evidence.
+- For normal repository work, prefer a governed chat checkpoint commit before
+  refreshing from `main`; do not hide task work in stash by default.
+- Preflight the refresh in a temporary worktree before mutating the active chat
+  worktree when the branch has task commits or a checkpoint.
+- Rebase, cherry-pick repair, force update, branch deletion, and push require
+  explicit user approval in the current chat.
+- Never discard dirty work to refresh a branch.
+- Do not use `git stash` in this workflow unless a later governed stash
+  capability defines exact path scope, stash identity recording, apply/drop
+  behavior, and conflict handling.
+- If conflicts appear outside a governed recovery path, stop after Git reports
+  the conflict set. Summarize the conflicting files and ask for approval before
+  resolving them.
+
+## Dirty State Classes
+
+Classify before refresh:
+
+```bash
+bash scripts/00.chat/main-refresh/classify-refresh-readiness/script.sh
+```
+
+The classifier reports state; the workflow decides what is allowed.
+
+- `clean`: the active chat worktree can use the normal refresh or preflight
+  flow.
+- `current-session-bookkeeping`: dirty paths are limited to the current chat
+  session log. Preserve the session log. If the incoming `main` overlap
+  includes the current session log, stop.
+- `repo-work`: dirty paths include normal repository work. Create a governed
+  checkpoint commit before refresh if the user approves. Do not stash by
+  default.
+- `unsupported-dirty`: stop. The workflow does not own this recovery.
+
+## Checkpoint And Rehearsed Refresh
+
+Use this when normal repository work exists on the chat branch or when a main
+refresh should be rehearsed before mutating the active chat worktree.
+
+<!-- deterministic-check: allow reason="checkpoint commits require human approval and existing commit gates" -->
+1. If normal repository work is dirty, create an explicit chat checkpoint commit
+   only after user approval and the relevant gates.
+2. Once the active chat worktree is clean, create a temporary refresh branch and
+   worktree:
+
+   ```bash
+   bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/main-refresh/rehearse-refresh-from-main/script.sh
+   ```
+
+3. If preflight reports conflicts, stop before resolving. Classify each
+   conflicted path with:
+
+   ```bash
+   bash scripts/00.chat/main-refresh/classify-conflict/script.sh <conflicted-path>
+   ```
+
+   Use `.agentic/00.chat/standards/main-refresh-conflict-types.md` as the
+   authority for the classification. Resolve only conflicts with deterministic
+   actions in that standard. If no existing type fits, use the
+   missing-governance stop response and propose a new type or expansion before
+   resolving.
+
+   Record every conflict classification and resolution under `## Main Refresh
+   Conflicts` in the current chat session log with:
+
+   ```bash
+   bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/session-log/record-main-refresh-conflict/script.sh ...
+   ```
+
+   Do not apply the rehearsed refresh until the session log records the audit
+   trail for every conflicted path.
+4. If the user already approved the main-refresh preflight, and the preflight
+   branch is clean, fully resolved, tested, and contains the intended merge
+   result, verify the session-log audit trail, then apply it back to the chat
+   branch automatically:
+
+   ```bash
+   bash scripts/00.chat/main-refresh/verify-conflict-audit/script.sh \
+     --path <conflicted-path> ...
+   bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/main-refresh/apply-rehearsed-refresh/script.sh <preflight-branch>
+   ```
+
+5. Applying the rehearsed refresh fast-forwards the active chat branch, verifies it points at the
+   tested preflight commit, removes the clean temporary preflight worktree,
+   deletes the matching `agentic/preflight/*/<timestamp>` branch, and cleans up
+   stale sibling preflight branches/worktrees for the same chat branch when they
+   are already ancestors of the promoted chat branch and have clean or absent
+   worktrees.
+<!-- deterministic-check: allow reason="apply-rehearsed-refresh enforces dirty preflight worktree refusal before applying or cleanup" -->
+6. Stop before applying if unresolved conflicts remain, required checks failed
+   or were skipped, the preflight worktree is dirty, the preflight branch no
+   longer descends from the chat branch, the apply script refuses cleanup,
+   or the user explicitly asked to inspect before applying. Stale sibling
+   preflight branches with unique commits or dirty worktrees must be reported
+   and skipped, not deleted. Do not force-remove the preflight worktree, delete
+   the preflight branch, or apply the refresh while stopped.
+7. After applying the refresh, run the relevant layer checks before any task commit or
+   promotion to `main`.
+
+## Recommended Active-Branch Flow
+
+1. Record the starting branch:
+
+   ```bash
+   git branch --show-current
+   ```
+
+2. Inspect status:
+
+   ```bash
+   git status --short --branch
+   bash scripts/00.chat/main-refresh/classify-refresh-readiness/script.sh
+   bash scripts/00.chat/main-refresh/show-main-update-status/script.sh
+   bash scripts/00.chat/local-merge/list-active-chat-branches/script.sh
+   bash scripts/00.chat/local-merge/report-chat-branch-overlaps/script.sh
+   ```
+
+3. If the active chat branch is behind `main`, ask before integrating `main`
+   unless the user already explicitly requested that operation.
+
+4. If the active chat worktree is clean and the refresh does not require
+   rehearsal, an approved non-rewriting refresh may merge directly:
+
+   ```bash
+   git merge --no-ff main
+   ```
+
+5. If the branch contains task commits, checkpoint commits, or uncertain merge
+   risk, use the preflight flow instead of merging directly in the active chat
+   worktree.
+
+6. Run the relevant checks for the changed layer before committing.
+
+7. Record decisions, issues, and ADR disposition in the current session log
+   before any task commit.
+
+## After Refresh
+
+- Report whether the branch is now even with, ahead of, behind, or diverged
+  from `main`.
+- Note whether the comparison used local refs only or included a remote fetch.
+- Record the classifier result, dirty paths, incoming overlap paths, recovery
+  action, preflight branch, preflight worktree, promoted commit, cleanup result,
+  conflict type for each conflicted path, deterministic action used, and whether
+  stash was used. Expected value for stash is `no` unless a later governed stash
+  path is approved.
+- Do not commit the refresh unless the user explicitly approves the commit.

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

@@ -0,0 +1,69 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.workflows.chat-reporting
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: chat
+  disciplines:
+  - agentic
+  kind: workflow
+  purpose: Document Chat Reporting Workflow.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+    - entity-builder
+    - design-system-builder
+  used_by:
+  - id: repo.agents
+    path: AGENTS.md
+-->
+# Chat Reporting Workflow
+
+## Use When
+
+Use this when the user asks for summaries, metrics, or reports derived from chat
+session logs.
+
+## Purpose
+
+Own on-demand reports from chat session logs.
+
+## Source Evidence
+
+- Individual session logs under `commitLogs/` are durable source evidence.
+- The retired aggregate path `commitLogs/README.md` is not maintained.
+- Report artifacts are temporary or explicitly requested outputs, not automatic
+  branch bookkeeping.
+
+## On-Demand Summary
+
+Use the chat-layer reporting skill for human-oriented summary work:
+
+```txt
+.agentic/00.chat/skills/session-summary.md
+```
+
+Use the script for deterministic aggregate metrics:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/reporting/generate-commit-log-summary/script.sh
+```
+
+To write a file, require an explicit output path:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/reporting/generate-commit-log-summary/script.sh --output <path>
+```
+
+## Rules
+
+- Do not recreate tracked `commitLogs/README.md`.
+- Treat individual session logs as source evidence.
+- Write file artifacts only to explicit user-requested paths.
+- Prefer stdout for quick inspection.
+- If the requested report needs interpretation beyond deterministic metrics,
+  cite the source session logs used.
+- If a requested report would need new persistent generated files, stop and ask
+  whether the harness should define that artifact first.

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

@@ -0,0 +1,173 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.workflows.chat-start
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: startup
+  disciplines:
+  - agentic
+  kind: workflow
+  purpose: Govern chat startup routing, session metadata discovery, and first-chat setup
+    steps.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: repo.agents
+    path: AGENTS.md
+  - id: chat.script.startup.start-chat-session
+    path: scripts/00.chat/startup/start-chat-session/script.sh
+-->
+# Chat Start Workflow
+
+## Purpose
+
+Use this at the start of a new chat to identify the active session, chat
+lifecycle workflow, latest context-packet references, and chat-owned worktree
+with minimal token use.
+
+## Fast Path
+
+First run:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/startup/resolve-current-chat-session/script.sh "<opening user message>"
+```
+
+This startup bootstrap is governed by the opening prompt. It may create or
+verify the chat branch, chat-owned worktree, and session log before task write
+permission is granted. Task edits remain read-only until the user grants write
+permission for the chat.
+
+If it returns valid chat lifecycle metadata, use it for session/worktree
+handling.
+
+Do not assign the whole chat a durable layer, mode, or workflow.
+Do not read `.agentic/routing-policy.yaml`.
+Do not load unrelated workflows, skills, standards, or documentation.
+
+If the metadata includes a `worktree` value, use that chat-owned worktree for
+task writes. The root worktree is the local integration console.
+
+If it reports `recorded-session-approval-required`, do not use the existing
+session metadata and do not edit files. Respond exactly:
+
+```txt
+Blocked: existing chat session has recorded commits. Confirm continue this existing chat/worktree, or start a new chat?
+```
+
+If the opening user request explicitly approves continuing the existing
+chat/worktree, rerun:
+
+```bash
+bash scripts/00.chat/session-log/read-current-chat-log/script.sh --allow-recorded-session
+```
+
+Only then may the existing session metadata be used.
+
+After the user first grants write permission for the chat, rename the current
+session log folder to a concise summary:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/session-log/rename-current-chat-log-folder/script.sh "<short-summary>"
+```
+
+If the current assistant can provide transcript metadata, record it through the
+neutral `transcript_provider`, `transcript_path`, `transcript_bytes`, and
+`transcript_source` session metadata fields before the first task commit.
+
+For Codex sessions, this optional adapter can discover and register the local
+JSONL transcript path:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/transcript/register-codex-session-log/script.sh
+```
+
+Missing transcript metadata is not a chat-start blocker in portable mode. Commit
+recording will mark token metrics unavailable unless strict transcript metrics
+mode is explicitly requested.
+
+## Missing Session
+
+<!-- deterministic-check: allow reason="resolve-current-chat-session.sh owns missing-session detection and auto-start execution" -->
+If no matching chat log exists for the current branch, or if
+`read-current-chat-log` reports `ERROR: current branch is not a chat branch:
+main`, treat the opening user message as a request for a new chat session
+unless it starts with `ignore chat start`. This is the Missing Session path, not
+a read-only orientation stop condition.
+
+If the opening message is exactly `new`, ask exactly:
+
+```txt
+What should the new chat be about?
+```
+
+Do not create a session until the user provides a task summary.
+
+Otherwise run:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/startup/resolve-current-chat-session/script.sh "<opening user message>"
+```
+
+After the command succeeds, use the generated session log, chat lifecycle
+workflow, latest context-packet references, and chat-owned worktree as the
+current chat context. Do not require the user to paste the generated first
+prompt back into the same chat.
+
+## Context Packet Continuity
+
+<!-- deterministic-check: allow reason="prompt routing may be manual or repo-specific; no universal script can decide whether a context router exists" -->
+Do not assign the whole chat a durable layer, mode, or workflow during startup.
+When later prompts need 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.
+
+<!-- deterministic-check: allow reason="context packets are optional continuity evidence and may come from repo-specific routers" -->
+If latest context-packet metadata is missing, leave it blank until a governed
+context-router query returns a packet. Record only the latest context packet ID,
+routing summary, and timestamp as continuity references. Do not copy the
+packet's prompt route into chat session `layer`, `mode`, or `workflow` fields.
+
+## Dirty Worktree
+
+Before editing files, run:
+
+```bash
+bash scripts/00.chat/worktree/dirty-worktree-check/script.sh
+```
+
+<!-- deterministic-check: allow reason="dirty-worktree-check.sh detects dirty state; workflow defines the exact blocked response" -->
+If dirty, respond exactly:
+
+```txt
+Blocked: dirty worktree. Confirm proceed?
+```
+
+Do not explain unless asked.
+Do not edit files while blocked.
+
+## Write Requests Without A Chat Worktree
+
+If the user grants write permission but the current session has no chat-owned
+worktree, create or verify it before editing:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/worktree/ensure-chat-worktree/script.sh <session-log>
+```
+
+<!-- deterministic-check: allow reason="check-write-location.sh enforces the write-location invariant; workflow states when agents should invoke it" -->
+Then run task commands from that worktree and verify:
+
+```bash
+bash scripts/00.chat/worktree/check-write-location/script.sh
+```
+
+## Migration Notes
+
+The executable chat startup scripts now live under canonical
+`scripts/00.chat/...` capability folders. Old `scripts/shared/chat/` command
+wrappers have been retired; use public `package.json` `chat:*` commands or
+the canonical governed script paths.

package/.agentic/00.chat/workflows/chat-upstream-reusable-lesson.md

@@ -0,0 +1,123 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.workflows.chat-upstream-reusable-lesson
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: chat
+  disciplines:
+  - agentic
+  kind: workflow
+  purpose: Document Chat Upstream Reusable Lesson Workflow.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+    - entity-builder
+    - design-system-builder
+  used_by:
+  - id: repo.agents
+    path: AGENTS.md
+-->
+# Chat Upstream Reusable Lesson Workflow
+
+## Use When
+
+Use this when work in a product or downstream repo reveals a reusable chat
+harness lesson that should be promoted to an upstream workbench repo such as
+`llm-workbench`.
+
+## Purpose
+
+Create a governed handoff from the source repo where the lesson was discovered
+to the upstream workbench repo that owns reusable chat harness behavior.
+
+The workflow documents and opens the upstream task. It does not silently copy
+files, edit the source repo, push to remotes, or mutate both repos in one step.
+
+Architecture decision: `docs/harness/architecture/adrs/0014-promote-reusable-lessons-upstream.md`.
+
+When the reusable lesson affects public `llm-workbench` startup, install,
+assistant adapters, metrics, portability, or export behavior, it must preserve
+`.agentic/00.chat/standards/llm-workbench-public-beta-contract.md`.
+
+## Ownership Model
+
+- The source repo provides evidence from real work.
+- The upstream workbench repo owns reusable chat harness workflows, scripts,
+  checklists, standards, and installer behavior.
+- Product, deployment, domain, and customer-specific rules stay in the source
+  repo.
+- If ownership is ambiguous, stop and ask whether the lesson is reusable or
+  source-repo-specific.
+
+## Required Source Packet
+
+Before opening the upstream chat, collect:
+
+- source repo absolute path
+- source branch
+- source chat worktree absolute path
+- source session log absolute or repo-relative path
+- source transcript provider and path when recorded in session metadata
+- target upstream repo absolute path
+- reusable lesson summary
+- source evidence paths or commands
+- source-repo-specific details that must not be promoted
+
+## Required Boundaries
+
+The upstream handoff prompt must include:
+
+```txt
+Inspect the source paths read-only.
+Do not edit the source repo.
+Do not copy source-repo-specific product, deployment, customer, or domain rules
+into the upstream workbench.
+Extract only the reusable chat harness lesson.
+If reusable ownership is ambiguous, stop and ask.
+Do not push unless explicitly approved separately.
+```
+
+## Opening The Upstream Chat
+
+From the upstream workbench repo, start a normal chat session using the existing
+chat startup path. The source repo may prepare the prompt, but the upstream repo
+must own the implementation chat.
+
+The prompt should include:
+
+```txt
+Task: Promote reusable chat harness lesson into llm-workbench
+
+Source repo: <absolute-path>
+Source branch: <branch>
+Source chat worktree: <absolute-path>
+Source session log: <path>
+Source transcript: <path-or-blank>
+Target repo: <absolute-path>
+
+Reusable lesson:
+<summary>
+
+Evidence:
+<paths, commands, failure mode, decisions>
+
+Keep out of upstream:
+<source-repo-specific details>
+
+Boundaries:
+Inspect the source paths read-only.
+Do not edit the source repo.
+Do not copy source-repo-specific product, deployment, customer, or domain rules
+into the upstream workbench.
+Extract only the reusable chat harness lesson.
+If reusable ownership is ambiguous, stop and ask.
+Do not push unless explicitly approved separately.
+```
+
+## Later Script
+
+A later command may prepare this source packet and open the upstream chat, but
+the command must preserve the boundaries above. Do not script cross-repo copying
+until this workflow has been exercised manually.

package/.agentic/shared/standards/README.md

@@ -0,0 +1,32 @@
+<!-- agentic-artifact:
+schema: agentic-artifact/v2
+id: shared.standards.readme
+version: 1
+status: active
+layer: 06.shared
+domain: governance
+disciplines:
+- agentic
+kind: readme
+purpose: Index the Shared Standards artifact family.
+portability:
+  class: required
+  targets:
+  - llm-workbench
+  - entity-builder
+  - design-system-builder
+used_by:
+- id: repo.agents
+  path: AGENTS.md
+-->
+
+# Shared Standards
+
+Shared standards govern cross-layer expectations that more than one layer can
+reuse.
+
+## Standards
+
+- `upstream-repo-bootstrap.md` - bootstrap reusable upstream repos from a
+  source repo without leaking source-specific behavior.
+