@haposoft/cafekit 0.8.12 → 0.8.14

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

@@ -0,0 +1,407 @@
+# Reconstruct Workflow
+
+Use this reference for `/hapo:docs reconstruct <scope>`.
+
+## Goal
+
+Rebuild current-state, as-is system documentation from source code.
+
+This is useful for:
+
+- existing systems with weak or missing documentation
+- legacy system modernization discovery
+- sales demos showing source-code-to-docs capability
+- preparing a reviewed baseline before `/hapo:specs` creates modernization/change specs
+
+## Non-Goal
+
+This workflow does not produce future design, implementation tasks, rewrite plans, or product code.
+
+It answers:
+
+```text
+What does the current system appear to do, based on evidence?
+```
+
+It does not answer:
+
+```text
+What should the future system do?
+```
+
+## Output Contract
+
+Write output under:
+
+```text
+docs/as-is/<scope-slug>/
+```
+
+Files:
+
+```text
+overview.html
+reconstruction.json
+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
+```
+
+If the user provides a different docs root through `.claude/runtime.json`, use that root.
+
+Use the bundled templates as output starters:
+
+- `templates/reconstruction.json`
+- `templates/requirements-as-is.md`
+- `templates/evidence-map.md`
+- `templates/unknowns-and-assumptions.md`
+- `templates/reconstruct-overview.html`
+
+`overview.html` is a self-contained visual review surface. Markdown and JSON remain the source of truth.
+
+## Required Classification
+
+Every major finding must include:
+
+```text
+Type: Observed | Inferred | Unknown
+Confidence: High | Medium | Low
+Evidence:
+- path/to/file.ext
+- path/to/file.ext:functionOrClass
+- path/to/test.spec.ts
+```
+
+Use line numbers when available from reads. If exact line numbers are not available, cite file paths and symbols.
+
+## Reconstruction Reader Model
+
+Reconstruction is written for two readers:
+
+1. a domain reviewer who can confirm or reject recovered behavior
+2. a future `hapo:specs` run that needs an approved as-is baseline before change design
+
+Write each document so those readers can separate:
+
+- current behavior visible from source
+- behavior inferred from multiple code signals
+- missing business context only humans or runtime evidence can supply
+
+## Evidence Quality
+
+High confidence:
+- directly found in route/controller/component/schema/test/config
+- supported by at least one source file and one behavior signal
+
+Medium confidence:
+- supported by multiple related source signals, but no explicit test or end-to-end path
+
+Low confidence:
+- suggested by naming, partial code, comments, or incomplete references
+
+Unknown:
+- not enough evidence
+- code path is dead or unreachable
+- behavior depends on runtime data, external service, manual operation, or undocumented configuration
+
+## Evidence Ledger
+
+Build an evidence ledger before writing conclusions. An evidence row should capture:
+
+| Field | Meaning |
+|---|---|
+| ID | Stable evidence ID such as `E-API-003` |
+| Surface | UI, API, data, auth, job, integration, test, config |
+| Source | File path and symbol/route/schema/test |
+| Observation | What the source directly proves |
+| Related behavior | Requirement/business rule/entity it may support |
+| Confidence | High, Medium, Low |
+| Gap | Missing trigger, runtime data, customer rule, or external system |
+
+Write the human-readable ledger into `evidence-map.md`. Reference evidence IDs from reconstructed requirements and supporting docs when a requirement needs multiple sources.
+
+## Workflow
+
+### 1. Scope Gate
+
+If `<scope>` is missing, ask for a module or bounded context.
+
+If `<scope>` is broad (`.`, `/`, `whole repo`, `entire system`):
+
+1. Run a structure scout first.
+2. Identify 2-6 candidate modules.
+3. Ask the user to choose, unless one module is clearly requested by the prompt.
+
+Never silently reconstruct a large system as one flat document.
+
+### 2. Structure And Source Scout
+
+Use `hapo:inspect` patterns or targeted reads to identify:
+
+- project type and language/framework
+- relevant screens/pages/routes
+- API endpoints/controllers
+- database schemas, migrations, models, entities
+- state machines/status fields/enums
+- validation logic
+- permission/auth checks
+- tests and fixtures
+- integrations, workers, jobs, cron, queues, webhooks
+- existing docs that may be stale or useful
+
+Use existing docs only as leads until source evidence confirms them.
+
+Save detailed scout findings and evidence IDs in:
+
+```text
+docs/as-is/<scope-slug>/evidence-map.md
+```
+
+### 3. Trace Behavior Surfaces
+
+Recover behavior by tracing reachable source surfaces:
+
+| Surface | Questions to answer |
+|---|---|
+| UI/screens | What actor sees, starts, filters, updates, downloads |
+| API/routes | What operations exist, inputs accepted, outputs/errors returned |
+| Data/schema | What entities, fields, statuses, relations, constraints exist |
+| Auth/permissions | Who can access which route/action/record |
+| Business rules | What validation, calculations, branching, lifecycle rules exist |
+| Background work | What jobs, events, queues, schedulers, hooks run |
+| Integrations | What external services, files, webhooks, mailers, payments exist |
+| Tests | What intended behavior is asserted and what gaps remain |
+
+Prefer end-to-end traces that connect entry point, rule, state change, and output. When a trace is incomplete, keep the gap in the evidence ledger and unknowns list.
+
+### 4. Reconstruct As-Is Requirements
+
+Write `requirements-as-is.md` using current behavior only.
+
+Recommended shape:
+
+```markdown
+## R-ASIS-001: <current behavior>
+- Type: Observed
+- Confidence: High
+- Evidence:
+  - E-API-003 — src/...
+  - E-TEST-004 — tests/...
+- Actors:
+  - ...
+- Trigger:
+  - ...
+- Current outcome:
+  - ...
+- Exceptions or gaps:
+  - ...
+- Notes:
+  - ...
+```
+
+Requirements should be singular, testable, and tied to code evidence.
+
+Do not use future-tense language such as "will", "should", or "must be improved" unless quoting existing source docs.
+
+Recommended extraction checklist:
+
+1. Identify actor or caller.
+2. Identify trigger and source entry point.
+3. Identify input, validation, state read/write, output, and error behavior.
+4. Link entity/status/permission/integration evidence.
+5. Mark requirement `Observed` only when its current behavior is directly supported.
+6. Move uncertain policy intent to `unknowns-and-assumptions.md`.
+
+### 5. Reconstruct Supporting Docs
+
+`system-overview.md`:
+- scope summary
+- actor summary
+- module boundaries
+- primary runtime entry points
+
+`roles-and-permissions.md`:
+- roles
+- allowed/blocked actions
+- permission checks and evidence
+- unauthenticated/authenticated boundaries when visible
+
+`entities-and-statuses.md`:
+- entities/models
+- important fields
+- statuses/enums
+- state transitions
+
+`business-rules.md`:
+- validations
+- calculations
+- branching conditions
+- lifecycle rules
+- non-obvious defaults and side effects
+
+`integrations.md`:
+- external APIs
+- email/SMS/payment/file import/export
+- batch/cron/queue/webhook behavior
+
+`architecture-c4.md`:
+- C4-style textual diagrams or Mermaid diagrams if useful
+- system context
+- container/component view for the selected scope
+- runtime/deployment notes only when source evidence exists
+
+`constraints-risks-and-decisions.md`:
+- technical and business constraints observed in source/config
+- recovered quality risks or technical debt that affect modernization review
+- architecture decisions with rationale only when evidence exists
+- explicitly unknown rationale when code shows the decision but not the reason
+
+`glossary.md`:
+- domain terms found in screens, schemas, routes, jobs, and tests
+- source vocabulary aliases or unclear terms needing reviewer correction
+- status/role labels that a reviewer should normalize before specs
+
+`unknowns-and-assumptions.md`:
+- uncertain areas
+- inferred behavior needing human confirmation
+- missing environment/runtime/data dependencies
+- interview questions for customer/domain expert
+
+### 6. Cross-Document Consistency Review
+
+Before declaring the bundle ready for review:
+
+1. Check that each as-is requirement has evidence or is explicitly unknown.
+2. Check that actors in requirements appear in roles/permissions or unknowns.
+3. Check that statuses and transitions match schemas/enums/rules found.
+4. Check that integrations listed in requirements appear in `integrations.md`.
+5. Check that architecture claims do not exceed evidence scope.
+6. Move future ideas and requested changes out of as-is docs.
+
+### 7. Build `overview.html`
+
+Generate `overview.html` from the reconstruct overview template after the markdown bundle has enough evidence to summarize:
+
+- scope, source revision, generated time, review status
+- observed/inferred/unknown counts
+- actor/module/external-system overview
+- recovered requirement cards with evidence IDs
+- entity/status summary
+- business rule/integration summary
+- human review queue and evidence trace
+
+Do not put unique facts only in HTML. Every overview claim must be traceable to markdown/JSON evidence.
+
+### 8. Build `reconstruction.json`
+
+Use this machine-readable summary:
+
+```json
+{
+  "scope": "<scope>",
+  "generated_at": "<ISO timestamp>",
+  "status": "draft",
+  "docs_root": "docs/as-is/<scope-slug>",
+  "source_revision": "<git commit or unavailable reason>",
+  "source_branch": "<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"
+}
+```
+
+If Git revision data is unavailable, record an explicit reason in `source_revision` instead of leaving the source snapshot blank.
+
+### 9. Validate Bundle
+
+Run the deterministic gate before human review:
+
+```text
+node .claude/scripts/validate-docs-reconstruct.cjs docs/as-is/<scope-slug>
+```
+
+Validator failure blocks the handoff. Fix:
+
+- missing bundle files
+- incomplete `reconstruction.json` registry/review metadata
+- requirements missing type/confidence/evidence IDs
+- evidence IDs missing from `evidence-map.md`
+- overview output missing its review-surface marker
+
+### 10. Human Review Gate
+
+End with a clear review prompt:
+
+- confirm observed requirements
+- correct inferred behavior
+- answer unknowns
+- add business rules that are not present in code
+
+Do not recommend `/hapo:develop`.
+
+Do not call the output approved until human review has resolved high-impact inferred and unknown behavior.
+
+Recommended handoff after review:
+
+```text
+/hapo:specs <modernization/change request based on approved docs/as-is/<scope-slug>>
+```
+
+## Guardrails
+
+- Do not invent missing behavior.
+- Do not collapse `Inferred` into `Observed`.
+- Do not omit unknowns to make the report look complete.
+- Do not describe future improvements inside as-is docs.
+- Do not create tasks or implementation plans.
+- Do not read ignored/generated/sensitive paths such as `.git`, `node_modules`, `dist`, `build`, `.next`, `coverage`, `.env`, secrets, or private dumps.
+- Do not trust stale docs without source verification.
+- Do not use route names, enum names, or comments alone to claim business intent when rule execution is not traced.
+- Do not treat HTML as source of truth; it is a visual layer over evidence-backed docs.
+
+## Best-Practice Basis
+
+Apply:
+
+- Docs as Code: commit docs with source.
+- C4: capture architecture at the right abstraction level.
+- arc42: preserve context, building blocks, runtime behavior, risks, and decisions.
+- Diataxis: separate explanation/reference/how-to content.
+- ADR discipline: record recovered decisions as evidence-backed notes, not guesses.

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

