@fugood/bricks-ctor 2.25.0-beta.6 → 2.25.0-beta.60

package/skills/bricks-ux/references/ux-critique.md

@@ -0,0 +1,256 @@
+# UX Critique
+
+Verification proves the flow *runs*. UX critique proves the flow is *usable*. Both are required before declaring done; neither substitutes for the other.
+
+UX critique runs in parallel with visual-design critique (`bricks-design/design-critique.md`). A Canvas can fail one and pass the other; both block ship.
+
+This file is tiered. The same UX problem (e.g., closure missing) is **CRITICAL** on a payment kiosk and **MEDIUM** on a museum signage loop. Critique fails ship when CRITICAL or HIGH items go unaddressed in their applicable tiers.
+
+## How to run the pass
+
+1. **Open the journey.** Walk every interaction step-by-step using `user-journey.md` as the spine.
+2. **For each Canvas / Brick group, classify by deployment risk** (table below). The classification determines which tier of checks apply.
+3. **Run the checks in the applicable tier(s).** CRITICAL items always run; HIGH applies broadly; MEDIUM and LOW depend on classification.
+4. **Fix every CRITICAL miss and every HIGH miss.** Surface MEDIUM and LOW misses in the trade-off note if not addressed.
+5. **Re-verify after fixes.** Don't accumulate fix debt.
+
+## Risk classification by deployment shape
+
+| Deployment shape | Risk profile | Tier weighting |
+|---|---|---|
+| Payment / identity capture / safety-critical | CRITICAL-dense — every transact discipline must pass | CRITICAL + HIGH + MEDIUM all apply |
+| Self-service interactive (ordering, check-in, configuration) | HIGH-dense — journey completeness, idle reset, recovery paths | CRITICAL + HIGH apply; MEDIUM where relevant |
+| Monitoring / dashboard / control room | HIGH-dense — alarm hierarchy, stale-data trust, calm/detect/demand | CRITICAL + HIGH apply for alarm states |
+| Browse / wayfinding / menu board | MEDIUM-dense — legibility, comparison clarity, sparse states | HIGH legibility, MEDIUM elsewhere |
+| Glanceable signage / dwell / ambient loop | LOW-dense — main checks are legibility and rhythm | HIGH legibility, LOW elsewhere |
+
+## CRITICAL — blocks ship
+
+Failure on any of these is sufficient grounds to declare the work mid-iteration.
+
+### CR-1. The user-journey spine is whole
+
+Every interaction must have all seven steps present (or deliberately compressed; see `user-journey.md` § "When the seven steps compress"). Most-common holes:
+
+- **Immediate feedback missing** (step 3). User taps, nothing visible, taps again.
+- **In-flight visibility missing** (step 4). Action triggered, screen frozen, user re-triggers.
+- **Recovery as dead-end** (step 6). Error Canvas with no path forward.
+- **Closure ambiguous or missing** (step 7). Success state transient or unclear.
+
+**Must Have:** every interaction has a designed and verified affordance, instruction, feedback, in-flight state, continuation, recovery, closure — or deliberate documented collapse.
+**Anti-Pattern:** journey skipping any step on the assumption "it's fast enough not to need".
+
+### CR-2. Transact has its intensification
+
+For payment / identity / safety-critical flows, the seven steps must be tightened (`user-journey.md` § "When the seven steps intensify"):
+
+- Confirmation step before commit.
+- In-flight visibility non-skippable.
+- Recovery categorised (declined / network / cancelled / timeout).
+- Closure with weight and hold time.
+
+**Must Have:** transact closure holds ≥ 5 seconds, success unmistakable, peripheral state visible.
+**Anti-Pattern:** "Process payment in one tap" with no confirmation; closure that auto-advances in < 2s.
+
+### CR-3. Monitoring has demand discipline
+
+For dashboards / monitor screens with alarm capability:
+
+- Calm / detect / demand are three distinct designed states.
+- Demand state stands out unambiguously; not a slight colour change.
+- Multiple concurrent demand states have priority ordering already designed.
+- Stale-data is visibly declared per source.
+- Color is never the only encoding of severity.
+
+**Must Have:** alarm-state preview captured and reviewed; squint-test passes (alarm visible from peripheral vision); monochrome preview still distinguishes severity tiers.
+**Anti-Pattern:** alarm styled identically to detect-state; "stale" indicator at 8pt in corner; severity by colour alone.
+
+### CR-4. Accessibility floors met for the audience
+
+The seven accessibility disciplines (`accessibility.md`) apply at deployment-relative floors. CRITICAL when the audience includes:
+
+- Reduced-vision users (contrast, scale, color-not-only).
+- Reduced-motor users (touch targets, no precise gestures, no time-pressure auto-cancels).
+- Sensitive-to-motion users (reduced-motion path available).
+- Multilingual audience (strings via Data; type scale accommodates longest translation).
+
+**Must Have:** contrast verified under deployment-actual lighting; touch targets verified with real-finger / real-hardware testing; severity / status encoded by shape + color + label.
+**Anti-Pattern:** WCAG-compliance-on-desktop-monitor as the audit (deployment is sunlit signage at 4m); time-pressure UI on a venue that includes slow / hesitant users.
+
+### CR-5. Idle reset is clean
+
+For self-service interactive deployments:
+
+- Idle timeout exists and is calibrated to the use pattern.
+- Idle reset clears flow state — no half-built order persists; no name on screen; no half-confirmed action.
+- Reset returns to a designed idle / attractor state, not to "whatever Canvas was loaded".
+
+**Must Have:** verified idle reset behaviour via Automation or live test; verified that no leaked state persists to next session.
+**Anti-Pattern:** idle = last interact Canvas; idle that requires operator to manually reset.
+
+## HIGH — must fix before launch
+
+### H-1. Affordance is unambiguous
+
+Every pressable Brick declares "press me" visually — contrast, weight, motion, or icon. Affordance vocabulary is consistent across the deployment.
+
+**Must Have:** pressable tiles visually distinct from non-pressable; squint test confirms which Bricks are interactive.
+**Anti-Pattern:** identical-looking tiles where some are pressable and some aren't; pressable Bricks with no visual distinction from background.
+
+### H-2. Press feedback at registration
+
+Every `on_press` produces a visible state change at the moment of registration — scale, opacity, color, or new Brick entry via Standby Transition. Not a fade-in.
+
+**Must Have:** Brick under press visibly responds within 100ms (effectively snap, not fade).
+**Anti-Pattern:** press registers, no visible change; press relies on Canvas-change-only feedback (user perceives lag).
+
+### H-3. Flow states designed, not skipped
+
+Idle / loading / empty / error / boot / maintenance (as applicable to the deployment) are designed states, each with verified preview.
+
+**Must Have:** every applicable state's preview captured and reviewed; failure modes per state checked against `flow-states.md`.
+**Anti-Pattern:** "empty state is fine, the list is always populated" without testing the empty case; error state in 8pt corner text; boot = loading spinner.
+
+### H-4. Hero continuity across journey Canvases
+
+For multi-Canvas flows, hero Bricks share ids across Canvases — chrome (logo, progress indicator, time, back action) carries via Truth #3 auto-tween.
+
+**Must Have:** primary chrome elements identifiable in the same screen positions across the flow's Canvases.
+**Anti-Pattern:** every Canvas remounts its full Brick set; user loses spatial mental model between steps.
+
+### H-5. Error recovery has a path
+
+Every error state offers retry, alternate method, abandon, or help — never a dead-end. Different error categories get distinguishable recovery treatments.
+
+**Must Have:** each error path verified end-to-end via Automation or live test.
+**Anti-Pattern:** "Error. Please try again." with no retry mechanism; generic recovery for all error types.
+
+### H-6. Stale-data trust
+
+For monitoring / live-data screens, every dynamic source has a visibly declared staleness state or a visible "last update" relative-time indicator.
+
+**Must Have:** staleness visible in peripheral vision; stale value distinguishable from current value.
+**Anti-Pattern:** dynamic value with no age indication; "last update" in 8pt absolute timestamp.
+
+### H-7. Predictable navigation
+
+Navigation affordances (back, next, home) sit consistently across Canvases. Idle returns to the same idle Canvas every time.
+
+**Must Have:** back / next affordance positions verified across Canvases; idle reset produces identical idle Canvas every time.
+**Anti-Pattern:** back button at top-left on Canvas 2, bottom-right on Canvas 3; idle rotates such that the "anchor" element moves.
+
+## MEDIUM — impacts polish; prioritize by user impact
+
+### M-1. Instruction matches user mental model
+
+Action instructions ("Scan your code", "Tap to start", "Pay now") match the user's likely understanding; jargon avoided; language locale-matched.
+
+**Must Have:** wording reviewed for the actual audience; jargon removed.
+**Anti-Pattern:** "Initiate authentication sequence" on a public kiosk; English-only instruction on a multilingual venue.
+
+### M-2. Continuation is non-surprising
+
+The Canvas the user lands on after an action matches their expectation. Big jumps in journey context happen only with explicit transition.
+
+**Must Have:** continuation Canvas reviewed for context preservation; hero continuity in place.
+**Anti-Pattern:** success on Canvas A jumps to Canvas D mid-flow; user loses context.
+
+### M-3. Closure proportional to stakes
+
+Success closure hold time and visual weight match the action's stakes. Routine completions get brief acknowledgement; transact completions get held visible.
+
+**Must Have:** closure hold time tuned to action stakes; auto-advance only after enough time for the user to read.
+**Anti-Pattern:** 1.5s closure for a transact flow; 8s closure for a "saved to favorites" toast.
+
+### M-4. Density rhythm in browse / dwell
+
+For browse / dwell deployments, content rotation has variation in density / framing / colour rhythm across Canvases or slides. Three identical-rhythm Canvases in a row is a tell. (Cross-reference: `bricks-design/design-critique.md` density-rhythm collapse.)
+
+**Must Have:** rhythm variation across the sequence; no three identical-archetype Canvases in a row.
+**Anti-Pattern:** ten Canvases that all read as "headline + bullet list".
+
+### M-5. Audio cues calibrated (when hardware allows)
+
+If the deployment uses audio, volume / timing / time-of-day awareness is intentional.
+
+**Must Have:** audio volume / scheduling reviewed; success / alarm cues distinguishable from ambient.
+**Anti-Pattern:** constant-volume cues regardless of time; audio-only confirmation (no visual pair).
+
+### M-6. Reduced-motion path available (if relevant)
+
+For deployments in clinical / safety / motion-sensitive contexts, a reduced-motion path exists.
+
+**Must Have:** `reduceMotion` Data flag wired where applicable; verified reduced-motion preview.
+**Anti-Pattern:** continuous-motion design with no reduction path for a clinical deployment.
+
+## LOW — context-dependent
+
+### L-1. Polish on idle / attractor presence
+
+For deployments where idle dominates: idle is *inviting*, not just *running*.
+
+**Must Have for high-traffic public deployments:** attractor sequence engages from peripheral vision.
+**Anti-Pattern:** logo-only idle on a deployment whose purpose is to invite interaction.
+
+### L-2. Maintenance state designed
+
+If the deployment has scheduled downtime, a maintenance Canvas exists and distinguishes itself from error.
+
+**Must Have for deployments with maintenance windows:** maintenance Canvas with return path.
+**Anti-Pattern:** maintenance = black screen.
+
+### L-3. Empty-state composition
+
+Empty states explain the absence and suggest what populates.
+
+**Must Have:** empty state designed rather than collapsed-whitespace.
+**Anti-Pattern:** "—" or blank where content would be.
+
+## Tier-by-tier checklist (running order)
+
+Use this when running the pass:
+
+**CRITICAL (always run):**
+
+- [ ] User-journey spine whole (CR-1)
+- [ ] Transact intensified if applicable (CR-2)
+- [ ] Monitoring demand discipline if applicable (CR-3)
+- [ ] Accessibility floors met (CR-4)
+- [ ] Idle reset clean if applicable (CR-5)
+
+**HIGH (always run except for glance / dwell loops):**
+
+- [ ] Affordance unambiguous (H-1)
+- [ ] Press feedback at registration (H-2)
+- [ ] Flow states designed (H-3)
+- [ ] Hero continuity across Canvases (H-4)
+- [ ] Error recovery has a path (H-5)
+- [ ] Stale-data trust if applicable (H-6)
+- [ ] Predictable navigation (H-7)
+
+**MEDIUM (run for interact / transact / browse):**
+
+- [ ] Instruction matches mental model (M-1)
+- [ ] Continuation non-surprising (M-2)
+- [ ] Closure proportional (M-3)
+- [ ] Density rhythm (M-4)
+- [ ] Audio cues calibrated (M-5)
+- [ ] Reduced-motion path (M-6)
+
+**LOW (run for public-facing / high-dwell):**
+
+- [ ] Idle / attractor polish (L-1)
+- [ ] Maintenance state (L-2)
+- [ ] Empty-state composition (L-3)
+
+## Definition of UX done
+
+A flow is UX-done when:
+
+1. The CRITICAL tier passes — zero unaddressed CRITICAL items.
+2. The HIGH tier passes — zero unaddressed HIGH items (or surfaced as accepted trade-off with rationale).
+3. Applicable MEDIUM / LOW items either pass or are surfaced.
+4. Every state (golden path + error categories + idle + empty if relevant) has been verified via preview screenshot or Automation, and reviewed.
+5. Accessibility floors are met at the deployment-relative threshold, not at a desktop default.
+
+If any item is unmet, the work is mid-iteration. Say so explicitly to the user; offer a precise list of what remains.

