source-kb 0.2.2__py3-none-any.whl

cli/commands/pipeline.py

@@ -0,0 +1,45 @@
+"""source-kb pipeline — Run engine pipelines (init/sync/audit) with LLM integration."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("pipeline", help="Run engine pipelines (requires LLM config)")
+    sub = p.add_subparsers(dest="action")
+
+    p_init = sub.add_parser("init", help="Run full kb-init pipeline")
+    p_init.add_argument("--kb", required=True)
+    p_init.add_argument("--module", default=None)
+    p_init.add_argument("--dry-run", action="store_true")
+    p_init.add_argument("--resume", action="store_true", help="Resume from last checkpoint")
+    p_init.add_argument("--config", help="kb-project.yaml path")
+
+    p_sync = sub.add_parser("sync", help="Run incremental sync pipeline")
+    p_sync.add_argument("--kb", required=True)
+    p_sync.add_argument("--module", default=None)
+    p_sync.add_argument("--dry-run", action="store_true")
+    p_sync.add_argument("--config", help="kb-project.yaml path")
+
+    p_audit = sub.add_parser("audit", help="Run document audit pipeline")
+    p_audit.add_argument("--kb", required=True)
+    p_audit.add_argument("--module", default=None)
+    p_audit.add_argument("--scope", default=None, help="Audit only this doc type")
+    p_audit.add_argument("--dry-run", action="store_true")
+    p_audit.add_argument("--force", action="store_true")
+    p_audit.add_argument("--config", help="kb-project.yaml path")
+
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    if not getattr(args, "action", None):
+        print("Usage: source-kb pipeline {init|sync|audit} --kb <name>", file=sys.stderr)
+        sys.exit(1)
+
+    from engine.main import cmd_init, cmd_sync, cmd_audit
+
+    dispatch = {"init": cmd_init, "sync": cmd_sync, "audit": cmd_audit}
+    dispatch[args.action](args)

cli/commands/post_merge.py

@@ -0,0 +1,43 @@
+"""source-kb post-merge — Post-merge refinement (dedup, terms, anchors)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("post-merge", help="Run post-merge refinement on module docs")
+    p.add_argument("--module-dir", required=True, help="Module directory")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.post_merge import refine_merged_doc
+
+    module_dir = Path(args.module_dir)
+    if not module_dir.is_dir():
+        print(f"Error: directory not found: {module_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    results = {"refined": 0, "unchanged": 0, "errors": []}
+    for md in sorted(module_dir.glob("*.md")):
+        if md.name.startswith(".") or md.name.lower() == "readme.md":
+            continue
+        try:
+            result = refine_merged_doc(md)
+            if result.changed:
+                result.apply()
+                results["refined"] += 1
+                print(f"  {md.name}: {result.summary()}")
+            else:
+                results["unchanged"] += 1
+        except Exception as e:
+            results["errors"].append(f"{md.name}: {e}")
+            print(f"  {md.name}: error - {e}", file=sys.stderr)
+
+    print(json.dumps({"status": "ok", "refined": results["refined"],
+                      "unchanged": results["unchanged"],
+                      "errors": len(results["errors"])}, ensure_ascii=False), file=sys.stderr)

cli/commands/query.py

@@ -0,0 +1,52 @@
+"""source-kb query — Query skeleton data."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("query", help="Query skeleton data (stats, search, file-list)")
+    p.add_argument("subcmd", choices=["stats", "high-methods", "file-list", "method-count", "search"])
+    p.add_argument("path", help="Skeleton JSON path or directory")
+    p.add_argument("query", nargs="?", default="", help="Search query (for search subcmd)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.query import load_skeleton, stats, high_methods, file_list, method_count, search
+
+    path = Path(args.path)
+    entries = load_skeleton(path)
+
+    if args.subcmd == "stats":
+        result = stats(entries)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif args.subcmd == "high-methods":
+        methods = high_methods(entries)
+        for m in methods[:20]:
+            print(f"{m['file']}  {m['method']}  ({m['line_count']} lines)")
+        if len(methods) > 20:
+            print(f"  ... and {len(methods) - 20} more")
+        print(json.dumps({"status": "ok", "count": len(methods)}, ensure_ascii=False), file=sys.stderr)
+    elif args.subcmd == "file-list":
+        files = file_list(entries)
+        print(f"Total files: {len(files)}")
+        for f in files[:30]:
+            print(f"  {f}")
+        if len(files) > 30:
+            print(f"  ... and {len(files) - 30} more")
+        print(json.dumps({"status": "ok", "files": len(files)}, ensure_ascii=False), file=sys.stderr)
+    elif args.subcmd == "method-count":
+        count = method_count(entries)
+        print(json.dumps({"status": "ok", "methods": count}, ensure_ascii=False))
+    elif args.subcmd == "search":
+        results = search(entries, args.query)
+        for r in results[:20]:
+            print(f"[{r['type']}] {r['file']}:{r['line']}  {r['name']}")
+        if len(results) > 20:
+            print(f"  ... and {len(results) - 20} more")
+        print(json.dumps({"status": "ok", "matches": len(results)}, ensure_ascii=False), file=sys.stderr)

cli/commands/render.py

@@ -0,0 +1,101 @@
+"""source-kb render — Render a sub-agent prompt from template."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("render", help="Render a sub-agent prompt from template")
+    p.add_argument("--template", help="Template filename (auto-resolved from doc_types.yaml if omitted)")
+    p.add_argument("--module", required=True, help="Module name")
+    p.add_argument("--config", help="kb-project.yaml path")
+    p.add_argument("--kb", required=True, help="Knowledge base name")
+    p.add_argument("--doc-type", required=True, help="Document type")
+    p.add_argument("--mode", default="readwrite", choices=["readwrite", "output-only"])
+    p.add_argument("--output", help="Output file path")
+    p.add_argument("--extra", nargs="*", help="Extra variables (key=value)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.config import load_config
+    from core.preset import load_preset
+    from core.prompt.renderer import render_prompt
+    from core.prompt.variables import ReferencePromptAssembler
+
+    config = load_config(Path(args.config) if args.config else None)
+    kb_config = config.get_kb(args.kb)
+    preset_name = kb_config.get("preset", "generic")
+    preset = load_preset(preset_name)
+
+    assembler = ReferencePromptAssembler(project_root=Path(".").resolve(), preset=preset)
+
+    template_name = args.template
+    if not template_name:
+        doc_types = preset.get("doc_types", {})
+        dt_cfg = doc_types.get(args.doc_type, {})
+        template_name = dt_cfg.get("template")
+        if not template_name:
+            print(f"Error: no template mapping for doc-type '{args.doc_type}' in {preset_name}/doc_types.yaml. "
+                  f"Specify --template explicitly.", file=sys.stderr)
+            sys.exit(1)
+
+    template_path = _find_template(template_name, preset_name)
+    if not template_path:
+        print(f"Error: template not found: {template_name}", file=sys.stderr)
+        sys.exit(1)
+
+    extras = {}
+    if args.extra:
+        for item in args.extra:
+            if "=" in item:
+                k, v = item.split("=", 1)
+                extras[k] = v
+
+    execution_snippet = ""
+    if args.mode == "readwrite":
+        snippet_path = Path("skills/kb-init/templates/core/readwrite.md")
+        if snippet_path.exists():
+            execution_snippet = snippet_path.read_text(encoding="utf-8")
+    elif args.mode == "output-only":
+        snippet_path = Path("skills/kb-init/templates/core/output-only.md")
+        if snippet_path.exists():
+            execution_snippet = snippet_path.read_text(encoding="utf-8")
+
+    rendered = render_prompt(
+        template_path=template_path,
+        config=config.raw,
+        kb_name=args.kb,
+        module_name=args.module,
+        doc_type=args.doc_type,
+        assembler=assembler,
+        extras=extras,
+        execution_snippet=execution_snippet,
+        preset=preset,
+    )
+
+    if args.output:
+        Path(args.output).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.output).write_text(rendered, encoding="utf-8")
+        print(f"Rendered to: {args.output} ({len(rendered)} chars)")
+    else:
+        meta_prompts = Path(f"knowledge/{args.module}/.meta/prompts")
+        meta_prompts.mkdir(parents=True, exist_ok=True)
+        out_path = meta_prompts / f"{args.doc_type}.md"
+        out_path.write_text(rendered, encoding="utf-8")
+        print(f"Rendered to: {out_path} ({len(rendered)} chars)")
+
+    print(json.dumps({"status": "ok", "chars": len(rendered)}, ensure_ascii=False), file=sys.stderr)
+
+
+def _find_template(template_name: str, preset_name: str) -> Path | None:
+    from core.preset import find_preset_template
+
+    p = Path(template_name)
+    if p.exists():
+        return p
+    return find_preset_template(preset_name, template_name)

cli/commands/scan_repos.py

@@ -0,0 +1,46 @@
+"""source-kb scan-repos — Scan repositories for changes since last baseline."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("scan-repos", help="Scan repositories for changes since last baseline")
+    p.add_argument("--config", help="Path to kb-project.yaml")
+    p.add_argument("--init", action="store_true", help="Initialize state file")
+    p.add_argument("--kb", help="Only scan specified knowledge base")
+    p.add_argument("--module", help="Only scan specified module")
+    p.add_argument("--force", action="store_true", help="Force scan (ignore state file)")
+    p.add_argument("--update-state", action="store_true", help="Update baseline commit in state")
+    p.add_argument("--batch-update", action="store_true", help="Batch update all baselines to latest")
+    p.add_argument("--commit", help="Commit hash (for --update-state)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+    from skills.kb_sync.scripts.scan_repos import main as scan_main
+
+    argv = []
+    if args.config:
+        argv += ["--config", args.config]
+    if args.init:
+        argv.append("--init")
+    if args.kb:
+        argv += ["--kb", args.kb]
+    if args.module:
+        argv += ["--module", args.module]
+    if args.force:
+        argv.append("--force")
+    if args.update_state:
+        argv.append("--update-state")
+    if args.batch_update:
+        argv.append("--batch-update")
+    if args.commit:
+        argv += ["--commit", args.commit]
+
+    sys.argv = ["source-kb scan-repos"] + argv
+    scan_main()

cli/commands/setup.py

@@ -0,0 +1,94 @@
+"""source-kb setup — Project setup and agent configuration."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("setup", help="Set up source-kb for a project")
+    p.add_argument("--agent", choices=["claude", "kiro", "generic"],
+                   default="claude", help="Target agent platform")
+    p.add_argument("--preset", default="java-spring", help="Preset to use")
+    p.add_argument("--project-dir", default=".", help="Project root directory")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    project_dir = Path(args.project_dir).resolve()
+
+    config_path = project_dir / "kb-project.yaml"
+    if config_path.exists():
+        print(f"kb-project.yaml already exists at {config_path}")
+        print("Use 'source-kb init' to regenerate, or edit manually.")
+        sys.exit(0)
+
+    config_template = {
+        "version": "1.0",
+        "knowledge_bases": {
+            "my-kb": {
+                "preset": args.preset,
+                "knowledge_dir": "./knowledge",
+                "collection": "my-kb-index",
+                "source": {
+                    "cache_dir": "./.source-cache",
+                    "repos": [
+                        {
+                            "name": "my-service",
+                            "url": "https://github.com/org/my-service.git",
+                            "branch": "main",
+                            "type": "service",
+                        }
+                    ],
+                },
+            }
+        },
+    }
+
+    import yaml
+    config_path.write_text(
+        yaml.dump(config_template, default_flow_style=False, allow_unicode=True, sort_keys=False),
+        encoding="utf-8",
+    )
+    print(f"Created: {config_path}")
+
+    if args.agent == "claude":
+        _setup_claude_skills(project_dir)
+    elif args.agent == "kiro":
+        _setup_kiro_skills(project_dir)
+
+    print(f"\nSetup complete. Edit kb-project.yaml to configure your repositories.")
+    print(json.dumps({"status": "ok", "agent": args.agent, "preset": args.preset},
+                     ensure_ascii=False), file=sys.stderr)
+
+
+def _setup_claude_skills(project_dir: Path) -> None:
+    claude_md = project_dir / "CLAUDE.md"
+    if claude_md.exists():
+        print(f"  CLAUDE.md already exists, skipping")
+        return
+    content = (
+        "# source-kb\n\n"
+        "This project uses source-kb for knowledge base generation.\n\n"
+        "## Available commands\n\n"
+        "```\n"
+        "source-kb extract --repo <path> --preset <preset>\n"
+        "source-kb dispatch --kb <name> --module <module>\n"
+        "source-kb render --kb <name> --module <module> --doc-type <type>\n"
+        "source-kb merge --dir <module-dir>\n"
+        "source-kb validate --module-dir <dir> --preset <preset>\n"
+        "source-kb index --kb <name>\n"
+        "source-kb search --kb <name> <query>\n"
+        "```\n"
+    )
+    claude_md.write_text(content, encoding="utf-8")
+    print(f"  Created: CLAUDE.md")
+
+
+def _setup_kiro_skills(project_dir: Path) -> None:
+    kiro_dir = project_dir / ".kiro"
+    kiro_dir.mkdir(exist_ok=True)
+    print(f"  Created: .kiro/ (add steering docs as needed)")

cli/commands/split.py

@@ -0,0 +1,196 @@
+"""source-kb split-files / split-apply — Shard splitting for large doc types."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("split-files", help="Generate shard file lists for a doc type")
+    p.add_argument("--config", help="kb-project.yaml path")
+    p.add_argument("--kb", required=True, help="Knowledge base name")
+    p.add_argument("--module", required=True, help="Module name")
+    p.add_argument("--doc-type", required=True, help="Document type to split")
+    p.add_argument("--mode", default="readwrite", choices=["readwrite", "output-only"])
+    p.set_defaults(func=run_split_files)
+
+    p = subparsers.add_parser("split-apply", help="Validate and apply Agent-provided grouping")
+    p.add_argument("--module-dir", required=True, help="Module knowledge directory")
+    p.add_argument("--doc-type", required=True, help="Document type")
+    p.add_argument("--groups", required=True, help="Path to groups JSON file (Agent output)")
+    p.set_defaults(func=run_split_apply)
+
+
+def run_split_files(args: argparse.Namespace) -> None:
+    from core.config import load_config
+    from core.preset import load_preset, get_doc_type_mapping
+    from core.skeleton.split import SplitConfig
+    from core.skeleton.split_plan import plan_splits
+    from core.skeleton.dispatch import get_file_list_with_stats
+    from core.skeleton.file_list import load_skeleton as load_skeleton_entries
+    from core.paths import file_list_dir
+
+    config = load_config(Path(args.config) if args.config else None)
+    kb_config = config.get_kb(args.kb)
+    preset_name = kb_config.get("preset", "generic")
+    preset = load_preset(preset_name)
+
+    knowledge_dir = Path(kb_config["knowledge_dir"])
+    source = kb_config.get("source", {})
+    cache_dir = Path(source.get("cache_dir", "./.source-cache"))
+
+    module_name = args.module
+    module_dir = knowledge_dir / module_name
+
+    if source.get("structure") == "monorepo":
+        repo_name = source.get("repo_name", "repo")
+        module_cfg = next((m for m in source.get("modules", []) if m["name"] == module_name), {})
+        module_path = module_cfg.get("path", module_name)
+        source_cache = cache_dir / repo_name / module_path
+    else:
+        source_cache = cache_dir / module_name
+
+    doc_type = args.doc_type
+    dt_mapping = get_doc_type_mapping(preset)
+    split_config = SplitConfig.from_preset(preset, mode=args.mode)
+
+    files = get_file_list_with_stats(module_dir, doc_type, source_cache, dt_mapping)
+    if not files:
+        print(f"No files found for doc-type '{doc_type}'", file=sys.stderr)
+        sys.exit(1)
+
+    entries = load_skeleton_entries(module_dir)
+    plan = plan_splits(
+        entries=entries, file_list=files, split_config=split_config,
+        doc_type=doc_type, module_dir=module_dir,
+    )
+
+    if plan.recommended_agents <= 1:
+        print(f"No split needed for {doc_type} (strategy: {plan.strategy})")
+        print(json.dumps({"status": "ok", "splits": 1, "strategy": plan.strategy},
+                         ensure_ascii=False), file=sys.stderr)
+        return
+
+    fl_dir = file_list_dir(module_dir)
+    fl_dir.mkdir(parents=True, exist_ok=True)
+
+    for old_file in fl_dir.glob(f"{doc_type}-*.txt"):
+        old_file.unlink()
+
+    shard_info = []
+    name_to_rel = {f.get("name", ""): f.get("rel_path", f.get("name", "")) for f in files}
+
+    for i, split in enumerate(plan.splits, 1):
+        shard_name = split.get("name", f"shard-{i}")
+        if len(shard_name) > 30 or "/" in shard_name:
+            shard_name = f"shard-{i}"
+        safe_name = shard_name.replace("/", "_").replace("\\", "_").replace(" ", "-").replace(":", "")
+        if len(safe_name) > 30:
+            safe_name = safe_name[:30]
+
+        shard_file = fl_dir / f"{doc_type}-{safe_name}.txt"
+        shard_files = split.get("files", [])
+        lines_out = [name_to_rel.get(fname, fname) for fname in shard_files]
+        shard_file.write_text("\n".join(lines_out) + "\n", encoding="utf-8")
+        shard_info.append({"shard_name": safe_name, "file_count": len(lines_out), "lines": split.get("lines", 0)})
+
+    print(f"Split {doc_type} into {len(plan.splits)} shards (strategy: {plan.strategy})")
+    for i, info in enumerate(shard_info, 1):
+        print(f"  {i}. {info['shard_name']} ({info['file_count']} files, {info['lines']} lines)")
+
+    print(json.dumps({"status": "ok", "doc_type": doc_type, "splits": len(plan.splits),
+                      "strategy": plan.strategy}, ensure_ascii=False), file=sys.stderr)
+
+
+def run_split_apply(args: argparse.Namespace) -> None:
+    module_dir = Path(args.module_dir)
+    doc_type = args.doc_type
+    groups_path = Path(args.groups)
+
+    if not groups_path.exists():
+        print(json.dumps({"status": "error", "message": f"Groups file not found: {groups_path}"}))
+        sys.exit(1)
+
+    request_path = module_dir / ".meta" / "split-requests" / f"{doc_type}-grouping-request.json"
+    if not request_path.exists():
+        print(json.dumps({"status": "error", "message": f"No grouping request found: {request_path}"}))
+        sys.exit(1)
+
+    request = json.loads(request_path.read_text(encoding="utf-8"))
+    constraints = request["constraints"]
+    all_files = {f["name"] for f in request["files"]}
+    file_lookup = {f["name"]: f for f in request["files"]}
+
+    groups = json.loads(groups_path.read_text(encoding="utf-8"))
+    if not isinstance(groups, list):
+        print(json.dumps({"status": "error", "message": "Groups must be a JSON array"}))
+        sys.exit(1)
+
+    errors: list[str] = []
+    assigned: set[str] = set()
+    group_stats: list[dict] = []
+
+    for i, g in enumerate(groups):
+        name = g.get("name", f"group-{i+1}")
+        files = g.get("files", [])
+        resolved: list[str] = []
+        for fname in files:
+            if fname in all_files:
+                resolved.append(fname)
+            else:
+                matches = [f for f in all_files if f.endswith(fname)]
+                if matches:
+                    resolved.append(matches[0])
+                else:
+                    errors.append(f"Group '{name}': unknown file '{fname}'")
+        for f in resolved:
+            if f in assigned:
+                errors.append(f"Group '{name}': duplicate file '{f}'")
+            assigned.add(f)
+        lines = sum(file_lookup.get(f, {}).get("lines", 0) for f in resolved)
+        group_stats.append({"name": name, "files": resolved, "file_count": len(resolved), "lines": lines})
+
+    missing = all_files - assigned
+    if missing and constraints.get("all_files_must_be_assigned", True):
+        errors.append(f"{len(missing)} files not assigned: {sorted(missing)[:5]}...")
+
+    max_files = constraints.get("max_files_per_group", 80)
+    max_lines = constraints.get("max_lines_per_group", 10000)
+    max_ratio = constraints.get("max_imbalance_ratio", 3.0)
+
+    for gs in group_stats:
+        if gs["file_count"] > max_files:
+            errors.append(f"Group '{gs['name']}': {gs['file_count']} files > max {max_files}")
+        if gs["lines"] > max_lines:
+            errors.append(f"Group '{gs['name']}': {gs['lines']} lines > max {max_lines}")
+
+    if group_stats:
+        line_counts = [gs["lines"] for gs in group_stats if gs["lines"] > 0]
+        if line_counts and max(line_counts) / max(min(line_counts), 1) > max_ratio:
+            errors.append(f"Imbalance ratio {max(line_counts)/max(min(line_counts),1):.1f}x > {max_ratio}x")
+
+    if errors:
+        print(json.dumps({"status": "error", "errors": errors}, ensure_ascii=False))
+        sys.exit(1)
+
+    shards_dir = module_dir / ".meta" / "shards"
+    shards_dir.mkdir(parents=True, exist_ok=True)
+
+    for i, gs in enumerate(group_stats, 1):
+        shard_path = shards_dir / f"{doc_type}-shard-{i:02d}.txt"
+        rel_paths = []
+        for fname in gs["files"]:
+            entry = file_lookup.get(fname, {})
+            rel_paths.append(entry.get("rel_path", fname) if "rel_path" in entry else fname)
+        shard_path.write_text("\n".join(rel_paths) + "\n", encoding="utf-8")
+
+    request_path.unlink(missing_ok=True)
+
+    print(json.dumps({
+        "status": "ok", "doc_type": doc_type, "shards": len(group_stats),
+        "groups": [{"name": gs["name"], "file_count": gs["file_count"], "lines": gs["lines"]}
+                   for gs in group_stats],
+    }, ensure_ascii=False))

cli/commands/stale_files.py

@@ -0,0 +1,98 @@
+"""source-kb stale-files — Detect stale/orphaned documentation files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("stale-files", help="Detect stale docs not in dispatch plan")
+    p.add_argument("--config", help="kb-project.yaml path")
+    p.add_argument("--kb", required=True, help="Knowledge base name")
+    p.add_argument("--module", required=True, help="Module name")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.config import load_config
+    from core.preset import load_preset, get_doc_type_mapping
+    from core.skeleton.dispatch import compute_dispatch_plan
+
+    config = load_config(Path(args.config) if args.config else None)
+    kb_config = config.get_kb(args.kb)
+    preset_name = kb_config.get("preset", "generic")
+    preset = load_preset(preset_name)
+
+    knowledge_dir = Path(kb_config["knowledge_dir"])
+    source = kb_config.get("source", {})
+    cache_dir = Path(source.get("cache_dir", "./.source-cache"))
+
+    module_name = args.module
+    module_dir = knowledge_dir / module_name
+
+    if source.get("structure") == "monorepo":
+        repo_name = source.get("repo_name", "repo")
+        module_cfg = next((m for m in source.get("modules", []) if m["name"] == module_name), {})
+        module_path = module_cfg.get("path", module_name)
+        source_cache = cache_dir / repo_name / module_path
+    else:
+        source_cache = cache_dir / module_name
+
+    module_type = "service"
+    repos = source.get("repos", [])
+    for repo in repos:
+        if repo.get("name") == module_name:
+            module_type = repo.get("type", "service")
+            break
+
+    plan = compute_dispatch_plan(
+        preset=preset, module_dir=module_dir, source_cache=source_cache,
+        mode="readwrite", module_name=module_name, module_type=module_type,
+    )
+
+    expected_files = {e.doc_filename for e in plan.entries}
+    doc_types_cfg = preset.get("doc_types", {})
+    for dt_key, dt_config in doc_types_cfg.items():
+        if isinstance(dt_config, dict) and not dt_config.get("conditional", True):
+            expected_files.add(dt_config.get("filename", f"{dt_key}.md"))
+
+    existing_files: list[Path] = []
+    if module_dir.is_dir():
+        existing_files = [f for f in module_dir.glob("*.md")
+                         if not f.name.startswith(".") and f.name.lower() != "readme.md"]
+
+    stale: list[dict] = []
+    doc_type_filenames = set(get_doc_type_mapping(preset).values())
+    module_types_config = preset.get("module_types", {})
+    type_config = module_types_config.get(module_type, {})
+    skip_docs = set(type_config.get("skip", []))
+
+    for f in existing_files:
+        if f.name not in expected_files:
+            mtime = f.stat().st_mtime
+            mtime_str = time.strftime("%Y-%m-%d %H:%M", time.localtime(mtime))
+            size_kb = round(f.stat().st_size / 1024, 1)
+
+            reason = "not in current dispatch plan"
+            if f.name in skip_docs:
+                reason = f"skipped for {module_type} module type"
+            elif f.name in doc_type_filenames:
+                reason = "file classification did not trigger this doc"
+
+            stale.append({"file": f.name, "size_kb": size_kb, "last_modified": mtime_str, "reason": reason})
+
+    if stale:
+        print(f"Found {len(stale)} stale/orphaned files:\n")
+        print("| File | Size | Last Modified | Reason |")
+        print("|------|------|---------------|--------|")
+        for s in stale:
+            print(f"| {s['file']} | {s['size_kb']}KB | {s['last_modified']} | {s['reason']} |")
+    else:
+        print("No stale files found. All docs are in the dispatch plan.")
+
+    print(json.dumps({"status": "ok", "stale_count": len(stale),
+                      "stale_files": [s["file"] for s in stale]}, ensure_ascii=False), file=sys.stderr)