@haposoft/cafekit 0.8.13 → 0.8.14

package/README.md

@@ -80,6 +80,7 @@ CafeKit ships many skills, but the main release surface is:
 - `/hapo:develop <feature-name>`: implement from approved spec artifacts
 - `/hapo:debug <issue>`: diagnose bugs, incidents, CI failures, flaky tests, UI regressions, and performance issues before fixing
 - `/hapo:hotfix <issue>`: fix diagnosed bugs with root-cause, verification, prevention, and side-effect gates
+- `/hapo:docs [init|update|summarize|reconstruct]`: create project docs or reconstruct as-is system documentation from source code
 - `/hapo:test [scope|--full]`: run verification and return a structured verdict
 - `/hapo:code-review [scope|--pending]`: adversarial review focused on correctness, regressions, and security
 - `/hapo:generate-graph <diagram request>`: generate technical SVG/PNG diagrams
@@ -125,6 +126,14 @@ Generate a diagram:
 /hapo:generate-graph Draw a sequence diagram for auth flow between browser, API, and database
 ```
 
+Reconstruct current-state docs for an existing or legacy system:
+
+```bash
+/hapo:docs reconstruct apps/legacy-admin
+```
+
+The reconstruct bundle includes as-is markdown/JSON evidence and a self-contained `overview.html` review dashboard before the approved docs are handed to `/hapo:specs`.
+
 ## Spec Artifacts
 
 CafeKit's current spec workflow writes artifacts under:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.13",
+  "version": "0.8.14",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/hooks/lib/skill-router-routes.cjs

@@ -18,7 +18,7 @@ const ROUTES = [
     strong: ['spec', 'specs', 'requirements', 'acceptance criteria', 'task breakdown', 'đặc tả', 'dac ta', '仕様', '仕様書', '要件', '受け入れ条件', 'タスク分解', '仕様を作って', '仕様を作成'],
     medium: ['requirement', 'ears', 'design doc', 'scope', '--validate', 'yêu cầu', 'yeu cau', 'phạm vi', 'pham vi', 'validate spec', 'kiểm tra spec', 'kiem tra spec', '要求', '設計書', 'スコープ', '検証', '仕様を確認'],
     weak: ['tính năng mới', 'tinh nang moi', 'feature idea', 'user story', 'criteria', 'task list', '新機能', 'ユーザーストーリー', '基準', 'タスクリスト'],
-    negative: ['commit', 'push', 'bug', 'error', 'production', 'pptx', 'pdf'],
+    negative: ['commit', 'push', 'bug', 'error', 'production', 'pptx', 'pdf', 'reconstruct requirements', 'as-is requirements', 'legacy system documentation', 'documentation from source code', 'docs from source code', 'ソースコードから'],
   }),
   route('hapo:develop', 'implementation from an approved spec or task list', 75, {
     strong: ['develop', 'implement', 'implementation', 'theo spec', 'theo specs', 'approved spec', 'làm theo spec', 'lam theo spec', '実装', '開発', '仕様に沿って', '仕様どおり', '承認済み仕様'],
@@ -98,6 +98,12 @@ const ROUTES = [
     weak: ['mind map', 'dependency map', 'system map', 'マインドマップ', '依存関係図', 'システム図'],
     negative: ['pptx', 'slide deck'],
   }),
+  route('hapo:docs', 'project documentation, codebase docs, or source-backed as-is reconstruction', 51, {
+    strong: ['hapo:docs', 'project docs', 'system docs', 'codebase docs', 'codebase documentation', 'documentation from source code', 'docs from source code', 'generate docs from codebase', 'dựng tài liệu từ source code', 'dung tai lieu tu source code', 'tài liệu hệ thống', 'tai lieu he thong', 'tài liệu hiện trạng', 'tai lieu hien trang', 'tạo tài liệu project', 'tao tai lieu project', 'legacy documentation', 'legacy system documentation', 'as-is documentation', 'as-is requirements', 'requirement reconstruction', 'reconstruct requirements', 'reconstruct requirements from legacy system', 'ソースコードから仕様書', 'ソースコードから仕様書を作成', 'ソースコードからドキュメント', '既存システムのドキュメント', '現行仕様書', 'as-isドキュメント'],
+    medium: ['create docs', 'update docs', 'refresh docs', 'summarize codebase', 'system documentation', 'source to docs', 'reverse documentation', 'current-state docs', 'existing system docs', 'legacy docs', 'legacy system', 'dựng docs', 'dung docs', 'tạo docs', 'tao docs', 'cập nhật docs', 'cap nhat docs', 'tóm tắt codebase', 'tom tat codebase', 'dựng lại tài liệu', 'dung lai tai lieu', '仕様書を作成', 'ドキュメント作成', 'ドキュメント更新', 'コードベース要約', '既存システム', 'レガシーシステム'],
+    weak: ['docs', 'documentation', 'document project', 'document codebase', 'as-is', 'reconstruct', 'hiện trạng', 'hien trang', 'tài liệu', 'tai lieu', 'ドキュメント', '資料化', '仕様化', '現状'],
+    negative: ['official docs', 'latest docs', 'library docs', 'framework docs', 'api docs lookup', 'context7', 'best practice', 'research', 'pptx', 'slide'],
+  }),
   route('hapo:brainstorm', 'early ideation or unclear solution direction', 50, {
     strong: ['brainstorm', 'ý tưởng', 'y tuong', 'phương án', 'phuong an', 'gợi ý', 'goi y', 'ブレスト', 'アイデア', '案', '提案して', '相談'],
     medium: ['idea', 'ideas', 'approach', 'options', 'tradeoff', 'chủ đề', 'chu de', 'cần làm gì', 'can lam gi', 'アプローチ', '選択肢', 'トレードオフ', 'テーマ', '何をすれば'],

package/src/claude/migration-manifest.json

@@ -15,6 +15,7 @@
       "debug",
       "develop",
       "devops",
+      "docs",
       "docx",
       "frontend-design",
       "frontend-development",
@@ -56,6 +57,7 @@
   "scripts": {
     "required": [
       "validate-docs.cjs",
+      "validate-docs-reconstruct.cjs",
       "browser-tool.cjs",
       "validate-spec-output.cjs"
     ]

package/src/claude/scripts/validate-docs-reconstruct.cjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * CafeKit as-is reconstruction bundle validator.
+ *
+ * The docs workflow is LLM-authored, so the bundle shape and evidence links
+ * must be checked deterministically before it is handed to human review.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DOCUMENT_FILES = [
+  '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',
+];
+const REQUIRED_FILES = ['reconstruction.json', ...DOCUMENT_FILES];
+const EVIDENCE_ID_RE = /\bE-[A-Z]+-\d{3}\b/g;
+
+function usage() {
+  console.error('Usage: node .claude/scripts/validate-docs-reconstruct.cjs docs/as-is/<scope>');
+}
+
+function readJson(filePath, errors) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    errors.push(`reconstruction.json: invalid JSON (${error.message})`);
+    return null;
+  }
+}
+
+function readText(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function uniqueMatches(text, pattern) {
+  return [...new Set(text.match(pattern) || [])].sort();
+}
+
+function validateMeta(bundle, meta, errors) {
+  for (const key of [
+    'scope',
+    'generated_at',
+    'status',
+    'docs_root',
+    'source_revision',
+    'source_branch',
+    'evidence_policy',
+    'review_gate',
+    'review_status',
+    'approved_for_specs',
+    'documents',
+    'counts',
+    'next_recommended_step',
+  ]) {
+    if (!(key in meta)) errors.push(`reconstruction.json.${key}: missing`);
+  }
+
+  for (const key of ['scope', 'generated_at', 'docs_root', 'source_revision', 'source_branch']) {
+    if (key in meta && (typeof meta[key] !== 'string' || meta[key].trim() === '')) {
+      errors.push(`reconstruction.json.${key}: must be a non-empty string`);
+    }
+  }
+  if (meta.approved_for_specs !== false && meta.review_status !== 'approved') {
+    errors.push('reconstruction.json.approved_for_specs: only approved review may set true');
+  }
+  if (!Array.isArray(meta.documents)) {
+    errors.push('reconstruction.json.documents: must be an array');
+    return;
+  }
+
+  const declared = [...meta.documents].sort();
+  const expected = [...DOCUMENT_FILES].sort();
+  if (JSON.stringify(declared) !== JSON.stringify(expected)) {
+    errors.push('reconstruction.json.documents: must exactly list the as-is document bundle');
+  }
+  if (typeof meta.docs_root === 'string' && !meta.docs_root.includes(path.basename(bundle))) {
+    errors.push('reconstruction.json.docs_root: must point at this scope bundle');
+  }
+}
+
+function requirementBlocks(text) {
+  const matches = [...text.matchAll(/^##\s+(R-ASIS-\d{3})\b[^\n]*$/gm)];
+  return matches.map((match, index) => ({
+    id: match[1],
+    text: text.slice(match.index, matches[index + 1]?.index ?? text.length),
+  }));
+}
+
+function validateRequirements(bundle, evidenceText, errors) {
+  const requirementPath = path.join(bundle, 'requirements-as-is.md');
+  const blocks = requirementBlocks(readText(requirementPath));
+  if (blocks.length === 0) {
+    errors.push('requirements-as-is.md: must contain at least one ## R-ASIS-### requirement');
+    return;
+  }
+
+  const ledgerIds = new Set(uniqueMatches(evidenceText, EVIDENCE_ID_RE));
+  for (const block of blocks) {
+    if (!/- Type:\s*(Observed|Inferred|Unknown)\b/.test(block.text)) {
+      errors.push(`requirements-as-is.md:${block.id}: missing Type`);
+    }
+    if (!/- Confidence:\s*(High|Medium|Low)\b/.test(block.text)) {
+      errors.push(`requirements-as-is.md:${block.id}: missing Confidence`);
+    }
+    if (!/^- Evidence:\s*$/m.test(block.text)) {
+      errors.push(`requirements-as-is.md:${block.id}: missing Evidence section`);
+    }
+
+    const evidenceIds = uniqueMatches(block.text, EVIDENCE_ID_RE);
+    if (evidenceIds.length === 0) {
+      errors.push(`requirements-as-is.md:${block.id}: must reference evidence IDs`);
+    }
+    for (const evidenceId of evidenceIds) {
+      if (!ledgerIds.has(evidenceId)) {
+        errors.push(`requirements-as-is.md:${block.id}: unknown evidence ID ${evidenceId}`);
+      }
+    }
+  }
+}
+
+function validateBundle(bundle) {
+  const errors = [];
+  if (!fs.existsSync(bundle)) return { errors: [`${bundle}: bundle directory does not exist`] };
+
+  for (const file of REQUIRED_FILES) {
+    if (!fs.existsSync(path.join(bundle, file))) errors.push(`${file}: missing`);
+  }
+  if (errors.length > 0) return { errors };
+
+  const meta = readJson(path.join(bundle, 'reconstruction.json'), errors);
+  if (meta) validateMeta(bundle, meta, errors);
+
+  const evidence = readText(path.join(bundle, 'evidence-map.md'));
+  if (uniqueMatches(evidence, EVIDENCE_ID_RE).length === 0) {
+    errors.push('evidence-map.md: must define evidence IDs');
+  }
+  validateRequirements(bundle, evidence, errors);
+
+  const overview = readText(path.join(bundle, 'overview.html'));
+  if (!overview.includes('data-reconstruct-overview')) {
+    errors.push('overview.html: must keep reconstruct overview marker');
+  }
+
+  return { errors };
+}
+
+function main() {
+  const input = process.argv[2];
+  if (!input) {
+    usage();
+    process.exit(2);
+  }
+
+  const bundle = path.resolve(process.cwd(), input);
+  const { errors } = validateBundle(bundle);
+  if (errors.length > 0) {
+    console.error(`FAIL ${path.relative(process.cwd(), bundle) || bundle}`);
+    for (const error of errors) console.error(`- ${error}`);
+    process.exit(1);
+  }
+
+  console.log(`PASS ${path.relative(process.cwd(), bundle) || bundle}`);
+}
+
+main();

package/src/claude/scripts/validate-docs.cjs

@@ -42,7 +42,8 @@ function checkBrokenLinks(docsDir) {
 }
 
 function main() {
-  const docsDir = path.resolve(process.cwd(), 'docs');
+  const docsArg = process.argv[2] || 'docs';
+  const docsDir = path.resolve(process.cwd(), docsArg);
   console.log(`[Docs Validator] Auditing bounds directory: ${docsDir}`);
   
   if (!fs.existsSync(docsDir)) {

package/src/claude/skills/docs/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: hapo:docs
+description: "Create, update, summarize, or reconstruct project/system documentation from source code. Use reconstruct mode for as-is documentation of existing or legacy systems with evidence and uncertainty tracking."
+version: 1.0.0
+argument-hint: "[init|update|summarize|reconstruct] [scope]"
+---
+
+# Docs
+
+Project documentation workflow for CafeKit.
+
+`hapo:docs` covers two related but distinct jobs:
+
+1. **Normal project docs** — create, update, or summarize living project documentation.
+2. **As-is reconstruction** — rebuild current-state system documentation from source code, especially for existing or legacy systems with missing documents.
+
+## Command Forms
+
+```text
+/hapo:docs
+/hapo:docs init
+/hapo:docs update
+/hapo:docs summarize
+/hapo:docs reconstruct <scope>
+```
+
+## Default Behavior
+
+Parse the user intent before selecting a mode.
+
+| Intent signal | Mode |
+|---|---|
+| Existing system, legacy system, source-to-docs, as-is, reverse documentation, or requirement reconstruction | `reconstruct` |
+| Missing docs, initialize docs, bootstrap docs | `init` |
+| Existing docs need refresh after code changes | `update` |
+| Short overview, quick codebase summary, summarize docs | `summarize` |
+
+When `/hapo:docs` has no clear mode:
+
+1. Read the docs root from `.claude/runtime.json`.
+2. If the docs root is missing, choose `init`.
+3. If the docs root exists and user did not request only a summary, choose `update`.
+4. Ask one concise clarification only when choosing between normal docs and as-is reconstruction would change the output materially.
+
+Do not show a menu when prompt intent is already clear.
+
+## Output Roots
+
+Read `.claude/runtime.json` first. Use:
+
+```json
+{
+  "paths": {
+    "docs": "docs"
+  }
+}
+```
+
+Default docs root: `docs/`.
+
+Normal docs live directly under the docs root:
+
+```text
+docs/
+├── project-overview-pdr.md
+├── codebase-summary.md
+├── system-architecture.md
+├── code-standards.md
+├── design-guidelines.md
+├── deployment-guide.md
+└── project-roadmap.md
+```
+
+Reconstructed as-is docs live under:
+
+```text
+docs/as-is/<scope-slug>/
+├── 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
+```
+
+## Subcommands
+
+### `init`
+
+Create the standard project docs set from the current source code.
+
+Use when:
+- the repository has code but no useful docs
+- the user asks to create project docs
+- SessionStart docs-sync reports missing documentation
+
+Load:
+- `references/standard-docs-workflow.md`
+- `references/init-workflow.md`
+
+### `update`
+
+Refresh existing docs after code changes.
+
+Use when:
+- docs exist and source code changed
+- the user asks to update or refresh docs
+- docs-sync reports stale docs
+
+Load:
+- `references/standard-docs-workflow.md`
+- `references/update-workflow.md`
+
+### `summarize`
+
+Create or update only `codebase-summary.md`.
+
+Use when:
+- the user asks for a quick project summary
+- downstream work needs orientation but not full docs
+
+Load:
+- `references/standard-docs-workflow.md`
+- `references/summarize-workflow.md`
+
+### `reconstruct`
+
+Rebuild current-state, as-is system documentation from source code.
+
+Use when the user asks for:
+- legacy system documentation
+- source-code-to-documentation
+- current system requirements
+- as-is requirements
+- requirement reconstruction
+- reverse documentation
+- Japanese-style legacy system modernization discovery
+
+Load:
+- `references/reconstruct-workflow.md`
+- `templates/reconstruction.json`
+- `templates/requirements-as-is.md`
+- `templates/evidence-map.md`
+- `templates/unknowns-and-assumptions.md`
+- `templates/reconstruct-overview.html`
+
+## Reconstruction Is Not Specs
+
+`hapo:docs reconstruct` MUST NOT:
+
+- design future behavior
+- add new requirements
+- create implementation tasks
+- create `specs/<feature>/`
+- run `/hapo:develop`
+- claim full business intent from code alone
+
+Correct handoff:
+
+```text
+/hapo:docs reconstruct <scope>
+-> human review of as-is docs
+-> /hapo:specs <modernization or change request>
+-> /hapo:develop <feature>
+```
+
+## Reconstruction Evidence Rules
+
+Every major finding in reconstructed docs MUST be classified:
+
+```text
+Type: Observed | Inferred | Unknown
+Confidence: High | Medium | Low
+Evidence: file path, symbol, route, schema, test, or config
+```
+
+Definitions:
+
+- `Observed`: directly visible in source code, tests, schemas, route definitions, config, or docs.
+- `Inferred`: likely behavior derived from multiple signals, but not directly proven.
+- `Unknown`: cannot be established from available evidence.
+
+Do not hide uncertainty. Preserving unknowns is part of the output.
+
+## Scope Discipline
+
+Start with the narrowest useful scope.
+
+For broad inputs such as `.`, `/`, `whole repo`, or `entire system`:
+
+1. Run a lightweight structure scout first.
+2. Split the project into modules or bounded contexts.
+3. Ask the user to pick a module if the first pass cannot safely choose one.
+
+Prefer:
+
+```text
+/hapo:docs reconstruct apps/admin
+/hapo:docs reconstruct modules/expense-approval
+/hapo:docs reconstruct src/features/order
+```
+
+Avoid reconstructing a large monolith in one pass unless the user explicitly accepts lower precision.
+
+## Agent And Tool Fit
+
+Normal docs workflows reuse the CafeKit docs stack already shipped in the package:
+
+- use `hapo:inspect` or targeted reads to scout source scope
+- use `docs-keeper` for evidence-backed docs writing when delegation is available
+- use `.claude/scripts/validate-docs.cjs <docs-root>` after create/update work
+- use `.claude/scripts/validate-docs-reconstruct.cjs <docs-root>/as-is/<scope-slug>` before a reconstructed bundle is handed to human review
+
+The upstream Research docs workflow names a `docs-manager` agent. CafeKit ships `docs-keeper` instead; keep the same scouting, size-check, and validation discipline while using the packaged agent contract.
+
+`reconstruct` may use the same scout patterns, but it writes a scoped as-is bundle and must keep uncertainty visible.
+
+## Best-Practice Basis
+
+Use these documentation principles:
+
+- **Docs as Code**: docs live in the repo and are reviewed like code.
+- **C4 Model**: use system context/container/component views when architecture is relevant.
+- **arc42**: capture context, building blocks, runtime behavior, deployment, risks, and decisions when useful.
+- **Diataxis**: separate explanation, reference, and how-to content instead of dumping one long file.
+- **ADR discipline**: if code reveals important architectural decisions, record them as recovered decision notes, not guesses.
+
+## Required Final Report
+
+For any `hapo:docs` run, report:
+
+- files created or updated
+- scope analyzed
+- evidence quality
+- unresolved questions
+- recommended next command, if any
+
+For `reconstruct`, the recommended next command is usually:
+
+```text
+/hapo:specs <change request based on approved as-is docs>
+```
+
+## References
+
+- `references/standard-docs-workflow.md`
+- `references/init-workflow.md`
+- `references/update-workflow.md`
+- `references/summarize-workflow.md`
+- `references/reconstruct-workflow.md`
+- `templates/reconstruction.json`
+- `templates/requirements-as-is.md`
+- `templates/evidence-map.md`
+- `templates/unknowns-and-assumptions.md`
+- `templates/reconstruct-overview.html`

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

@@ -0,0 +1,132 @@
+# Init Workflow
+
+Use with `/hapo:docs init`.
+
+## Goal
+
+Create a first evidence-backed documentation baseline for a repository that already has source code but lacks useful project docs.
+
+The first run should make future agents faster without presenting guesses as project truth.
+
+## Inputs
+
+Resolve the docs root from `.claude/runtime.json` first. Default to `docs/`.
+
+Read or scout:
+
+- `README.md`, `CLAUDE.md`, `AGENTS.md`, and root instructions that exist
+- package/workspace manifests, lock files, build config, runtime config
+- source directories that actually exist
+- tests, migrations, schemas, routes, CI, deployment config
+- current docs root if it exists but is incomplete
+
+Do not hardcode `src/` when a project uses `apps/`, `packages/`, `cmd/`, `internal/`, `modules/`, or another structure.
+
+## Required Baseline
+
+Create or update the useful core docs below:
+
+| File | Purpose | Creation rule |
+|---|---|---|
+| `README.md` | Entry point and quick commands | Update if needed; keep concise |
+| `<docs-root>/project-overview-pdr.md` | Product purpose, actors, capabilities, constraints | Core |
+| `<docs-root>/codebase-summary.md` | Project structure, tech stack, major runtime paths | Core |
+| `<docs-root>/code-standards.md` | Observed conventions, commands, code quality rules | Core |
+| `<docs-root>/system-architecture.md` | Boundaries, components, runtime/data flow | Core |
+| `<docs-root>/project-roadmap.md` | Current state, milestones, known follow-up areas | Core when evidence exists |
+| `<docs-root>/deployment-guide.md` | Build/deploy/runtime config | Optional when deployment evidence exists |
+| `<docs-root>/design-guidelines.md` | UI/design conventions | Optional when UI evidence exists |
+
+Do not create a large document solely to fill the table. If a core file cannot be grounded yet, create the smallest useful shell and put unresolved questions at the end.
+
+## Workflow
+
+### Phase 0: Preflight
+
+1. Read repo instructions and runtime docs root.
+2. Detect whether docs already exist.
+3. If user specifically asked `init` and docs exist, preserve existing content:
+   - read it first
+   - merge or add missing baseline sections
+   - do not overwrite human-written docs blind
+4. Build a no-scan list for ignored, generated, vendor, cache, secret, and credential paths.
+
+### Phase 1: Structure Scout
+
+Run a lightweight source scout before deep reading:
+
+1. List top-level directories and key manifests.
+2. Count file/LOC shape by existing source areas where practical.
+3. Identify project type:
+   - language/framework
+   - package manager/build system
+   - app/service boundaries
+   - UI/API/worker/job/deployment surfaces
+4. Split large repositories into scoped source areas.
+
+Use `hapo:inspect` when source discovery spans multiple directories. Prefer targeted reads when the repo is small.
+
+### Phase 2: Evidence Scout
+
+Collect evidence for docs authorship:
+
+| Topic | Evidence examples |
+|---|---|
+| Tech stack | package manifests, `go.mod`, `pyproject.toml`, build files |
+| Commands | scripts, Makefiles, CI jobs |
+| Runtime entry points | app bootstrap, routes, controllers, server main files |
+| Data model | schemas, migrations, models, DTOs |
+| Architecture | imports between modules, service boundaries, deploy config |
+| Testing | test commands, test directories, fixtures |
+| UI/design | shared components, tokens, styles, screenshots when present |
+
+Merge scout results into a concise context summary. Keep file references with each important claim.
+
+### Phase 3: Docs Authoring
+
+Delegate the merged context to `docs-keeper` when available. Otherwise follow its verification discipline in the main context.
+
+Authoring rules:
+
+1. Read code before documenting code.
+2. Verify referenced paths, commands, config keys, endpoints, and symbols before naming them.
+3. Record observed conventions as observed; do not turn folder guesses into standards.
+4. Use relative links among docs only after confirming targets exist.
+5. Add unresolved questions to any doc whose important claim is not yet verifiable.
+
+### Phase 4: Size Discipline
+
+After generation:
+
+1. Check markdown LOC in the docs root.
+2. Use `docs.maxLoc` from session/runtime context when provided; default to 800 lines.
+3. If a file crosses the limit:
+   - split on semantic boundaries
+   - make an `index.md` for the topic when a document becomes a folder
+   - keep links from the original entry point
+4. Report any intentionally accepted oversized file.
+
+### Phase 5: Validation And Tracking
+
+1. Run `.claude/scripts/validate-docs.cjs <docs-root>` when available.
+2. Fix broken internal doc links that can be resolved from evidence.
+3. If docs-sync uses `<docs-root>/.sync_hash`, update it only after the docs reflect current source state.
+
+## Required Final Report
+
+Report:
+
+- docs root used
+- source areas scouted
+- files created or updated
+- validation result
+- evidence gaps
+- unresolved questions
+
+Recommended next command:
+
+```text
+/hapo:docs update
+```
+
+after meaningful source changes.