package/tools/__tests__/_cli-error.test.ts

@@ -0,0 +1,35 @@
+import { extractCliErrorMessage } from '../_cli-error'
+
+// bricks-project's tsconfig has no @types/jest, so declare the globals this test
+// uses (mirrors tools/mcp-tools/__tests__/huggingface.test.ts).
+declare const describe: (name: string, fn: () => void) => void
+declare const it: (name: string, fn: () => void) => void
+declare const expect: (actual: unknown) => { toBe: (expected: unknown) => void }
+
+describe('extractCliErrorMessage', () => {
+  // Regression: the tools used to build this message inside the same try that
+  // wrapped JSON.parse, so the throw was caught by its own catch and replaced
+  // with the raw JSON blob. The human-readable message must survive.
+  it('extracts error.message from a JSON error body', () => {
+    const output = JSON.stringify({ error: { message: 'Conflict: config was modified' } })
+    expect(extractCliErrorMessage(output, 'Update failed')).toBe('Conflict: config was modified')
+  })
+
+  it('extracts a string error from a JSON error body', () => {
+    expect(extractCliErrorMessage('{"error":"Boom"}', 'Pull failed')).toBe('Boom')
+  })
+
+  it('returns the raw output when it is not JSON', () => {
+    expect(extractCliErrorMessage('plain text failure', 'Release failed')).toBe(
+      'plain text failure',
+    )
+  })
+
+  it('falls back to the raw output when the JSON has no error field', () => {
+    expect(extractCliErrorMessage('{"ok":true}', 'Update failed')).toBe('{"ok":true}')
+  })
+
+  it('falls back to the generic message when output is empty', () => {
+    expect(extractCliErrorMessage('', 'Update failed')).toBe('Update failed')
+  })
+})

