@haposoft/cafekit 0.8.12 → 0.8.14

package/src/claude/skills/docs/references/update-workflow.md

@@ -0,0 +1,123 @@
+# Update Workflow
+
+Use with `/hapo:docs update`.
+
+## Goal
+
+Refresh existing living docs after code or project-state changes without rewriting docs that are already accurate.
+
+## Inputs
+
+- docs root from `.claude/runtime.json` (`paths.docs`, default `docs`)
+- existing docs under that root
+- recent source changes when git context is available
+- relevant source code, tests, schemas, config, CI, deploy files
+- any additional user focus in the prompt
+
+## Workflow
+
+### Phase 0: Preflight
+
+1. Read repo instructions and docs root.
+2. Verify the docs root exists.
+3. If the docs root does not exist, switch to `init` or explain that no docs baseline exists.
+4. Identify update focus:
+   - user-named module or doc
+   - recent source diff
+   - docs-sync stale hash signal
+   - a full docs refresh only when user asks for it
+
+### Phase 1: Source Change Scout
+
+Scout source areas that can affect docs:
+
+1. Compare git change context when available.
+2. Map changed files to affected topics:
+   - product capability/PDR
+   - architecture or module boundaries
+   - commands/config/deployment
+   - design/code standards
+   - roadmap/changelog state
+3. Run targeted source reads for evidence.
+4. Use `hapo:inspect` only when the affected scope is unclear or broad.
+
+Do not treat commit messages as sufficient evidence. Verify changed behavior in code, tests, config, or schemas.
+
+### Phase 1.5: Existing Docs Read
+
+Read existing docs before edits.
+
+Use document count and file size to decide reading strategy:
+
+| Docs set | Reading strategy |
+|---|---|
+| 1-3 markdown files | Read directly |
+| 4-6 markdown files | Split across 2-3 readers when delegation is available |
+| 7+ markdown files | Split across up to 5 readers by LOC and topic |
+
+Each reading pass extracts:
+
+- document purpose
+- claims that may be affected
+- related cross-links
+- stale or contradictory sections
+- unresolved questions already present
+
+Merge source scout and docs readings before writing.
+
+### Phase 2: Surgical Docs Update
+
+Delegate to `docs-keeper` when available. The update must stay surgical:
+
+1. Edit only affected docs and sections.
+2. Remove or rewrite stale claims when source evidence contradicts docs.
+3. Preserve useful human-written context not contradicted by evidence.
+4. Add new links only after verifying targets.
+5. Record remaining unknowns instead of inventing migration guidance or architecture.
+
+Common update targets:
+
+| File | Update when |
+|---|---|
+| `README.md` | setup, usage, command entry points changed |
+| `project-overview-pdr.md` | actors, capabilities, constraints, status changed |
+| `codebase-summary.md` | structure, stack, runtime map changed |
+| `code-standards.md` | real conventions or required commands changed |
+| `system-architecture.md` | components, data flow, integrations, deployment changed |
+| `deployment-guide.md` | build/deploy/env/config changed |
+| `design-guidelines.md` | design system or UI conventions changed |
+| `project-roadmap.md` | milestone/project state changed |
+
+### Phase 3: Size Check
+
+1. Check docs LOC after updates.
+2. Use `docs.maxLoc` when provided; default to 800.
+3. Split large documents on semantic boundaries if this update pushes them over the limit.
+4. Report oversized docs left unchanged when splitting is outside the user scope.
+
+### Phase 4: Validation And Sync
+
+1. Run `.claude/scripts/validate-docs.cjs <docs-root>` when available.
+2. Treat warnings as review signals; fix resolvable broken links and clearly state remaining warnings.
+3. Update `<docs-root>/.sync_hash` only after docs are accurately synchronized with the code version being documented.
+
+## Additional Requests
+
+Apply extra user instructions only within docs scope. Do not start product implementation from a docs update prompt.
+
+## Required Final Report
+
+Report:
+
+- docs root used
+- source changes/scopes reviewed
+- docs changed and docs intentionally untouched
+- stale claims corrected
+- validation result
+- unresolved questions
+
+If a requested change belongs to future behavior rather than current project docs, recommend:
+
+```text
+/hapo:specs <change request>
+```

package/src/claude/skills/docs/templates/evidence-map.md

@@ -0,0 +1,14 @@
+# Evidence Map: {{SCOPE}}
+
+## Ledger
+
+| ID | Surface | Source | Observation | Related Behavior | Confidence | Gap |
+|---|---|---|---|---|---|---|
+| E-API-001 | API | `{{PATH}}:{{SYMBOL}}` | {{DIRECT_OBSERVATION}} | R-ASIS-001 | High | None |
+| E-TEST-001 | Test | `{{PATH}}` | {{ASSERTED_BEHAVIOR}} | R-ASIS-001 | High | None |
+
+## Evidence Notes
+
+- Evidence IDs must stay stable inside this bundle.
+- Existing docs may seed investigation, but source/test/schema/config evidence confirms claims.
+- Put missing runtime data, customer policy, and unreachable code paths in the Gap column and unknowns file.