@@ -0,0 +1,124 @@
+# Standard Docs Workflow
+
+Use this shared contract for `/hapo:docs init`, `/hapo:docs update`, and `/hapo:docs summarize`.
+
+Then load the mode-specific reference:
+
+- `init-workflow.md`
+- `update-workflow.md`
+- `summarize-workflow.md`
+
+## Purpose
+
+Create or refresh living project documentation from the current repository.
+
+This workflow is for normal project docs. If the user asks to reconstruct current behavior from a legacy/existing system, use `reconstruct-workflow.md` instead.
+
+## Inputs
+
+- `README.md`
+- existing `docs/` files
+- package manifests and workspace config
+- source directories such as `src/`, `app/`, `apps/`, `packages/`, `lib/`
+- tests, build scripts, CI config, deployment config
+
+## Output Files
+
+Use the docs root from `.claude/runtime.json` (`paths.docs`, default `docs`).
+
+Recommended files:
+
+```text
+docs/
+├── project-overview-pdr.md
+├── codebase-summary.md
+├── system-architecture.md
+├── code-standards.md
+├── design-guidelines.md
+├── deployment-guide.md
+└── project-roadmap.md
+```
+
+Create only files that are useful. Minimum viable documentation is preferred over a large stale docs set.
+
+## Shared Workflow Decisions
+
+### 1. Decide Operation
+
+`init`:
+- docs missing or clearly incomplete
+- create baseline docs
+
+`update`:
+- docs exist
+- compare recent code changes and update only affected docs
+
+`summarize`:
+- update only `codebase-summary.md`
+
+### 2. Scout And Verify
+
+Normal docs are current-state living docs. Ground them in:
+
+- repo instructions
+- existing docs and README
+- package/workspace/build/runtime config
+- source code that implements the documented behavior
+- tests, CI, deploy config, schemas, migrations, routes when relevant
+
+Use `hapo:inspect` or targeted `rg`/file reads when the project is large. Keep broad scanning scoped by real project areas.
+
+### 3. Author Concisely
+
+Follow these rules:
+
+- prefer short sections over huge narrative
+- document real code, not aspirations
+- keep generated docs easy to review
+- include unresolved questions at the end
+- remove or rewrite stale claims when evidence contradicts existing docs
+- verify paths, commands, config keys, endpoints, and symbols before naming them
+
+### 4. Keep The Core Docs Legible
+
+The Research docs workflow uses a size check after generation and update. CafeKit keeps that rule:
+
+- read `docs.maxLoc` from session/runtime context when available
+- default to 800 lines per markdown document
+- split large topics by semantic boundary instead of expanding one omnibus file
+
+### 5. Sync Tracking
+
+If the project uses `docs/.sync_hash`, update it only after docs accurately reflect the current source state.
+
+Use the same docs root as runtime config:
+
+```text
+<docs-root>/.sync_hash
+```
+
+### 6. Validate
+
+When available, run:
+
+```text
+node .claude/scripts/validate-docs.cjs <docs-root>
+```
+
+Use validation output to catch broken internal doc links before reporting.
+
+### 7. Final Report
+
+Report:
+
+- files created/updated
+- code areas reviewed
+- stale docs corrected
+- unresolved questions
+
+## Guardrails
+
+- Do not run broad full-repo reads when targeted scout is enough.
+- Do not invent architecture from folder names alone.
+- Do not modify product code.
+- Do not overwrite user-written docs without reading them first.

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