package/tools/__tests__/_mcp-config.test.ts

@@ -0,0 +1,67 @@
+import { mkdtemp, readFile, writeFile, rm } from 'fs/promises'
+import { tmpdir } from 'os'
+import * as path from 'path'
+import { handleMcpConfigOverride } from '../_mcp-config'
+
+// bricks-project's tsconfig has no @types/jest, so declare the globals this test uses
+// (mirrors tools/__tests__/_cli-error.test.ts).
+declare const describe: (name: string, fn: () => void) => void
+declare const it: (name: string, fn: () => void | Promise<void>) => void
+declare const expect: (actual: unknown) => {
+  toBe: (expected: unknown) => void
+  toEqual: (expected: unknown) => void
+}
+
+const projectMcpServer = { command: 'bun', args: ['mcp-server.ts'] }
+
+const withTempMcp = async (contents: string | null, fn: (p: string) => Promise<void>) => {
+  const dir = await mkdtemp(path.join(tmpdir(), 'bf-mcp-'))
+  const mcpPath = path.join(dir, '.mcp.json')
+  if (contents !== null) await writeFile(mcpPath, contents)
+  try {
+    await fn(mcpPath)
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}
+
+describe('handleMcpConfigOverride', () => {
+  it('injects bricks-ctor while preserving the user other servers', async () => {
+    await withTempMcp(
+      JSON.stringify({ mcpServers: { smartbear: { command: 'npx' } } }),
+      async (p) => {
+        await handleMcpConfigOverride(p, projectMcpServer)
+        const result = JSON.parse(await readFile(p, 'utf-8'))
+        expect(result.mcpServers.smartbear).toEqual({ command: 'npx' })
+        expect(result.mcpServers['bricks-ctor']).toEqual(projectMcpServer)
+      },
+    )
+  })
+
+  it('does not clobber a malformed .mcp.json (regression: user servers were wiped)', async () => {
+    // trailing comma -> JSON.parse throws; the whole file used to be overwritten with the
+    // default, silently deleting every other configured server.
+    const malformed = '{ "mcpServers": { "smartbear": { "command": "npx" }, } }'
+    await withTempMcp(malformed, async (p) => {
+      await handleMcpConfigOverride(p, projectMcpServer)
+      expect(await readFile(p, 'utf-8')).toBe(malformed)
+    })
+  })
+
+  it('backfills mcpServers when missing without dropping other top-level keys', async () => {
+    await withTempMcp(JSON.stringify({ otherKey: 'keep-me' }), async (p) => {
+      await handleMcpConfigOverride(p, projectMcpServer)
+      const result = JSON.parse(await readFile(p, 'utf-8'))
+      expect(result.otherKey).toBe('keep-me')
+      expect(result.mcpServers['bricks-ctor']).toEqual(projectMcpServer)
+    })
+  })
+
+  it('writes a default config when no .mcp.json exists', async () => {
+    await withTempMcp(null, async (p) => {
+      await handleMcpConfigOverride(p, projectMcpServer)
+      const result = JSON.parse(await readFile(p, 'utf-8'))
+      expect(result.mcpServers['bricks-ctor']).toEqual(projectMcpServer)
+    })
+  })
+})

package/tools/__tests__/pull.test.ts

@@ -0,0 +1,108 @@
+import { execFile as execFileCallback } from 'node:child_process'
+import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { promisify } from 'node:util'
+
+// bricks-project's tsconfig has no @types/jest, so declare the globals this test uses
+// (mirrors tools/__tests__/_mcp-config.test.ts).
+declare const describe: (name: string, fn: () => void) => void
+declare const it: (name: string, fn: () => void | Promise<void>, timeout?: number) => void
+declare const expect: (actual: unknown) => {
+  toBe: (expected: unknown) => void
+}
+
+const execFile = promisify(execFileCallback)
+
+async function run(cmd: string, args: string[], cwd: string, env?: NodeJS.ProcessEnv) {
+  return execFile(cmd, args, {
+    cwd,
+    env: { ...process.env, ...env },
+    maxBuffer: 1024 * 1024,
+  })
+}
+
+async function initGitProject(projectDir: string) {
+  await run('git', ['init', '--initial-branch=master'], projectDir)
+  await run('git', ['config', 'user.email', 'test@example.com'], projectDir)
+  await run('git', ['config', 'user.name', 'Test User'], projectDir)
+  await writeFile(join(projectDir, 'application.json'), JSON.stringify({ id: 'app-1' }))
+  await run('git', ['add', '.'], projectDir)
+  await run('git', ['commit', '-m', 'init'], projectDir)
+}
+
+async function writeFakeBricks(binDir: string) {
+  const payload = {
+    files: [
+      {
+        name: 'subspaces/subspace-13/data-calc/data-calculation-0.sandbox.js',
+        input: 'export const value = 1\n',
+        formatable: false,
+      },
+    ],
+    lastCommitId: 'server-commit',
+  }
+  const bricksPath = join(binDir, 'bricks')
+  await writeFile(
+    bricksPath,
+    `#!/usr/bin/env node\nprocess.stdout.write(${JSON.stringify(JSON.stringify(payload))})\n`,
+  )
+  await chmod(bricksPath, 0o755)
+}
+
+describe('pull.ts', () => {
+  it('creates parent directories before writing pulled project files', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'bricks-project-pull-'))
+    const projectDir = join(root, 'project')
+    const binDir = join(root, 'bin')
+
+    try {
+      await mkdir(projectDir)
+      await mkdir(binDir)
+      await initGitProject(projectDir)
+      await writeFakeBricks(binDir)
+
+      const pullScript = resolve(__dirname, '../pull.ts')
+      await run('bun', [pullScript, '--force'], projectDir, {
+        PATH: `${binDir}:${process.env.PATH || ''}`,
+      })
+
+      const pulledFile = join(
+        projectDir,
+        'subspaces/subspace-13/data-calc/data-calculation-0.sandbox.js',
+      )
+      expect(await readFile(pulledFile, 'utf8')).toBe('export const value = 1\n')
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  }, 30000)
+
+  it('merges pulled project files back into the starting branch', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'bricks-project-pull-'))
+    const projectDir = join(root, 'project')
+    const binDir = join(root, 'bin')
+
+    try {
+      await mkdir(projectDir)
+      await mkdir(binDir)
+      await initGitProject(projectDir)
+      await writeFakeBricks(binDir)
+
+      const pullScript = resolve(__dirname, '../pull.ts')
+      await run('bun', [pullScript], projectDir, {
+        PATH: `${binDir}:${process.env.PATH || ''}`,
+      })
+
+      const { stdout: branch } = await run('git', ['branch', '--show-current'], projectDir)
+      const pulledFile = join(
+        projectDir,
+        'subspaces/subspace-13/data-calc/data-calculation-0.sandbox.js',
+      )
+
+      expect(branch.trim()).toBe('master')
+      expect(await readFile(pulledFile, 'utf8')).toBe('export const value = 1\n')
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  }, 30000)
+})

