@xulthekl/team-flow 0.22.4

package/skills/ce-brainstorm/scripts/visual-probe-server.js

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+import { execFileSync, spawn } from "node:child_process"
+import fs from "node:fs"
+import http from "node:http"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const scriptPath = fileURLToPath(import.meta.url)
+const DEFAULT_HOST = "127.0.0.1"
+const DEFAULT_URL_HOST = "localhost"
+const IDLE_TIMEOUT_MS = Number(process.env.CE_VISUAL_PROBE_IDLE_TIMEOUT_MS) || 30 * 60 * 1000
+const LIFECYCLE_CHECK_MS = Number(process.env.CE_VISUAL_PROBE_LIFECYCLE_CHECK_MS) || 60 * 1000
+
+function usage() {
+  return [
+    "Usage:",
+    "  node visual-probe-server.js start --root <dir> [--host 127.0.0.1] [--port 0] [--foreground] [--owner-pid <pid>]",
+    "  node visual-probe-server.js stop --root <dir>",
+    "  node visual-probe-server.js status --root <dir>",
+  ].join("\n")
+}
+
+function parseArgs(argv) {
+  const command = argv[2]
+  const options = {
+    command,
+    host: DEFAULT_HOST,
+    port: 0,
+    foreground: false,
+  }
+
+  for (let i = 3; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === "--root") {
+      options.root = argv[++i]
+    } else if (arg === "--host") {
+      options.host = argv[++i]
+    } else if (arg === "--port") {
+      options.port = Number(argv[++i])
+    } else if (arg === "--foreground") {
+      options.foreground = true
+    } else if (arg === "--owner-pid") {
+      options.ownerPid = Number(argv[++i])
+    } else {
+      throw new Error(`Unknown argument: ${arg}`)
+    }
+  }
+
+  if (!["start", "serve", "stop", "status"].includes(command)) {
+    throw new Error(usage())
+  }
+  if (!options.root) {
+    throw new Error("--root is required")
+  }
+  if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
+    throw new Error("--port must be an integer from 0 to 65535")
+  }
+  if (options.ownerPid !== undefined && (!Number.isInteger(options.ownerPid) || options.ownerPid <= 1)) {
+    throw new Error("--owner-pid must be an integer greater than 1")
+  }
+
+  options.root = path.resolve(options.root)
+  options.screensDir = path.join(options.root, "screens")
+  options.stateDir = path.join(options.root, "state")
+  options.pidFile = path.join(options.stateDir, "server.pid")
+  options.infoFile = path.join(options.stateDir, "display-info.json")
+  options.logFile = path.join(options.stateDir, "server.log")
+  return options
+}
+
+function ensureDirs(options) {
+  fs.mkdirSync(options.screensDir, { recursive: true })
+  fs.mkdirSync(options.stateDir, { recursive: true })
+}
+
+function jsonOut(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`)
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"))
+}
+
+function processAlive(pid) {
+  if (!pid || !Number.isInteger(pid)) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error?.code === "EPERM"
+  }
+}
+
+function processArgs(pid) {
+  try {
+    return execFileSync("ps", ["-p", String(pid), "-o", "args="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim()
+  } catch {
+    return null
+  }
+}
+
+function ownsServerProcess(options, pid) {
+  const args = processArgs(pid)
+  // Process-command inspection is best-effort; when unavailable, fall back to
+  // PID-file behavior so stop still works on platforms without a compatible ps.
+  if (args === null) return true
+  return args.includes(scriptPath) && args.includes("serve") && args.includes(options.root)
+}
+
+function resolveOwnerPid() {
+  const parentPid = process.ppid
+  if (!parentPid || parentPid <= 1) return null
+  try {
+    const grandparent = Number(execFileSync("ps", ["-o", "ppid=", "-p", String(parentPid)], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim())
+    if (Number.isInteger(grandparent) && grandparent > 1) return grandparent
+  } catch {
+    // Fall back to the direct parent when grandparent lookup is unavailable.
+  }
+  return parentPid
+}
+
+function readPid(options) {
+  if (!fs.existsSync(options.pidFile)) return null
+  const pid = Number(fs.readFileSync(options.pidFile, "utf8").trim())
+  return Number.isInteger(pid) ? pid : null
+}
+
+function getRunningInfo(options) {
+  const pid = readPid(options)
+  if (!processAlive(pid)) return null
+  if (!ownsServerProcess(options, pid)) return null
+  if (!fs.existsSync(options.infoFile)) return null
+  return readJson(options.infoFile)
+}
+
+function newestScreen(options) {
+  if (!fs.existsSync(options.screensDir)) return null
+  const files = fs.readdirSync(options.screensDir)
+    .filter((file) => file.endsWith(".html"))
+    .map((file) => {
+      const filePath = path.join(options.screensDir, file)
+      return { filePath, mtimeMs: fs.statSync(filePath).mtimeMs }
+    })
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+  return files[0]?.filePath ?? null
+}
+
+function isFullDocument(html) {
+  const trimmed = html.trimStart().toLowerCase()
+  return trimmed.startsWith("<!doctype") || trimmed.startsWith("<html")
+}
+
+function screenVersion(options) {
+  const screen = newestScreen(options)
+  if (!screen) return { screen: null, mtimeMs: 0 }
+  return {
+    screen: path.basename(screen),
+    mtimeMs: fs.statSync(screen).mtimeMs,
+  }
+}
+
+function refreshScript(options) {
+  const initialVersion = JSON.stringify(screenVersion(options))
+  return `<script>
+(function(){
+  var currentVersion = ${initialVersion};
+  function key(version) {
+    return String(version && version.screen) + ":" + String(version && version.mtimeMs);
+  }
+  async function checkForVisualProbeUpdate() {
+    try {
+      var response = await fetch("/version", { cache: "no-store" });
+      if (!response.ok) return;
+      var nextVersion = await response.json();
+      if (key(nextVersion) !== key(currentVersion)) {
+        window.location.reload();
+      }
+    } catch (error) {
+      // Keep the current sketch visible if the transient version check fails.
+    }
+  }
+  setInterval(checkForVisualProbeUpdate, 1000);
+})();
+</script>`
+}
+
+function wrapFragment(options, content) {
+  return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>CE Brainstorm Visual Probe</title>
+  <style>
+    body { margin: 0; font-family: system-ui, -apple-system, BlinkMacSystemFont, sans-serif; background: #f7f7f8; color: #1f2328; }
+    header { padding: 10px 18px; border-bottom: 1px solid #d8dee4; background: #fff; color: #57606a; font-size: 13px; }
+    main { padding: 24px; }
+  </style>
+</head>
+<body>
+  <header>CE Brainstorm Visual Probe - directional sketch, reply in chat</header>
+  <main>${content}</main>
+  ${refreshScript(options)}
+</body>
+</html>`
+}
+
+function injectRefresh(options, html) {
+  if (html.includes("</body>")) {
+    return html.replace("</body>", `${refreshScript(options)}\n</body>`)
+  }
+  return `${html}\n${refreshScript(options)}`
+}
+
+function renderPage(options) {
+  const screen = newestScreen(options)
+  if (!screen) {
+    return wrapFragment(options, "<h1>Waiting for a visual probe...</h1><p>The agent will update this page when a sketch is ready.</p>")
+  }
+  const html = fs.readFileSync(screen, "utf8")
+  return isFullDocument(html) ? injectRefresh(options, html) : wrapFragment(options, html)
+}
+
+function safeFileResponse(options, req, res) {
+  const name = decodeURIComponent(req.url.slice("/files/".length))
+  const filePath = path.join(options.screensDir, path.basename(name))
+  if (!fs.existsSync(filePath)) {
+    res.writeHead(404)
+    res.end("Not found")
+    return
+  }
+  res.writeHead(200, { "Content-Type": contentType(filePath) })
+  res.end(fs.readFileSync(filePath))
+}
+
+function contentType(filePath) {
+  const ext = path.extname(filePath).toLowerCase()
+  if (ext === ".svg") return "image/svg+xml"
+  if (ext === ".png") return "image/png"
+  if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg"
+  if (ext === ".gif") return "image/gif"
+  if (ext === ".html") return "text/html; charset=utf-8"
+  if (ext === ".css") return "text/css; charset=utf-8"
+  if (ext === ".js") return "text/javascript; charset=utf-8"
+  return "application/octet-stream"
+}
+
+async function start(options) {
+  ensureDirs(options)
+  options.ownerPid = options.ownerPid ?? resolveOwnerPid()
+  const running = getRunningInfo(options)
+  if (running) {
+    jsonOut({ ...running, status: "running" })
+    return
+  }
+
+  fs.rmSync(options.pidFile, { force: true })
+  fs.rmSync(options.infoFile, { force: true })
+
+  if (options.foreground) {
+    await serve(options)
+    return
+  }
+
+  const logFd = fs.openSync(options.logFile, "a")
+  const child = spawn(process.execPath, [
+    scriptPath,
+    "serve",
+    "--root",
+    options.root,
+    "--host",
+    options.host,
+    "--port",
+    String(options.port),
+    ...(options.ownerPid ? ["--owner-pid", String(options.ownerPid)] : []),
+  ], {
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+  })
+  child.unref()
+  fs.closeSync(logFd)
+
+  const started = await waitForInfo(options, child.pid)
+  if (!started) {
+    throw new Error(`Server failed to start. See ${options.logFile}`)
+  }
+  jsonOut({ ...started, status: "started" })
+}
+
+async function waitForInfo(options, pid) {
+  for (let i = 0; i < 100; i++) {
+    if (fs.existsSync(options.infoFile)) return readJson(options.infoFile)
+    if (pid && !processAlive(pid)) return null
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+  return null
+}
+
+async function serve(options) {
+  ensureDirs(options)
+
+  let lastActivity = Date.now()
+  const touch = () => {
+    lastActivity = Date.now()
+  }
+
+  const server = http.createServer((req, res) => {
+    if (req.method === "GET" && req.url === "/") {
+      touch()
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
+      res.end(renderPage(options))
+      return
+    }
+    if (req.method === "GET" && req.url === "/version") {
+      res.writeHead(200, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store",
+      })
+      res.end(`${JSON.stringify(screenVersion(options))}\n`)
+      return
+    }
+    if (req.method === "GET" && req.url.startsWith("/files/")) {
+      touch()
+      safeFileResponse(options, req, res)
+      return
+    }
+    res.writeHead(404)
+    res.end("Not found")
+  })
+
+  server.listen(options.port, options.host, () => {
+    const address = server.address()
+    const port = typeof address === "object" && address ? address.port : options.port
+    const info = {
+      status: "running",
+      root: options.root,
+      host: options.host,
+      port,
+      url: `http://${DEFAULT_URL_HOST}:${port}`,
+      screen_dir: options.screensDir,
+      state_dir: options.stateDir,
+      pid: process.pid,
+      owner_pid: options.ownerPid ?? null,
+    }
+    fs.writeFileSync(options.pidFile, `${process.pid}\n`)
+    fs.writeFileSync(options.infoFile, `${JSON.stringify(info, null, 2)}\n`)
+    console.log(JSON.stringify(info))
+  })
+
+  const idleTimer = setInterval(() => {
+    if (options.ownerPid && !processAlive(options.ownerPid)) {
+      server.close(() => process.exit(0))
+    } else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) {
+      server.close(() => process.exit(0))
+    }
+  }, LIFECYCLE_CHECK_MS)
+  idleTimer.unref()
+}
+
+async function stop(options) {
+  const pid = readPid(options)
+  if (!processAlive(pid)) {
+    fs.rmSync(options.pidFile, { force: true })
+    jsonOut({ status: "stopped", root: options.root })
+    return
+  }
+  if (!ownsServerProcess(options, pid)) {
+    fs.rmSync(options.pidFile, { force: true })
+    jsonOut({ status: "stopped", root: options.root })
+    return
+  }
+
+  process.kill(pid)
+  for (let i = 0; i < 20; i++) {
+    if (!processAlive(pid)) break
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+  if (processAlive(pid)) {
+    try {
+      process.kill(pid, "SIGKILL")
+    } catch {
+      // Process may have exited between the liveness check and kill.
+    }
+  }
+
+  fs.rmSync(options.pidFile, { force: true })
+  jsonOut({ status: "stopped", root: options.root })
+}
+
+function status(options) {
+  const info = getRunningInfo(options)
+  if (!info) {
+    jsonOut({ status: "stopped", root: options.root })
+    return
+  }
+  jsonOut({ ...info, status: "running" })
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv)
+    if (options.command === "start") await start(options)
+    else if (options.command === "serve") await serve(options)
+    else if (options.command === "stop") await stop(options)
+    else if (options.command === "status") status(options)
+  } catch (error) {
+    console.error(error.message)
+    process.exit(1)
+  }
+}
+
+await main()