@@ -0,0 +1,89 @@
+# Summarize Workflow
+
+Use with `/hapo:docs summarize`.
+
+## Goal
+
+Create or refresh the fastest reliable project orientation artifact:
+
+```text
+<docs-root>/codebase-summary.md
+```
+
+This mode is intentionally smaller than `init` and `update`.
+
+## Inputs
+
+- docs root from `.claude/runtime.json` (`paths.docs`, default `docs`)
+- existing `codebase-summary.md`, if present
+- user focus topics, if provided
+- narrowly selected source evidence
+
+## Argument Semantics
+
+Treat the prompt after `summarize` as focus:
+
+| User request | Behavior |
+|---|---|
+| no focus | summarize current high-level project map |
+| module/path focus | summarize only that area plus its dependencies |
+| explicit "scan codebase" | scout the source layout before summarizing |
+
+Do not scan the entire codebase just because summary mode was selected.
+
+## Workflow
+
+### Phase 1: Read Current Summary
+
+1. Read repo instructions.
+2. Read existing `codebase-summary.md` if present.
+3. Identify stale claims or missing focus areas relevant to the request.
+
+### Phase 2: Focused Scout
+
+Read the smallest evidence set needed:
+
+- top-level manifests and README for project identity
+- the focused module/path if user supplied one
+- runtime entry points and dependency boundaries needed to orient readers
+- tests/config only when they clarify behavior or commands
+
+Use `hapo:inspect` only if the relevant path is unclear. For a broad explicit scan, apply inspect scope gating first.
+
+### Phase 3: Write Summary
+
+Update only `codebase-summary.md`.
+
+Recommended sections:
+
+1. project identity and current purpose
+2. tech stack and commands verified from manifests/config
+3. source layout and major boundaries
+4. runtime entry points and key flows
+5. data/integration notes when directly relevant
+6. links to deeper docs that already exist
+7. unresolved questions
+
+Keep the result usable as an orientation document, not as a requirements spec.
+
+### Phase 4: Validate
+
+1. Validate docs links with `.claude/scripts/validate-docs.cjs <docs-root>` when available.
+2. Respect docs size discipline; split only if summary has become a long handbook and the user asked for that work.
+
+## Guardrails
+
+- Do not update every docs file.
+- Do not reconstruct legacy requirements in summary mode.
+- Do not implement code.
+- Do not convert weak source hints into verified behavior.
+
+## Required Final Report
+
+Report:
+
+- summary path
+- focus used
+- evidence read
+- validation result
+- unresolved questions