package/tools/_cli-error.ts

@@ -0,0 +1,17 @@
+// Extract a human-readable message from a `bricks ... --json` failure payload.
+//
+// On failure the CLI prints `{ "error": { "message": "..." } }` (or the older
+// `{ "error": "..." }`) to stdout/stderr. Earlier call sites built that message
+// inside the same `try` that wrapped `JSON.parse`, so the `throw` was caught by
+// its own `catch` and replaced with the raw JSON blob — the human-readable
+// message never surfaced. Parsing here, outside any throw, avoids that trap.
+export function extractCliErrorMessage(output: string, fallback: string): string {
+  try {
+    const { error } = JSON.parse(output)
+    const message = error?.message ?? error
+    if (typeof message === 'string' && message) return message
+  } catch {
+    // output is not JSON — fall through to the raw output below
+  }
+  return output || fallback
+}

package/tools/_edits-log.ts

@@ -0,0 +1,41 @@
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+const auditLogIgnoreEntry = '.bricks/edits.jsonl'
+
+// Ensure the project's .gitignore excludes the audit log. No-op when it is already
+// ignored directly or via a broader `.bricks` rule.
+const ensureAuditLogIgnored = async (projectDir: string) => {
+  const gitignorePath = path.join(projectDir, '.gitignore')
+  const content = await readFile(gitignorePath, 'utf8').catch((err: any) => {
+    if (err?.code === 'ENOENT') return ''
+    throw err
+  })
+  const ignored = content
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .some((line) => line === auditLogIgnoreEntry || line === '.bricks/' || line === '.bricks')
+  if (ignored) return
+
+  const prefix = content && !content.endsWith('\n') ? '\n' : ''
+  await writeFile(
+    gitignorePath,
+    `${content}${prefix}\n# MCP entry-editing audit log\n${auditLogIgnoreEntry}\n`,
+  )
+}
+
+// Append one JSON record to `.bricks/edits.jsonl`, creating the directory and the
+// gitignore entry as needed. Shared by the source-editing tools and `compile()` so
+// every project mutation lands in the same audit log.
+export const appendEditRecord = async (projectDir: string, record: Record<string, unknown>) => {
+  const bricksDir = path.join(projectDir, '.bricks')
+  await mkdir(bricksDir, { recursive: true })
+  await ensureAuditLogIgnored(projectDir)
+  await appendFile(path.join(bricksDir, 'edits.jsonl'), `${JSON.stringify(record)}\n`)
+}
+
+// Provenance stamped on every audit record: which agent/session produced the change.
+export const editProvenance = () => ({
+  session: process.env.BRICKS_CTOR_SESSION_ID || process.env.CODEX_SESSION_ID,
+  agent: process.env.BRICKS_CTOR_AGENT_ID || process.env.USER,
+})