package/src/claude/skills/docs/templates/reconstruct-overview.html

@@ -0,0 +1,205 @@
+<!doctype html>
+<html lang="en" data-reconstruct-overview>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>As-Is Reconstruction Overview - {{SCOPE}}</title>
+  <style>
+    :root {
+      color-scheme: light;
+      --bg: #f5faf8;
+      --panel: #fff;
+      --ink: #15231e;
+      --muted: #566b63;
+      --line: #d8e6e0;
+      --brand: #087a5a;
+      --sky: #0369a1;
+      --observed: #047857;
+      --inferred: #b45309;
+      --unknown: #be123c;
+      --soft: #eaf6f1;
+      --shadow: 0 14px 36px rgba(15, 23, 42, 0.08);
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background:
+        radial-gradient(circle at 8% 4%, rgba(8, 122, 90, 0.18), transparent 30rem),
+        radial-gradient(circle at 92% 2%, rgba(3, 105, 161, 0.14), transparent 28rem),
+        linear-gradient(180deg, #f9fffd, var(--bg));
+      color: var(--ink);
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      line-height: 1.5;
+    }
+    main { width: min(1240px, calc(100% - 32px)); margin: 0 auto; padding: 32px 0 56px; }
+    .hero, aside, section {
+      border: 1px solid var(--line);
+      border-radius: 16px;
+      background: rgba(255, 255, 255, 0.94);
+      box-shadow: var(--shadow);
+    }
+    .hero { padding: 28px; display: grid; gap: 18px; }
+    .eyebrow { color: var(--brand); font-size: 12px; font-weight: 800; text-transform: uppercase; }
+    h1, h2, h3 { letter-spacing: 0; line-height: 1.15; margin: 0; }
+    h1 { font-size: clamp(30px, 4vw, 52px); }
+    h2 { font-size: 22px; }
+    h3 { font-size: 16px; }
+    p { margin: 0; }
+    .muted { color: var(--muted); }
+    .metrics, .grid { display: grid; gap: 12px; }
+    .metrics { grid-template-columns: repeat(5, minmax(0, 1fr)); }
+    .metric, .card {
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      background: #fbfefd;
+      padding: 14px;
+    }
+    .metric span, .label { color: var(--muted); display: block; font-size: 12px; }
+    .metric strong { display: block; font-size: 18px; margin-top: 6px; overflow-wrap: anywhere; }
+    .layout {
+      display: grid;
+      grid-template-columns: 260px minmax(0, 1fr);
+      gap: 18px;
+      align-items: start;
+      margin-top: 18px;
+    }
+    aside { padding: 18px; position: sticky; top: 18px; }
+    nav { display: grid; gap: 8px; margin-top: 14px; }
+    nav a {
+      border: 1px solid var(--line);
+      border-radius: 10px;
+      color: var(--ink);
+      background: #fbfefd;
+      padding: 9px 10px;
+      text-decoration: none;
+    }
+    nav a:hover { border-color: var(--brand); color: var(--brand); }
+    .content { display: grid; gap: 16px; }
+    section { padding: 20px; display: grid; gap: 14px; }
+    .grid.two { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .grid.three { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+    .badge {
+      border: 1px solid currentColor;
+      border-radius: 999px;
+      display: inline-flex;
+      font-size: 12px;
+      font-weight: 800;
+      gap: 6px;
+      padding: 4px 9px;
+      width: fit-content;
+    }
+    .observed { color: var(--observed); background: #ecfdf5; }
+    .inferred { color: var(--inferred); background: #fff7ed; }
+    .unknown { color: var(--unknown); background: #fff1f2; }
+    .flow { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
+    .node { border: 1px solid var(--line); border-radius: 10px; background: var(--soft); padding: 9px 11px; }
+    .arrow { color: var(--sky); font-weight: 900; }
+    table { width: 100%; border-collapse: collapse; font-size: 14px; }
+    th, td { border-bottom: 1px solid var(--line); padding: 10px 8px; text-align: left; vertical-align: top; }
+    th { color: var(--muted); }
+    code { border: 1px solid var(--line); border-radius: 6px; background: var(--soft); padding: 1px 5px; }
+    ul { margin: 0; padding-left: 18px; }
+    @media (max-width: 900px) {
+      .layout, .metrics, .grid.two, .grid.three { grid-template-columns: 1fr; }
+      aside { position: static; }
+    }
+  </style>
+</head>
+<body>
+<main>
+  <header class="hero">
+    <div class="eyebrow">CafeKit As-Is Reconstruction</div>
+    <div>
+      <h1>{{SCOPE}}</h1>
+      <p class="muted">Review current behavior recovered from source evidence before creating change specs.</p>
+    </div>
+    <div class="metrics">
+      <div class="metric"><span>Source revision</span><strong>{{SOURCE_REVISION}}</strong></div>
+      <div class="metric"><span>Generated</span><strong>{{GENERATED_AT}}</strong></div>
+      <div class="metric"><span>Observed</span><strong>{{OBSERVED_COUNT}}</strong></div>
+      <div class="metric"><span>Inferred</span><strong>{{INFERRED_COUNT}}</strong></div>
+      <div class="metric"><span>Unknown</span><strong>{{UNKNOWN_COUNT}}</strong></div>
+    </div>
+  </header>
+
+  <div class="layout">
+    <aside>
+      <h2>Review Map</h2>
+      <p class="muted">Markdown and JSON remain source of truth. This HTML is a visual review surface.</p>
+      <nav>
+        <a href="#system">System</a>
+        <a href="#requirements">Requirements</a>
+        <a href="#entities">Entities</a>
+        <a href="#rules">Rules</a>
+        <a href="#integrations">Integrations</a>
+        <a href="#unknowns">Unknowns</a>
+        <a href="#evidence">Evidence</a>
+      </nav>
+    </aside>
+
+    <div class="content">
+      <section id="system">
+        <h2>System Overview</h2>
+        <!-- SYSTEM_OVERVIEW_START -->
+        <div class="flow">
+          <span class="node">{{ACTOR}}</span><span class="arrow">-&gt;</span>
+          <span class="node">{{ENTRY_POINT}}</span><span class="arrow">-&gt;</span>
+          <span class="node">{{STATE_OR_EXTERNAL_SYSTEM}}</span>
+        </div>
+        <!-- SYSTEM_OVERVIEW_END -->
+      </section>
+
+      <section id="requirements">
+        <h2>Recovered Requirements</h2>
+        <div class="grid two">
+          <!-- REQUIREMENTS_START -->
+          <article class="card">
+            <span class="badge observed">Observed</span>
+            <h3>R-ASIS-001 {{CURRENT_BEHAVIOR}}</h3>
+            <p class="muted">Actor: {{ACTOR}} | Evidence: E-API-001, E-TEST-001</p>
+          </article>
+          <!-- REQUIREMENTS_END -->
+        </div>
+      </section>
+
+      <section id="entities">
+        <h2>Entities And Statuses</h2>
+        <!-- ENTITIES_START -->
+        <div class="grid three"><div class="card">{{ENTITY_AND_STATUS_SUMMARY}}</div></div>
+        <!-- ENTITIES_END -->
+      </section>
+
+      <section id="rules">
+        <h2>Business Rules And Decisions</h2>
+        <!-- RULES_START -->
+        <ul><li>{{VALIDATION_CALCULATION_CONSTRAINT_OR_DECISION}}</li></ul>
+        <!-- RULES_END -->
+      </section>
+
+      <section id="integrations">
+        <h2>Integrations</h2>
+        <!-- INTEGRATIONS_START -->
+        <table><thead><tr><th>System</th><th>Evidence</th><th>Current behavior</th></tr></thead>
+        <tbody><tr><td>{{EXTERNAL_SYSTEM}}</td><td>{{EVIDENCE_ID}}</td><td>{{BEHAVIOR}}</td></tr></tbody></table>
+        <!-- INTEGRATIONS_END -->
+      </section>
+
+      <section id="unknowns">
+        <h2>Human Review Queue</h2>
+        <!-- UNKNOWNS_START -->
+        <article class="card"><span class="badge unknown">Unknown</span><p>{{QUESTION_FOR_DOMAIN_REVIEWER}}</p></article>
+        <!-- UNKNOWNS_END -->
+      </section>
+
+      <section id="evidence">
+        <h2>Evidence Trace</h2>
+        <!-- EVIDENCE_START -->
+        <table><thead><tr><th>ID</th><th>Source</th><th>Observation</th></tr></thead>
+        <tbody><tr><td>E-API-001</td><td><code>{{PATH_OR_SYMBOL}}</code></td><td>{{DIRECT_OBSERVATION}}</td></tr></tbody></table>
+        <!-- EVIDENCE_END -->
+      </section>
+    </div>
+  </div>
+</main>
+</body>
+</html>

package/src/claude/skills/docs/templates/reconstruction.json

@@ -0,0 +1,40 @@
+{
+  "scope": "{{SCOPE}}",
+  "generated_at": "{{ISO_TIMESTAMP}}",
+  "status": "draft",
+  "docs_root": "{{DOCS_ROOT}}/as-is/{{SCOPE_SLUG}}",
+  "source_revision": "{{SOURCE_REVISION_OR_UNAVAILABLE_REASON}}",
+  "source_branch": "{{SOURCE_BRANCH_OR_UNAVAILABLE_REASON}}",
+  "evidence_policy": "observed-inferred-unknown",
+  "review_gate": "human_review_required",
+  "review_status": "pending",
+  "reviewed_by": null,
+  "reviewed_at": null,
+  "approved_for_specs": false,
+  "source_scope": [
+    "{{SCOPE}}"
+  ],
+  "documents": [
+    "overview.html",
+    "system-overview.md",
+    "requirements-as-is.md",
+    "roles-and-permissions.md",
+    "entities-and-statuses.md",
+    "business-rules.md",
+    "integrations.md",
+    "architecture-c4.md",
+    "constraints-risks-and-decisions.md",
+    "glossary.md",
+    "evidence-map.md",
+    "unknowns-and-assumptions.md"
+  ],
+  "counts": {
+    "requirements": 0,
+    "evidence_items": 0,
+    "observed": 0,
+    "inferred": 0,
+    "unknown": 0,
+    "open_unknowns": 0
+  },
+  "next_recommended_step": "human_review"
+}

package/src/claude/skills/docs/templates/requirements-as-is.md

@@ -0,0 +1,34 @@
+# As-Is Requirements: {{SCOPE}}
+
+## Evidence Policy
+
+Each requirement records current behavior only.
+
+- `Observed`: current behavior directly supported by source/test/schema/config evidence.
+- `Inferred`: likely current behavior supported by multiple signals but not fully proven.
+- `Unknown`: code indicates a gap that needs human or runtime confirmation.
+
+## R-ASIS-001: {{CURRENT_BEHAVIOR_TITLE}}
+
+- Type: Observed
+- Confidence: High
+- Evidence:
+  - E-API-001 - `{{PATH_OR_SYMBOL}}`
+  - E-TEST-001 - `{{PATH_OR_SYMBOL}}`
+- Actors:
+  - {{ACTOR_OR_CALLER}}
+- Trigger:
+  - {{ENTRY_POINT_OR_EVENT}}
+- Inputs:
+  - {{INPUTS_OR_NONE}}
+- Current outcome:
+  - {{CURRENT_RESULT}}
+- Exceptions or gaps:
+  - {{ERROR_PATH_OR_UNKNOWN}}
+- Notes:
+  - {{SHORT_REVIEW_NOTE}}
+
+## Open Review Notes
+
+- Replace template examples with source-backed requirements.
+- Move requested future changes to `/hapo:specs`, not this file.

package/src/claude/skills/docs/templates/unknowns-and-assumptions.md

@@ -0,0 +1,19 @@
+# Unknowns And Assumptions: {{SCOPE}}
+
+## Review Queue
+
+| ID | Topic | Type | Why It Is Unresolved | Needed Confirmation |
+|---|---|---|---|---|
+| U-001 | {{TOPIC}} | Unknown | {{CODE_OR_RUNTIME_GAP}} | {{DOMAIN_OR_RUNTIME_ANSWER}} |
+
+## Inferred Behavior To Confirm
+
+- {{INFERRED_BEHAVIOR_WITH_EVIDENCE_IDS}}
+
+## Business Rules Missing From Code
+
+- {{QUESTION_FOR_DOMAIN_REVIEWER}}
+
+## Runtime Or Environment Gaps
+
+- {{EXTERNAL_SERVICE_DATA_OR_CONFIG_GAP}}

package/src/claude/status.cjs

@@ -14,7 +14,8 @@ const fs = require('fs');
 const path = require('path');
 
 // Import modular components
-const { green, yellow, red, cyan, magenta, dim, coloredBar, RESET, shouldUseColor } = require('./hooks/lib/color.cjs');
+const colors = require('./hooks/lib/color.cjs');
+const { green, yellow, red, cyan, magenta, dim, coloredBar, RESET } = colors;
 const { parseTranscript } = require('./hooks/lib/parser.cjs');
 const { countConfigs } = require('./hooks/lib/counter.cjs');
 const { loadConfig } = require('./hooks/lib/config.cjs');
@@ -358,7 +359,7 @@ function render(ctx, singleLineMode = false) {
 
   // Output all lines with non-breaking spaces for alignment
   for (const line of lines) {
-    const outputLine = shouldUseColor ? `${RESET}${line.replace(/ /g, '\u00A0')}` : line;
+    const outputLine = colors.shouldUseColor ? `${RESET}${line.replace(/ /g, '\u00A0')}` : line;
     console.log(outputLine);
   }
 }
@@ -509,6 +510,7 @@ async function main() {
     // Load config and get statusline mode
     const config = loadConfig({ includeProject: false, includeAssertions: false, includeLocale: false });
     const statuslineMode = config.statusline || 'full';
+    colors.setColorEnabled(config.statuslineColors !== false);
 
     // Render based on mode
     switch (statuslineMode) {