package/skills/ce-compound/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: ce-compound
+description: Document a recently solved problem or durable project vocabulary in docs/solutions/ or CONCEPTS.md. Use when capturing a learning after work.
+argument-hint: "[optional: brief context] [mode:headless] [depth:lightweight|full]"
+---
+
+# /ce-compound
+
+Coordinate multiple subagents working in parallel to document a recently solved problem.
+
+See `references/v0.5-upgrade.md` for the v0.5 复利贯穿引擎 upgrade details and auto-invoke scenarios.
+
+## Purpose
+
+Capture problem solutions while context is fresh, creating structured documentation in `docs/solutions/` with YAML frontmatter. Each documented solution compounds your team's knowledge — the first fix takes research; document it, and the next occurrence takes minutes. See `references/three-tier-index.md` for the three-tier index architecture. See `references/write-flow.md` for write flow and eviction rules. See `references/promotion-rules.md` for change→product promotion rules.
+
+## When to Use
+
+```bash
+/ce-compound                            # Document the most recent fix
+/ce-compound [brief context]            # Provide additional context hint
+/ce-compound mode:headless              # Non-interactive run for automations
+/ce-compound mode:headless depth:lightweight [context]
+/ce-compound mode:headless depth:full [context]
+```
+
+**One learning per run.** Run the skill once per learning, sequentially. Do not batch several learnings through one run.
+
+If invoked to bootstrap `CONCEPTS.md` from scratch, redirect to `ce-compound-refresh` and exit.
+
+## Mode Detection
+
+Enter headless mode when the arguments contain `mode:headless`, or the invocation makes non-interactive intent unmistakable. `depth:lightweight` routes to Lightweight Mode; `depth:full` or no depth token routes to Full Mode. Strip `mode:` and `depth:` tokens before treating the remainder as context.
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **Interactive** (default) | No headless signal | Auto-pick Full vs Lightweight; prompt for Discoverability Check consent; end with plain summary |
+| **Headless** | `mode:headless` or clear non-interactive intent | No blocking questions; default to Full; report gaps without editing instruction files; structured terminal report |
+
+**Mode selection (Full vs Lightweight) — decide it, don't ask it.** Default to Full. Choose Lightweight only under real context pressure. State the chosen mode in the first line of output.
+
+## Session Context
+
+Before Phase 1, resolve: **Git branch** (`git rev-parse --abbrev-ref HEAD`) and **Repo root** (`git rev-parse --show-toplevel`). Non-zero exits are normal — skip branch filtering or fall back to working directory.
+
+## Support Files
+
+Read on-demand at the step that needs them — do not bulk-load at skill start.
+
+- `references/schema.yaml` — canonical frontmatter fields and enum values
+- `references/yaml-schema.md` — category mapping from problem_type to directory
+- `references/concepts-vocabulary.md` — CONCEPTS.md format and inclusion rules
+- `references/grounding-validation.md` — flag adjudication rules and semantic validator prompt
+- `references/agents/session-historian.md` — session-history synthesis prompt
+- `references/v0.5-upgrade.md` — v0.5 upgrade table and auto-invoke scenarios
+- `references/three-tier-index.md` — three-tier index architecture and file format
+- `references/write-flow.md` — write flow, eviction rules, CLI commands
+- `references/promotion-rules.md` — promotion check rules (change→product)
+- `references/full-mode-workflow.md` — **Full Mode detailed phases (0.5→1→2→2.4→2.45→2.5→Discoverability→3)**
+- `references/lightweight-mode.md` — **Lightweight Mode detailed steps**
+- `references/output-standards.md` — success output formats, categories, common mistakes, specialized prompts
+- `assets/resolution-template.md` — section structure for new docs
+- `scripts/session-history/` — session discovery and extraction scripts
+- `scripts/validate-frontmatter.py` — frontmatter parser-safety validator
+- `scripts/validate-doc-claims.py` — mechanical claims validator
+
+When spawning subagents, pass the relevant file contents into the task prompt.
+
+## Core Workflow
+
+**Read `references/full-mode-workflow.md` (Full) or `references/lightweight-mode.md` (Lightweight) before executing.** The steps below are the imperative summary; the references contain the complete operational detail.
+
+### Full Mode
+
+1. **Phase 0.5 — Auto Memory Scan**: Check auto-memory block for relevant notes; pass as supplementary context.
+2. **Phase 1 — Research**: Generate run dir. Launch Context Analyzer, Solution Extractor, Related Docs Finder in parallel. Then run session-history probe (automatic, two-stage: cheap discovery always runs; expensive synthesis only on relevance hit). Each subagent writes to `{run_dir}/` artifact and returns only the path.
+3. **Phase 2 — Assembly & Write**: Wait for all Phase 1 inputs. Collect artifacts. Check overlap (high→update existing, moderate/low→create new). Incorporate session history. Assemble doc from `assets/resolution-template.md`. Validate YAML frontmatter. Write file. Run `scripts/validate-frontmatter.py`.
+4. **Phase 2.4 — Vocabulary Capture**: Read `references/concepts-vocabulary.md`. Scan for qualifying domain terms. Create/update `CONCEPTS.md` silently.
+5. **Phase 2.45 — Grounding Validation**: Run `scripts/validate-doc-claims.py` (mechanical). Dispatch semantic grounding validator subagent (Full only). Adjudicate flags per `references/grounding-validation.md`.
+6. **Phase 2.5 — Selective Refresh Check**: Decide whether to invoke/recommend `ce-compound-refresh` with narrow scope. Never a default follow-up.
+7. **Discoverability Check**: Assess whether instruction files surface `docs/solutions/` (and `CONCEPTS.md` if it exists). Interactive Full: edit after consent. Headless: report gap only.
+8. **Phase 3 — Optional Enhancement**: Dispatch specialized reviewers by problem type (skip in headless). See `references/output-standards.md` for prompt list.
+
+### Lightweight Mode
+
+Single-pass, no subagents. Read `references/lightweight-mode.md` for the full 8-step sequence: extract → classify → write minimal doc → vocabulary capture (update-only) → read-only discoverability → mechanical claims check → frontmatter check → skip Phase 3.
+
+## Guardrails
+
+- **One deliverable**: `docs/solutions/[category]/[filename].md`. Subagents write only scratch artifacts under `<run-dir>/`; only the orchestrator writes product files.
+- **Ground claims in source**: Read the defining line before asserting code behavior. Cite PR numbers over SHAs. Soften unverifiable claims.
+- **Overlap before create**: High overlap → update existing doc. Do not create duplicates.
+- **Headless never edits instruction files**: Report gaps; do not apply edits.
+- **No "What's next?" menu**: End the turn after the summary.
+
+## Preconditions
+
+Problem has been solved (not in-progress). Solution has been verified working. Non-trivial problem (not simple typo or obvious error).
+
+## Output
+
+See `references/output-standards.md` for complete output formats (headless lightweight, headless full, interactive, failure), categories, common mistakes table, and the compounding philosophy.
+
+**Headless**: structured terminal report ending with `Documentation complete` (or `Documentation skipped`).
+**Interactive**: subagent results, grounding validation, files written, refresh recommendation. End the turn.
+
+## Auto-Invoke
+
+Trigger phrases: "that worked", "it's fixed", "working now", "problem solved". Manual override: `/ce-compound [context]`.
+
+## Related Commands
+
+- `/research [topic]` — deep investigation (searches docs/solutions/ for patterns)
+- `/ce-plan` — planning workflow (references documented solutions)