package/tools/_git-author.ts

@@ -15,7 +15,15 @@ async function hasGitIdentity(cwd: string): Promise<boolean> {
 // If no identity is configured (typical for non-tech users), CTOR becomes the
 // main author via per-command `-c user.name/-c user.email` overrides so the
 // user's git config is left untouched.
-export async function buildCommitArgs(cwd: string, messages: string[]): Promise<string[]> {
+//
+// `extraFlags` are inserted between `commit` and the `-m` args (e.g.
+// `['--no-verify']` to bypass pre-commit hooks for controlled cases like
+// committing merge-conflict markers).
+export async function buildCommitArgs(
+  cwd: string,
+  messages: string[],
+  extraFlags: string[] = [],
+): Promise<string[]> {
   const hasIdentity = await hasGitIdentity(cwd)
   const prefix = hasIdentity
     ? []
@@ -23,7 +31,7 @@ export async function buildCommitArgs(cwd: string, messages: string[]): Promise<
   const msgArgs: string[] = []
   for (const m of messages) msgArgs.push('-m', m)
   if (hasIdentity) msgArgs.push('-m', CTOR_COAUTHOR_TRAILER)
-  return [...prefix, 'commit', ...msgArgs]
+  return [...prefix, 'commit', ...extraFlags, ...msgArgs]
 }
 
 export { CTOR_NAME, CTOR_EMAIL, CTOR_COAUTHOR_TRAILER }

package/tools/_last-pushed-commit.ts

@@ -0,0 +1,28 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+
+// Local sync marker: the git commit hash that was on HEAD when we last
+// successfully pushed to the server (deploy or push-config) or pulled
+// from it. Stored at the `.bricks/` top level (gitignored explicitly) — it's
+// per-clone state, not a build artifact, so it doesn't belong under
+// `.bricks/build/`.
+//
+// Why this exists: server's `bricks_project_last_commit_id` can be an opaque
+// nanoid for content-only edits (config-editor saves), so it isn't a
+// reliable git anchor for `git checkout` during pull. The local marker is
+// always a real reachable commit hash from THIS clone.
+const REL_PATH = '.bricks/.last-pushed-commit'
+
+export async function readLastPushedCommit(cwd: string): Promise<string | null> {
+  try {
+    const content = await readFile(`${cwd}/${REL_PATH}`, 'utf8')
+    return content.trim() || null
+  } catch {
+    return null
+  }
+}
+
+export async function writeLastPushedCommit(cwd: string, commitId: string): Promise<void> {
+  if (!commitId) return
+  await mkdir(`${cwd}/.bricks`, { recursive: true })
+  await writeFile(`${cwd}/${REL_PATH}`, commitId)
+}

package/tools/_mcp-config.ts

@@ -0,0 +1,42 @@
+import { readFile, writeFile, stat } from 'fs/promises'
+
+const exists = async (f: string) => {
+  try {
+    await stat(f)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Refresh the `bricks-ctor` entry in a project's `.mcp.json` while preserving every other MCP
+// server the user configured. A malformed `.mcp.json` is left untouched (with a warning)
+// rather than overwritten with the default — clobbering it would silently delete the user's
+// other server entries. This mirrors `setupClaudeAutoMode`'s handling of a malformed
+// `settings.local.json` in postinstall.ts.
+export const handleMcpConfigOverride = async (mcpConfigPath: string, projectMcpServer: object) => {
+  let mcpConfig: { mcpServers: Record<string, unknown> }
+  if (await exists(mcpConfigPath)) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(await readFile(mcpConfigPath, 'utf-8'))
+    } catch {
+      console.warn(`Skipping .mcp.json update; ${mcpConfigPath} is not valid JSON`)
+      return
+    }
+    mcpConfig =
+      parsed && typeof parsed === 'object'
+        ? (parsed as { mcpServers: Record<string, unknown> })
+        : { mcpServers: {} }
+    if (!mcpConfig.mcpServers || typeof mcpConfig.mcpServers !== 'object') {
+      mcpConfig.mcpServers = {}
+    }
+    mcpConfig.mcpServers['bricks-ctor'] = projectMcpServer
+    delete mcpConfig.mcpServers['bricks-project']
+  } else {
+    mcpConfig = { mcpServers: { 'bricks-ctor': projectMcpServer } }
+  }
+
+  await writeFile(mcpConfigPath, `${JSON.stringify(mcpConfig, null, 2)}\n`)
+  console.log(`Updated ${mcpConfigPath}`)
+}

package/tools/_shell.ts

@@ -29,6 +29,7 @@ class Sh implements PromiseLike<ShResult> {
   private _cwd: string | undefined
   private _mode: Mode = 'default'
   private _throw = true
+  private _env: NodeJS.ProcessEnv | undefined
   private _promise: Promise<ShResult> | null = null
 
   constructor(private readonly args: string[]) {}
@@ -48,6 +49,11 @@ class Sh implements PromiseLike<ShResult> {
     return this
   }
 
+  env(extra: NodeJS.ProcessEnv): this {
+    this._env = { ...this._env, ...extra }
+    return this
+  }
+
   async text(): Promise<string> {
     // If no explicit quiet was requested, capture stdout/stderr without
     // forwarding them to the parent's streams (matches Bun's `.text()`).
@@ -79,7 +85,8 @@ class Sh implements PromiseLike<ShResult> {
           ? ['ignore', 'pipe', 'pipe']
           : ['inherit', 'pipe', 'pipe']
 
-    const proc = spawn(cmd, rest, { cwd: this._cwd, stdio })
+    const env = this._env ? { ...process.env, ...this._env } : undefined
+    const proc = spawn(cmd, rest, { cwd: this._cwd, stdio, env })
 
     const outChunks: Buffer[] = []
     const errChunks: Buffer[] = []