sync(bfmono): feat(gambit): align scaffolds with product command and hourglass policies (+19 more) (bfmono@cae381f00)

This PR is an automated gambitmono sync of bfmono Gambit packages.

- Source: `packages/gambit/`
- Core: `packages/gambit-core/`
- bfmono rev: cae381f00

Changes:
- cae381f00 feat(gambit): align scaffolds with product command and hourglass policies
- 5faa48b35 feat(gambit): move bot policy to folder and enforce policy summarizer flow
- 9a36c4a7e fix(gambit): align env loading with init and block .gambit env writes
- dbe7c54ca feat(gambit-bot): add file actions and scenario deck structure
- 855784d6b docs(gambit): add public permissions guide and API jsdoc
- 8f0ca0a85 feat(gambit): trace effective permission layers at runtime
- 90b4b5071 feat(gambit-core): add phase-1 permission contract primitives
- df9280f6a fix(gambit): restore build-bot deck path compatibility
- daca46555 feat(simulator-ui): wire build, test, and grade to workspace sessions
- e404a17d7 feat(gambit): add workspace-backed serve and bot sandbox flow
- 5f4fa86b9 feat(gambit): scaffold workspace defaults in init
- cf9b23778 feat(gambit-core): add schema guards and model param passthrough
- d0e5a9617 [gambit] move chat message into transcript so it scrolls
- 5c6125d99 feat(simulator-ui): open workbench drawer by default
- 7c9cd05f8 feat(simulator): gate chat accordion by env flag
- a2599068e feat(simulator-ui): add build chat history loading
- 9911dae22 feat(simulator-ui): add workbench chat drawer accordion
- 8cab8ec1f feat(simulator-ui): dock calibrate drawer and sync updates
- d41ba101d Add AAR for phase 3.1.5 deck format build tab
- b1b5e2a7e Prefer PROMPT.md after build scaffolds

Do not edit this repo directly; make changes in bfmono and re-run the sync.

Author: bft-codebot

src/decks/gambit-bot/policy/README.md

@@ -12,6 +12,12 @@ Use this folder as the policy source of truth for Gambit Bot.
   creation).
 - [`safety-reliability.md`](./safety-reliability.md): Safety checks and fallback
   behavior when workflows may break or model/runtime setup is invalid.
+- [`product-command.md`](./product-command.md): Product Command operating rules
+  for deck creation and updates (ship small, focus impact, keep structure
+  stable).
+- [`hourglass.md`](./hourglass.md): How to apply Hourglass structure when
+  creating or updating `PROMPT.md`, especially system prompt/body sections
+  (`Assistant Persona`, `User Persona`, `Behavior`).
 - [`frontmatter-guardrails.md`](./frontmatter-guardrails.md): Rules and
   checklist for safe frontmatter and schema editing.
 - [`deck-format-1.0.md`](./deck-format-1.0.md): Full Deck Format v1.0

src/decks/gambit-bot/policy/hourglass.md

@@ -0,0 +1,44 @@
+# Hourglass Policy
+
+## Purpose
+
+- Define how Gambit Bot should structure prompt guidance so behavior is
+  predictable and easy to edit.
+- Keep deck prompts understandable by separating broad context from strict
+  execution constraints.
+- Ensure updates preserve a clear "narrow middle" where tool usage, formatting,
+  and step-by-step behavior are unambiguous.
+
+## Policy
+
+- Use Hourglass structure for bot authoring guidance:
+  - Wide context: assistant/user framing.
+  - Narrow middle: concrete behavior constraints, tool rules, output
+    requirements.
+  - Controlled widen-out: practical response guidance for the user.
+- Keep the narrow middle explicit and actionable (numbered steps, hard
+  constraints, escalation conditions).
+- When updating prompts, preserve clarity of the narrow middle before expanding
+  persona/detail sections.
+- For deck edits that touch behavior, ensure policy summaries include how the
+  "narrow middle" should change (or remain stable).
+
+- `Assistant Persona` (wide context):
+  - Define who the assistant is, its core goals, and tone boundaries.
+  - Keep this stable so behavior changes do not rewrite identity each time.
+- `User Persona` (wide context):
+  - Describe who the user is, what they are trying to achieve, and key fears or
+    constraints.
+  - Use this to guide prioritization and language, not to add execution rules.
+- `Behavior` (narrow middle):
+  - Define concrete steps, decision rules, tool usage expectations, and output
+    constraints.
+  - This is the most important control surface; keep it specific, testable, and
+    easy to diff.
+
+Tooling note:
+
+- `[[actions]]` in frontmatter defines which tools are available to the deck.
+- Those tool definitions are populated automatically into the runtime tool set.
+- Do not duplicate full tool inventories in the initial system/body prompt
+  unless there is a specific reason to add extra guardrails for one tool.