package/skills/ce-compound/assets/resolution-template.md

@@ -0,0 +1,94 @@
+# Resolution Templates
+
+Choose the template matching the problem_type track (see `references/schema.yaml`).
+
+---
+
+## Bug Track Template
+
+Use for: `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error`
+
+<!-- YAML safety: array items (symptoms, applies_when, tags, related_components) starting with ` [ * & ! | > % @ ? or containing ": " must be wrapped in double quotes. See references/yaml-schema.md > "YAML Safety Rules". -->
+
+```markdown
+---
+title: [Clear problem title]
+date: [YYYY-MM-DD]
+category: [docs/solutions subdirectory]
+module: [Module or area]
+problem_type: [schema enum]
+component: [schema enum]
+symptoms:
+  - [Observable symptom 1]
+root_cause: [schema enum]
+resolution_type: [schema enum]
+severity: [schema enum]
+tags: [keyword-one, keyword-two]
+---
+
+# [Clear problem title]
+
+## Problem
+[1-2 sentence description of the issue and user-visible impact]
+
+## Symptoms
+- [Observable symptom or error]
+
+## What Didn't Work
+- [Attempted fix and why it failed]
+
+## Solution
+[The fix that worked, including code snippets when useful]
+
+## Why This Works
+[Root cause explanation and why the fix addresses it]
+
+## Prevention
+- [Concrete practice, test, or guardrail]
+
+## Related Issues
+- [Related docs or issues, if any]
+```
+
+---
+
+## Knowledge Track Template
+
+Use for: `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`
+
+<!-- YAML safety: array items (symptoms, applies_when, tags, related_components) starting with ` [ * & ! | > % @ ? or containing ": " must be wrapped in double quotes. See references/yaml-schema.md > "YAML Safety Rules". -->
+
+```markdown
+---
+title: [Clear, descriptive title]
+date: [YYYY-MM-DD]
+category: [docs/solutions subdirectory]
+module: [Module or area]
+problem_type: [schema enum]
+component: [schema enum]
+severity: [schema enum]
+applies_when:
+  - [Condition where this applies]
+tags: [keyword-one, keyword-two]
+---
+
+# [Clear, descriptive title]
+
+## Context
+[What situation, gap, or friction prompted this guidance]
+
+## Guidance
+[The practice, pattern, or recommendation with code examples when useful]
+
+## Why This Matters
+[Rationale and impact of following or not following this guidance]
+
+## When to Apply
+- [Conditions or situations where this applies]
+
+## Examples
+[Concrete before/after or usage examples showing the practice in action]
+
+## Related
+- [Related docs or issues, if any]
+```