source-kb 0.2.2__py3-none-any.whl

core/skeleton/__main__.py

@@ -0,0 +1,934 @@
+"""CLI entry points for core/skeleton tools.
+
+Provides sub-commands for Agent mode to call directly:
+    python -m core.skeleton extract ...
+    python -m core.skeleton query ...
+    python -m core.skeleton file-list ...
+    python -m core.skeleton metadata ...
+    python -m core.skeleton dispatch-preview ...
+    python -m core.skeleton module-dag ...
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.stdout.reconfigure(encoding="utf-8")
+
+
+def _resolve_doc_type_files(preset: dict, doc_type: str) -> list[str] | None:
+    """Resolve which file classification categories are relevant to a doc type.
+
+    Returns None if doc_type is invalid (not in doc_types.yaml).
+    Returns empty list if valid but no categories map to it.
+    Note: This returns category names, not actual file paths — the extract
+    function uses the `files` param to filter after full extraction.
+    """
+    doc_types = preset.get("doc_types", {})
+    if doc_type not in doc_types:
+        return None
+
+    # Get the filename for this doc type
+    dt_config = doc_types[doc_type]
+    if not isinstance(dt_config, dict):
+        return []
+    target_filename = dt_config.get("filename", f"{doc_type}.md")
+
+    # Reverse lookup: find classification categories whose 'affects' includes this filename
+    classification = preset.get("file_classification", {})
+    # We can't resolve actual file paths without a skeleton, so return None
+    # to indicate "use full extraction then filter" — the --doc param is mainly
+    # a validation + documentation feature for now
+    return []  # Empty means "don't filter" — full extract, doc_type noted in output
+
+
+def cmd_extract(args: argparse.Namespace) -> None:
+    """Extract skeleton from repository."""
+    from core.skeleton.extract import extract_skeleton
+    from core.preset import load_preset
+
+    preset = load_preset(args.preset)
+    repo_path = Path(args.repo)
+    output_dir = Path(args.output) if args.output else None
+
+    # Handle --doc parameter: filter to files relevant to a doc type
+    files_filter = getattr(args, "files", None)
+    doc_filter = getattr(args, "doc", None)
+    if doc_filter and not files_filter:
+        doc_files = _resolve_doc_type_files(preset, doc_filter)
+        if doc_files is None:
+            # Invalid doc type
+            doc_types = list(preset.get("doc_types", {}).keys())
+            print(f"Error: unknown doc type '{doc_filter}'. Valid: {', '.join(doc_types)}",
+                  file=sys.stderr)
+            sys.exit(1)
+        files_filter = doc_files if doc_files else None
+
+    entries = extract_skeleton(
+        repo_path, preset,
+        ref=args.ref or "HEAD",
+        subpath=getattr(args, "subpath", None),
+        output_dir=output_dir,
+        split_by_package=args.split_by_package,
+        compact=not args.no_compact,
+        files=files_filter,
+    )
+
+    result = {"status": "ok", "files": len(entries),
+              "methods": sum(len(e.get("methods", [])) for e in entries),
+              "classes": sum(len(e.get("classes", [])) for e in entries)}
+    if doc_filter:
+        result["doc_filter"] = doc_filter
+
+    if args.summary and output_dir:
+        result["summary"] = str(output_dir / ".meta" / "skeleton-summary.json")
+
+    if not output_dir:
+        # No output dir: write to default location instead of flooding stdout
+        default_out = repo_path / ".meta" / "skeleton"
+        default_out.mkdir(parents=True, exist_ok=True)
+        skel_file = default_out / "skeleton.json"
+        skel_file.write_text(json.dumps(entries, ensure_ascii=False, indent=1), encoding="utf-8")
+        result["output"] = str(skel_file)
+        print(f"Extracted to: {skel_file}")
+    print(json.dumps(result, ensure_ascii=False), file=sys.stderr)
+
+
+def cmd_query(args: argparse.Namespace) -> None:
+    """Query skeleton data."""
+    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))
+    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)
+
+
+def cmd_file_list(args: argparse.Namespace) -> None:
+    """Extract file list for a doc type."""
+    from core.skeleton.file_list import load_skeleton, extract_file_list, check_coverage
+    from core.preset import load_preset
+
+    preset = load_preset(args.preset)
+    module_dir = Path(args.module_dir) if args.module_dir else None
+    skeleton_path = Path(args.skeleton) if args.skeleton else None
+
+    # Load skeleton
+    if skeleton_path:
+        from core.skeleton.query import load_skeleton as ql
+        entries = ql(skeleton_path)
+    elif module_dir:
+        entries = load_skeleton(module_dir)
+    else:
+        print("Error: --skeleton or --module-dir required", file=sys.stderr)
+        sys.exit(1)
+
+    source_cache = Path(args.source_cache) if args.source_cache else Path(".")
+
+    if args.coverage_check:
+        from core.paths import file_list_dir
+        fl_dir = file_list_dir(module_dir) if module_dir else None
+        report = check_coverage(entries, preset, fl_dir)
+        print(f"Coverage: {report.coverage_pct:.1f}% ({report.covered}/{report.total_files})")
+        if report.uncovered_files:
+            print(f"Uncovered ({report.uncovered_count}):")
+            for f in report.uncovered_files[:20]:
+                print(f"  {f}")
+        output = args.output
+        if output:
+            Path(output).parent.mkdir(parents=True, exist_ok=True)
+            Path(output).write_text(
+                "\n".join(report.uncovered_files), encoding="utf-8"
+            )
+        print(json.dumps({"status": "ok", "coverage_pct": round(report.coverage_pct, 1),
+                          "uncovered": report.uncovered_count}, ensure_ascii=False), file=sys.stderr)
+        return
+
+    files = extract_file_list(entries, preset, args.doc_type, source_cache)
+    if args.output:
+        Path(args.output).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.output).write_text("\n".join(files) + "\n", encoding="utf-8")
+        print(f"Written {len(files)} files to: {args.output}")
+    elif module_dir and args.doc_type:
+        from core.paths import file_list_dir
+        fl_dir = file_list_dir(module_dir)
+        fl_dir.mkdir(parents=True, exist_ok=True)
+        out_path = fl_dir / f"{args.doc_type}.txt"
+        out_path.write_text("\n".join(files) + "\n", encoding="utf-8")
+        print(f"Written {len(files)} files to: {out_path}")
+    else:
+        for f in files:
+            print(f)
+    print(json.dumps({"status": "ok", "files": len(files)}, ensure_ascii=False), file=sys.stderr)
+
+
+def cmd_metadata(args: argparse.Namespace) -> None:
+    """Pre-generate global metadata."""
+    from core.skeleton.metadata import pregenerate
+
+    module_dir = Path(args.module_dir)
+    output = pregenerate(module_dir, module_name=args.module_name or module_dir.name)
+    print(f"Generated: {output}")
+    print(json.dumps({"status": "ok", "output": str(output)}, ensure_ascii=False), file=sys.stderr)
+
+
+def cmd_dispatch_preview(args: argparse.Namespace) -> None:
+    """Generate dispatch plan preview and write .meta/dispatch-plan.md + dispatch-tasks.json."""
+    from core.config import load_config
+    from core.preset import load_preset
+    from core.skeleton.dispatch import compute_dispatch_plan
+    from core.skeleton.dispatch_render import render_markdown, plan_to_tasks
+
+    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
+    source_cache = cache_dir / module_name
+
+    # Resolve module_type from kb-project.yaml repos config
+    module_type = "service"
+    repos = source.get("repos", [])
+    for repo in repos:
+        if repo.get("name") == module_name:
+            module_type = repo.get("type", "service")
+            break
+
+    mode = args.mode or "readwrite"
+
+    plan = compute_dispatch_plan(
+        preset=preset, module_dir=module_dir, source_cache=source_cache,
+        mode=mode, module_name=module_name,
+        module_type=module_type,
+    )
+
+    markdown = render_markdown(plan, mode=mode)
+
+    # Write dispatch-plan.md and dispatch-tasks.json to .meta/
+    meta_dir = module_dir / ".meta"
+    meta_dir.mkdir(parents=True, exist_ok=True)
+    (meta_dir / "dispatch-plan.md").write_text(markdown, encoding="utf-8")
+
+    tasks = plan_to_tasks(
+        plan=plan, kb_name=args.kb, preset_name=preset_name,
+        preset=preset, knowledge_dir=knowledge_dir, mode=mode,
+    )
+    (meta_dir / "dispatch-tasks.json").write_text(
+        json.dumps(tasks, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+
+    # Write shard file lists for split entries
+    from core.skeleton.dispatch_render import write_shard_files
+    write_shard_files(plan, module_dir)
+
+    # Print compact summary to stdout (full plan is in dispatch-plan.md)
+    print(f"Dispatch plan: {len(plan.entries)} doc types, {plan.total_shards()} shards (mode={mode})")
+    print(f"  Written to: {meta_dir / 'dispatch-plan.md'}")
+    print(f"  Tasks JSON: {meta_dir / 'dispatch-tasks.json'}")
+    for e in plan.entries:
+        shards_str = f" x{e.split_count}" if e.split_count > 1 else ""
+        print(f"  - {e.doc_type} ({e.file_count} files, {e.total_lines} lines){shards_str}")
+
+    print(json.dumps({"status": "ok", "entries": len(plan.entries),
+                      "total_shards": plan.total_shards()}, ensure_ascii=False), file=sys.stderr)
+
+
+def cmd_module_dag(args: argparse.Namespace) -> None:
+    """Build and display module dependency DAG."""
+    from core.skeleton.module_dag import build_module_dag, topo_sort_modules, get_generation_layers
+
+    source_cache = Path(args.source_cache)
+    modules = args.modules.split(",")
+
+    dag = build_module_dag(source_cache, modules)
+    order = topo_sort_modules(dag)
+    layers = get_generation_layers(dag)
+
+    print("Module generation order (dependencies first):")
+    for i, name in enumerate(order, 1):
+        deps = dag.edges.get(name, set())
+        dep_str = f" (depends on: {', '.join(sorted(deps))})" if deps else ""
+        print(f"  {i}. {name}{dep_str}")
+
+    print(f"\nParallel layers:")
+    for i, layer in enumerate(layers, 1):
+        print(f"  Layer {i}: {', '.join(layer)}")
+
+    print(json.dumps({"status": "ok", "modules": len(modules),
+                      "order": order, "layers": layers}, ensure_ascii=False), file=sys.stderr)
+
+
+def cmd_post_merge(args: argparse.Namespace) -> None:
+    """Run post-merge refinement on all docs in a module directory."""
+    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
+                print(f"  — {md.name}: No fixes needed")
+        except Exception as e:
+            results["errors"].append(f"{md.name}: {e}")
+            print(f"  ❌ {md.name}: {e}")
+
+    print(json.dumps({"status": "ok", "refined": results["refined"],
+                      "unchanged": results["unchanged"],
+                      "errors": len(results["errors"])}, ensure_ascii=False), file=sys.stderr)
+
+
+def cmd_audit(args: argparse.Namespace) -> None:
+    """Run low-confidence classification audit on skeleton entries."""
+    from core.skeleton.classify import find_suspicious_files
+    from core.preset import load_preset
+    from core.skeleton.query import load_skeleton
+
+    preset = load_preset(args.preset)
+    skeleton_path = Path(args.skeleton)
+    entries = load_skeleton(skeleton_path)
+    threshold = args.threshold
+
+    suspicious = find_suspicious_files(entries, preset, threshold=threshold)
+
+    if suspicious:
+        print(f"⚠️ Found {len(suspicious)} low-confidence files (threshold < {threshold}):\n")
+        print("| File | Category | Confidence | Match Reason | Suspicious Signal |")
+        print("|------|------|--------|---------|---------|")
+        for entry in suspicious:
+            cats = ", ".join(entry.categories) if entry.categories else "—"
+            reasons = "; ".join(entry.match_reasons[:2]) if entry.match_reasons else "—"
+            signals = "; ".join(entry.suspicious_signals[:2]) if entry.suspicious_signals else "—"
+            print(f"| {entry.file} | {cats} | {entry.confidence:.2f} | {reasons} | {signals} |")
+    else:
+        print(f"✅ No low-confidence files (threshold < {threshold})")
+
+    print(json.dumps({"status": "ok", "suspicious": len(suspicious),
+                      "threshold": threshold}, ensure_ascii=False), file=sys.stderr)
+
+
+def cmd_record_feedback(args: argparse.Namespace) -> None:
+    """Record split execution feedback for adaptive tuning."""
+    from core.skeleton.split_feedback import SplitRecord, record_split_result
+
+    module_dir = Path(args.module_dir)
+    record = SplitRecord(
+        doc_type=args.doc_type,
+        strategy=args.strategy,
+        resolution=args.resolution,
+        n_splits=args.n_splits,
+        coverage_score=args.coverage_score,
+        quality_score=args.quality_score,
+    )
+    record_split_result(module_dir, record)
+    print(f"✅ Feedback recorded: {args.doc_type} ({args.strategy}, {args.n_splits} splits, "
+          f"score={record.composite_score:.3f})")
+    print(json.dumps({"status": "ok", "doc_type": args.doc_type,
+                      "composite_score": record.composite_score}, ensure_ascii=False), file=sys.stderr)
+
+
+def _find_common_prefix(strings: list[str]) -> str:
+    """Find the longest common prefix of a list of dot-separated package names."""
+    if not strings:
+        return ""
+    if len(strings) == 1:
+        parts = strings[0].split(".")
+        return ".".join(parts[:-1]) + "." if len(parts) > 1 else ""
+    prefix = strings[0]
+    for s in strings[1:]:
+        while not s.startswith(prefix):
+            if "." in prefix:
+                prefix = prefix[:prefix.rfind(".") + 1]
+            else:
+                prefix = ""
+                break
+    return prefix
+
+
+def cmd_split_files(args: argparse.Namespace) -> None:
+    """Generate shard file lists for a doc type that needs splitting.
+
+    Reads the full file list for a doc-type, runs plan_splits() to compute
+    the split plan (community detection → package → simple), and writes
+    per-shard file lists to .meta/file-lists/{doc_type}-{shard_name}.txt.
+
+    This is the missing step between dispatch-preview (which only computes
+    split_count) and prompt rendering (which needs per-shard file lists).
+    """
+    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
+
+    # Resolve source_cache (monorepo vs multi-repo)
+    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
+    mode = args.mode or "readwrite"
+
+    dt_mapping = get_doc_type_mapping(preset)
+    split_config = SplitConfig.from_preset(preset, mode=mode)
+
+    # Get file list with stats (path, lines, bytes)
+    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)
+        print(json.dumps({"status": "error", "message": f"No files for {doc_type}"},
+                         ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)
+
+    # Load skeleton entries for dependency analysis (community detection)
+    entries = load_skeleton_entries(module_dir)
+
+    # Run split planning
+    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,
+                          "message": "no split needed"}, ensure_ascii=False), file=sys.stderr)
+        return
+
+    # Write shard file lists (clean old shards first)
+    fl_dir = file_list_dir(module_dir)
+    fl_dir.mkdir(parents=True, exist_ok=True)
+
+    # Remove old shard files for this doc_type
+    for old_file in fl_dir.glob(f"{doc_type}-*.txt"):
+        old_file.unlink()
+
+    shard_info = []
+    for i, split in enumerate(plan.splits, 1):
+        shard_name = split.get("name", f"shard-{i}")
+        # If name looks like a path or is too long, derive from package info
+        if len(shard_name) > 40 or "/" in shard_name or "\\" in shard_name or ":" in shard_name:
+            # Use the last meaningful package segment from files in this split
+            pkgs = split.get("packages", [])
+            if pkgs:
+                # Find the distinguishing part of the package
+                common_prefix = _find_common_prefix(pkgs)
+                unique_parts = set()
+                for pkg in pkgs:
+                    suffix = pkg[len(common_prefix):].strip(".")
+                    if suffix:
+                        unique_parts.add(suffix.split(".")[0])
+                if unique_parts:
+                    shard_name = "-".join(sorted(unique_parts)[:3])
+                else:
+                    shard_name = pkgs[0].split(".")[-1] if pkgs[0] else f"shard-{i}"
+            else:
+                shard_name = f"shard-{i}"
+        # Sanitize shard name for filename
+        safe_name = shard_name.replace("/", "_").replace("\\", "_").replace(" ", "-").replace(":", "")
+        # Truncate if still too long
+        if len(safe_name) > 30:
+            safe_name = safe_name[:30]
+        shard_file = fl_dir / f"{doc_type}-{safe_name}.txt"
+
+        # Write file paths (use rel_path if available, else name)
+        shard_files = split.get("files", [])
+        # Resolve back to relative paths from the original file list
+        name_to_rel = {f.get("name", ""): f.get("rel_path", f.get("name", "")) for f in files}
+        lines_out = []
+        for fname in shard_files:
+            rel = name_to_rel.get(fname, fname)
+            lines_out.append(rel)
+
+        shard_file.write_text("\n".join(lines_out) + "\n", encoding="utf-8")
+        shard_info.append({
+            "shard_name": safe_name,
+            "file": str(shard_file),
+            "file_count": len(lines_out),
+            "lines": split.get("lines", 0),
+        })
+
+    # Print summary
+    print(f"✅ Split {doc_type} into {len(plan.splits)} shards (strategy: {plan.strategy})")
+    print()
+    print(f"| # | Shard Name | Files | Lines | File List |")
+    print(f"|---|-----------|-------|-------|-----------|")
+    for i, info in enumerate(shard_info, 1):
+        rel_file = Path(info["file"]).relative_to(Path.cwd()) if Path(info["file"]).is_absolute() else info["file"]
+        print(f"| {i} | {info['shard_name']} | {info['file_count']} | {info['lines']} | {rel_file} |")
+
+    if plan.warnings:
+        print(f"\n⚠️ Warnings:")
+        for w in plan.warnings:
+            print(f"  - {w}")
+
+    print(json.dumps({
+        "status": "ok",
+        "doc_type": doc_type,
+        "splits": len(plan.splits),
+        "strategy": plan.strategy,
+        "shards": shard_info,
+    }, ensure_ascii=False), file=sys.stderr)
+
+
+def cmd_split_apply(args: argparse.Namespace) -> None:
+    """Validate and apply Agent-provided grouping result.
+
+    Reads the Agent's grouping JSON, validates against constraints from the
+    original grouping request, and writes shard file lists to .meta/shards/.
+    """
+    import json
+
+    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)
+
+    # Load grouping request for constraints
+    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"]}
+
+    # Load Agent's grouping result
+    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)
+
+    # Validate
+    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", [])
+
+        # Resolve file names (Agent may use short names)
+        resolved: list[str] = []
+        for fname in files:
+            if fname in all_files:
+                resolved.append(fname)
+            else:
+                # Try suffix match
+                matches = [f for f in all_files if f.endswith(fname) or f == fname]
+                if matches:
+                    resolved.append(matches[0])
+                else:
+                    errors.append(f"Group '{name}': unknown file '{fname}'")
+
+        # Check duplicates
+        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})
+
+    # Check all files assigned
+    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]}...")
+
+    # Check per-group constraints
+    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}")
+
+    # Check imbalance
+    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)
+
+    # Write shard files
+    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"
+        # Write file paths (relative to source-cache)
+        # Look up rel_path from request files
+        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")
+
+    # Clean up request file
+    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))
+
+
+def cmd_diff_doc(args: argparse.Namespace) -> None:
+    """Compare document against skeleton to find inconsistencies."""
+    from core.skeleton.cmd_diff_doc import cmd_diff_doc as _impl
+    _impl(args)
+
+
+def cmd_lock(args: argparse.Namespace) -> None:
+    """Unified lock management for both Agent and CLI modes."""
+    from core.skeleton.cmd_lock import cmd_lock as _impl
+    _impl(args)
+
+
+def _is_stale_lock(lock_meta_path: Path) -> bool:
+    """Check if a lock is stale (>30 minutes old). Delegated to cmd_lock module."""
+    from core.skeleton.cmd_lock import _is_stale_lock as _impl
+    return _impl(lock_meta_path)
+
+
+def cmd_anchor_fix(args: argparse.Namespace) -> None:
+    """Fix broken cross-document anchor links."""
+    from core.skeleton.cmd_anchor_fix import cmd_anchor_fix as _impl
+    _impl(args)
+
+
+def cmd_merge_delta(args: argparse.Namespace) -> None:
+    """Merge skeleton delta into existing skeleton."""
+    from core.skeleton.cmd_merge_delta import cmd_merge_delta as _impl
+    _impl(args)
+
+
+def cmd_stale_files(args: argparse.Namespace) -> None:
+    """Detect stale/orphaned documentation files not in the current dispatch plan."""
+    from core.config import load_config
+    from core.preset import load_preset
+    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
+
+    # Resolve source_cache (monorepo vs multi-repo)
+    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
+
+    # Resolve module_type
+    module_type = "service"
+    repos = source.get("repos", [])
+    for repo in repos:
+        if repo.get("name") == module_name:
+            module_type = repo.get("type", "service")
+            break
+
+    # Get dispatch plan to know expected files
+    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}
+    # Add all non-conditional (always-generated) doc types from preset
+    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"))
+
+    # Scan existing .md files
+    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"]
+
+    # Find stale files
+    stale: list[dict] = []
+    from core.preset import get_doc_type_mapping
+    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:
+            import time
+            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)
+
+            # Determine likely reason
+            reason = "Not in current dispatch plan"
+            if f.name in skip_docs:
+                reason = f"Doc type skipped for {module_type} modules"
+            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,
+            })
+
+    # Output
+    if stale:
+        print(f"⚠️ Detected {len(stale)} stale/orphaned files:\n")
+        print("| File | Size | Last Modified | Likely Reason |")
+        print("|------|------|---------|---------|")
+        for s in stale:
+            print(f"| {s['file']} | {s['size_kb']}KB | {s['last_modified']} | {s['reason']} |")
+        print("\nRecommended actions:")
+        print("  1. Delete all (recommended: keep directory clean, avoid index pollution)")
+        print("  2. Keep all (files won't be indexed, but remain in directory)")
+        print("  3. Confirm individually")
+    else:
+        print("✅ No stale files, all documents 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)
+
+
+def main():
+    import warnings
+    warnings.warn(
+        "Use 'source-kb <command>' instead of 'python -m core.skeleton <command>'",
+        DeprecationWarning, stacklevel=2,
+    )
+    print("[DEPRECATED] Use 'source-kb <command>' instead of 'python -m core.skeleton'",
+          file=sys.stderr)
+    parser = argparse.ArgumentParser(prog="python -m core.skeleton", description="Skeleton tools")
+    sub = parser.add_subparsers(dest="command")
+
+    # extract
+    p = sub.add_parser("extract", help="Extract skeleton from repository")
+    p.add_argument("--repo", required=True, help="Repository path")
+    p.add_argument("--preset", required=True, help="Preset name")
+    p.add_argument("--ref", default="HEAD", help="Git reference")
+    p.add_argument("--output", help="Output directory")
+    p.add_argument("--split-by-package", action="store_true")
+    p.add_argument("--no-compact", action="store_true")
+    p.add_argument("--summary", action="store_true")
+    p.add_argument("--full", action="store_true", help="Full extraction (all files)")
+    p.add_argument("--subpath", help="Subdirectory to scope extraction (monorepo module path)")
+    p.add_argument("--files", nargs="*", help="Extract only specified file paths (incremental mode)")
+    p.add_argument("--doc", help="Extract only files relevant to specified doc type")
+
+    # query
+    p = sub.add_parser("query", help="Query skeleton data")
+    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)")
+
+    # file-list
+    p = sub.add_parser("file-list", help="Extract file list for doc type")
+    p.add_argument("--skeleton", help="Skeleton JSON path")
+    p.add_argument("--skeleton-dir", help="Skeleton shards directory")
+    p.add_argument("--module-dir", help="Module directory")
+    p.add_argument("--preset", required=True, help="Preset name")
+    p.add_argument("--doc-type", help="Document type")
+    p.add_argument("--source-cache", help="Source cache path")
+    p.add_argument("--output", help="Output file path")
+    p.add_argument("--coverage-check", action="store_true")
+    p.add_argument("--file-lists-dir", help="Existing file-lists directory")
+
+    # metadata
+    p = sub.add_parser("metadata", help="Pre-generate global metadata")
+    p.add_argument("--module-dir", required=True, help="Module directory")
+    p.add_argument("--module-name", help="Module name")
+
+    # dispatch-preview
+    p = sub.add_parser("dispatch-preview", help="Generate dispatch plan preview")
+    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("--mode", default="readwrite", choices=["readwrite", "output-only"])
+
+    # module-dag
+    p = sub.add_parser("module-dag", help="Build module dependency DAG")
+    p.add_argument("--source-cache", required=True, help="Source cache directory")
+    p.add_argument("--modules", required=True, help="Comma-separated module names")
+
+    # stale-files
+    p = sub.add_parser("stale-files", help="Detect stale/orphaned 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")
+
+    # post-merge
+    p = sub.add_parser("post-merge", help="Run post-merge refinement (dedup + term consistency + anchors)")
+    p.add_argument("--module-dir", required=True, help="Module directory")
+
+    # audit
+    p = sub.add_parser("audit", help="Low-confidence classification audit")
+    p.add_argument("--skeleton", required=True, help="Skeleton JSON path")
+    p.add_argument("--preset", required=True, help="Preset name")
+    p.add_argument("--threshold", type=float, default=0.7, help="Confidence threshold (default: 0.7)")
+
+    # record-feedback
+    p = sub.add_parser("record-feedback", help="Record split execution feedback")
+    p.add_argument("--module-dir", required=True, help="Module directory")
+    p.add_argument("--doc-type", required=True, help="Document type")
+    p.add_argument("--strategy", required=True, choices=["community", "package", "simple", "single"])
+    p.add_argument("--resolution", type=float, default=1.0, help="Resolution parameter")
+    p.add_argument("--n-splits", type=int, default=1, help="Number of splits")
+    p.add_argument("--coverage-score", type=float, default=0.0, help="Coverage score (0-1)")
+    p.add_argument("--quality-score", type=float, default=0.0, help="Quality score (0-1)")
+
+    # split-files
+    p = sub.add_parser("split-files", help="Generate shard file lists for a doc type that needs splitting")
+    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"])
+
+    # split-apply
+    p = sub.add_parser("split-apply", help="Validate and apply Agent-provided grouping result")
+    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)")
+
+    # merge-delta
+    p = sub.add_parser("merge-delta", help="Merge skeleton delta into existing skeleton")
+    p.add_argument("--delta", required=True, help="Path to .skeleton-delta.json")
+    p.add_argument("--target", required=True, help="Target module directory")
+    p.add_argument("--dry-run", action="store_true", help="Preview without writing")
+    p.add_argument("--no-cleanup", action="store_true", help="Keep delta file after merge")
+
+    # anchor-fix
+    p = sub.add_parser("anchor-fix", help="Fix broken cross-document anchor links")
+    p.add_argument("--module-dir", required=True, help="Module documentation directory")
+    p.add_argument("--dry-run", action="store_true", help="Report without fixing")
+    p.add_argument("--threshold", type=float, default=0.8, help="Fuzzy match threshold (0.0-1.0)")
+
+    # lock
+    p = sub.add_parser("lock", help="Unified lock management (acquire/release/status)")
+    p.add_argument("--action", required=True, choices=["acquire", "release", "status"])
+    p.add_argument("--dir", required=True, help="Knowledge directory")
+    p.add_argument("--operation", help="Operation name (kb-sync|kb-audit)")
+    p.add_argument("--timeout", type=int, default=30, help="Timeout in minutes")
+
+    # diff-doc
+    p = sub.add_parser("diff-doc", help="Compare document against skeleton")
+    p.add_argument("--doc-path", required=True, help="Path to markdown document")
+    p.add_argument("--skeleton-path", required=True, help="Path to skeleton JSON file or directory")
+    p.add_argument("--doc-type", help="Document type for specific comparison rules")
+    p.add_argument("--output", help="Output JSON path (default: stdout)")
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    commands = {
+        "extract": cmd_extract, "query": cmd_query, "file-list": cmd_file_list,
+        "metadata": cmd_metadata, "dispatch-preview": cmd_dispatch_preview,
+        "module-dag": cmd_module_dag, "stale-files": cmd_stale_files,
+        "post-merge": cmd_post_merge, "audit": cmd_audit,
+        "record-feedback": cmd_record_feedback, "split-files": cmd_split_files,
+        "split-apply": cmd_split_apply, "merge-delta": cmd_merge_delta,
+        "anchor-fix": cmd_anchor_fix, "lock": cmd_lock, "diff-doc": cmd_diff_doc,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()