src/decks/gambit-bot/policy/product-command.md

@@ -0,0 +1,48 @@
+# Product Command Policy
+
+## Purpose
+
+- Keep Gambit Bot aligned with Product Command for deck creation and updates.
+- Prioritize user-visible progress, fast iteration, and clear deck structure.
+
+## Policy
+
+- Build less, ship more:
+  - Prefer the smallest runnable change that advances the user's goal.
+  - Avoid speculative abstractions or broad rewrites unless requested.
+- Focus on impact:
+  - Prioritize edits that improve user-facing bot behavior and reliability.
+  - Defer non-blocking internal cleanup when it does not unblock shipping.
+- Keep Deck Format v1.0 structure stable:
+  - `PROMPT.md` remains canonical.
+  - `INTENT.md` and `policy/*.md` are guidance surfaces, not executable prompts.
+- Be explicit about tradeoffs:
+  - Call out what is intentionally deferred.
+  - Escalate only when safety/reliability or format correctness is at risk.
+
+Every `INTENT.md` should explicitly answer these 8 questions:
+
+1. `Purpose`: Why does this scope exist?
+2. `End State`: What conditions define success?
+3. `Constraints`: What must not happen?
+4. `Tradeoffs`: Which decisions are already made?
+5. `Risk tolerance`: How bold can this effort be?
+6. `Escalation conditions`: When should we pause or escalate?
+7. `Verification steps`: What signals/commands prove success?
+8. `Activation / revalidation`: When does this intent start/stop governing
+   decisions, and what triggers review?
+
+`INTENT.md` maintenance expectations:
+
+- `INTENT.md` should match the user's stated goals, constraints, risk posture,
+  and success criteria as they are expressed in the session.
+- Treat `INTENT.md` as a living alignment artifact expected to change frequently
+  during build/edit loops, not a one-time static document.
+
+## Application to deck updates
+
+- If a default scaffold echo bot is detected, overwrite it by default unless the
+  user asks to preserve it.
+- Prefer iterative edits over multi-file rewrites when both can satisfy the
+  request.
+- Keep scenario/grader coverage runnable after each substantial change.

src/decks/gambit-init.deck.md

@@ -40,6 +40,10 @@ Rules:
 
 - Keep the conversation lightweight and opinionated.
 - Use Deck Format 1.0 (`PROMPT.md` with TOML frontmatter).
+- Use Hourglass structure in the root `PROMPT.md` body:
+  1. assistant persona context,
+  2. user persona context,
+  3. explicit behavior constraints/steps (the narrow middle).
 - Do not overwrite existing files; rely on tool errors if a path exists.
 - Create `scenarios/default/` and `graders/default/` with `mkdir` before writing
   files.

src/workspace.ts

@@ -39,7 +39,18 @@ description = "Simple grader to start."
 
 You are the default deck for a new Gambit workspace.
 
-Rules:
+## Assistant Persona
+
+- You are a practical starter assistant for quickly validating the workspace
+  loop.
+- You keep responses plain and easy to replace as the bot evolves.
+
+## User Persona
+
+- The user is trying to confirm the deck runs end-to-end before customizing.
+- They want predictable behavior and clear output.
+
+## Behavior
 
 - If the conversation does not yet contain a user utterance, reply exactly
   "Welcome to Gambit! What should we build?"
@@ -136,15 +147,13 @@ export async function createWorkspaceScaffoldAtRoot(
 
   const rootDeckPath = path.join(resolvedRoot, "PROMPT.md");
   const intentPath = path.join(resolvedRoot, "INTENT.md");
-  const policyPath = path.join(resolvedRoot, "POLICY.md");
   const scenariosDir = path.join(resolvedRoot, "scenarios", "default");
   const gradersDir = path.join(resolvedRoot, "graders", "default");
   const scenarioPromptPath = path.join(scenariosDir, "PROMPT.md");
   const graderPromptPath = path.join(gradersDir, "PROMPT.md");
 
   await ensureEmptyPath(rootDeckPath);
   await ensureEmptyPath(intentPath);
-  await ensureEmptyPath(policyPath);
   await ensureEmptyPath(scenarioPromptPath);
   await ensureEmptyPath(graderPromptPath);