context-handoff-bundle 0.3.0__py3-none-any.whl

context_handoff_bundle/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ['main']
+__version__ = '0.1.0'

context_handoff_bundle/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as python -m context_handoff_bundle."""
+from context_handoff_bundle.cli import main
+
+raise SystemExit(main())

context_handoff_bundle/anchors.py

@@ -0,0 +1,205 @@
+"""Evidence anchor parsing, resolution, and content verification.
+
+Evidence anchors are authored by agents as human-readable bullets like:
+
+    orchestrator/company_loop/builder.py:59 — DEFAULT_BUILDER_CMD (new prompt)
+    git commit 4a135d2 on main (pushed)
+    https://github.com/remotion-dev/remotion — video lib
+    py -3 -m pytest tests/ — verification run
+
+Treating those raw strings as filesystem paths is what caused drift to mark
+every anchor GONE. This module is the single shared parser: save uses it to
+verify and hash anchors, load uses it to check them, freshness and token
+estimation use it to resolve files. Parse the locator out, classify the kind,
+and never existence-check prose.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+# Note separators in priority order of first occurrence (em dash, double
+# hyphen, en dash). Everything after the first separator is the note.
+_NOTE_SEPARATORS = (" — ", " -- ", " – ")
+
+_COMMIT_RE = re.compile(r"^(?:git\s+)?commit\s+([0-9a-fA-F]{6,40})\b")
+_BARE_COMMIT_RE = re.compile(r"^[0-9a-f]{7,40}$")
+_LINE_SUFFIX_RE = re.compile(r":(\d+)(?:-(\d+))?$")
+# "Memory: C:\path" / "Config: ~/x" style label prefixes before a real path.
+_LABEL_PREFIX_RE = re.compile(r"^[A-Za-z][A-Za-z ]*:\s+(?=[A-Za-z]:[\\/]|[\\/~.]|\w)")
+_BARE_FILENAME_RE = re.compile(r"^[\w.\-]+\.[A-Za-z0-9]+$")
+
+
+@dataclass
+class Anchor:
+    raw: str
+    kind: str  # 'file' | 'url' | 'commit' | 'other'
+    path: str | None = None  # file path or commit sha or url
+    line_start: int | None = None
+    line_end: int | None = None
+    note: str = ""
+
+
+def parse_anchor(raw: str) -> Anchor:
+    """Parse a free-form evidence anchor string into a structured Anchor."""
+    raw = (raw or "").strip()
+    if not raw:
+        return Anchor(raw=raw, kind="other")
+
+    # Split off the note at the earliest separator occurrence.
+    locator, note = raw, ""
+    cut = min(
+        (raw.find(sep) for sep in _NOTE_SEPARATORS if raw.find(sep) != -1),
+        default=-1,
+    )
+    if cut != -1:
+        sep_len = next(len(s) for s in _NOTE_SEPARATORS if raw.startswith(s, cut))
+        locator, note = raw[:cut].strip(), raw[cut + sep_len :].strip()
+
+    # URLs first (before any colon/paren surgery).
+    if locator.startswith(("http://", "https://")):
+        return Anchor(raw=raw, kind="url", path=locator.split(" ")[0], note=note)
+
+    # Commit references ("git commit 4a135d2 on main", "commit 1eb485f").
+    m = _COMMIT_RE.match(locator)
+    if m:
+        return Anchor(raw=raw, kind="commit", path=m.group(1), note=note)
+
+    # Drop trailing parentheticals and "; extra" clauses from the locator.
+    locator = locator.split(" (")[0].split("; ")[0].strip()
+
+    # Strip a label prefix like "Memory: C:\path\file.md", but never eat a
+    # Windows drive letter ("C:\..." has no space after the colon).
+    locator = _LABEL_PREFIX_RE.sub("", locator)
+
+    if _BARE_COMMIT_RE.match(locator):
+        return Anchor(raw=raw, kind="commit", path=locator, note=note)
+
+    # Pull off a ":line" / ":start-end" suffix.
+    line_start = line_end = None
+    m = _LINE_SUFFIX_RE.search(locator)
+    if m:
+        # Guard against eating a Windows drive colon ("C:" with no path).
+        candidate = locator[: m.start()]
+        if candidate and not re.fullmatch(r"[A-Za-z]", candidate):
+            line_start = int(m.group(1))
+            line_end = int(m.group(2)) if m.group(2) else None
+            locator = candidate
+
+    # A file locator has no spaces and either contains a path separator or
+    # looks like a bare filename with an extension.
+    if (
+        locator
+        and " " not in locator
+        and ("/" in locator or "\\" in locator or _BARE_FILENAME_RE.match(locator))
+    ):
+        return Anchor(
+            raw=raw,
+            kind="file",
+            path=locator,
+            line_start=line_start,
+            line_end=line_end,
+            note=note,
+        )
+
+    return Anchor(raw=raw, kind="other", note=note)
+
+
+def resolve_anchor_path(
+    anchor: Anchor,
+    repo_root: Path | str | None = None,
+    cwd: Path | str | None = None,
+) -> Path | None:
+    """Resolve a file anchor to an existing file on disk, or None."""
+    if anchor.kind != "file" or not anchor.path:
+        return None
+    candidate = Path(anchor.path)
+    candidates = [candidate] if candidate.is_absolute() else []
+    if not candidate.is_absolute():
+        if repo_root:
+            candidates.append(Path(repo_root) / candidate)
+        if cwd:
+            candidates.append(Path(cwd) / candidate)
+    for c in candidates:
+        try:
+            if c.is_file():
+                return c.resolve()
+        except OSError:
+            continue
+    return None
+
+
+def hash_anchor_content(
+    path: Path,
+    line_start: int | None,
+    line_end: int | None,
+) -> str | None:
+    """Content hash for an anchor: the referenced line range, or the whole
+    file when no lines are given. Line-range hashing means unrelated edits
+    elsewhere in the file do not invalidate the anchor."""
+    try:
+        if line_start is None:
+            return hashlib.sha256(path.read_bytes()).hexdigest()[:16]
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        end = line_end if line_end is not None else line_start
+        segment = "\n".join(lines[line_start - 1 : end])
+        return hashlib.sha256(segment.encode("utf-8")).hexdigest()[:16]
+    except OSError:
+        return None
+
+
+def normalize_for_match(path_str: str) -> str:
+    """Normalize a path for exact comparison against git diff output
+    (forward slashes, lowercased -- git paths are repo-relative and we only
+    use this for matching, never for display)."""
+    return path_str.replace("\\", "/").strip("/").lower()
+
+
+def repo_relative(resolved: Path, repo_root: Path | str | None) -> str | None:
+    """Repo-relative normalized form of a resolved path, or None if the file
+    is outside the repo."""
+    if not repo_root:
+        return None
+    try:
+        rel = resolved.relative_to(Path(repo_root).resolve())
+    except ValueError:
+        return None
+    return normalize_for_match(str(rel))
+
+
+# Re-exported convenience used by save: parse + resolve + hash in one pass.
+def verify_anchor(
+    raw: str,
+    repo_root: Path | str | None = None,
+    cwd: Path | str | None = None,
+) -> dict:
+    """Classify and (for file anchors) verify an anchor at save time.
+
+    Returns a dict of the optional evidence-index fields:
+        anchor_kind, resolved_path (repo-relative when possible),
+        line_start, line_end, content_hash, verified_at_save
+    """
+    anchor = parse_anchor(raw)
+    out: dict = {
+        "anchor_kind": anchor.kind,
+        "resolved_path": None,
+        "line_start": anchor.line_start,
+        "line_end": anchor.line_end,
+        "content_hash": None,
+        "verified_at_save": False,
+    }
+    if anchor.kind != "file":
+        return out
+    resolved = resolve_anchor_path(anchor, repo_root=repo_root, cwd=cwd)
+    if resolved is None:
+        return out
+    rel = repo_relative(resolved, repo_root)
+    out["resolved_path"] = rel if rel is not None else str(resolved)
+    out["content_hash"] = hash_anchor_content(
+        resolved, anchor.line_start, anchor.line_end
+    )
+    out["verified_at_save"] = out["content_hash"] is not None
+    return out

context_handoff_bundle/autocontext.py

@@ -0,0 +1,463 @@
+"""Auto-context gathering for rich handoff generation without manual notes.
+
+Task-aware: captures what was being worked on, what changed, what broke,
+what remains unresolved, and which files matter first -- not just repo orientation.
+"""
+from __future__ import annotations
+
+import glob
+import subprocess
+from pathlib import Path
+
+
+def gather_repo_context(cwd: Path | None = None) -> dict:
+    """Gather rich, task-aware context from the current repo automatically.
+
+    Returns a parsed dict compatible with the notes format:
+        scope, projects, findings, opportunities, open_questions, evidence_anchors
+    """
+    cwd = cwd or Path.cwd()
+    cwd = cwd.resolve()
+
+    scope = _build_scope(cwd)
+    projects = _detect_projects(cwd)
+    findings = _gather_findings(cwd)
+    evidence = _gather_evidence_anchors(cwd)
+    open_questions = _gather_open_questions(cwd, findings)
+
+    return {
+        'scope': scope,
+        'projects': projects,
+        'findings': findings,
+        'opportunities': [],
+        'open_questions': open_questions,
+        'evidence_anchors': evidence,
+    }
+
+
+def _build_scope(cwd: Path) -> str:
+    """Build a scope description from repo state."""
+    parts = [f'Context handoff from {cwd.name}']
+    branch = _git_output(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], cwd)
+    if branch:
+        parts.append(f'on branch {branch}')
+    return ' '.join(parts)
+
+
+def _detect_projects(cwd: Path) -> list[str]:
+    """Detect project names from repo structure."""
+    projects = [cwd.name]
+    for subdir in ['packages', 'projects', 'apps', 'services', 'modules']:
+        d = cwd / subdir
+        if d.is_dir():
+            for child in sorted(d.iterdir()):
+                if child.is_dir() and not child.name.startswith('.'):
+                    projects.append(child.name)
+    return projects
+
+
+def _gather_findings(cwd: Path) -> list[str]:
+    """Extract task-aware findings from repo inspection."""
+    findings: list[str] = []
+
+    # 1. What the project is
+    readme_desc = _extract_readme_purpose(cwd)
+    if readme_desc:
+        findings.append(readme_desc)
+
+    # 2. What branch work looks like
+    branch_summary = _summarize_branch_work(cwd)
+    if branch_summary:
+        findings.append(branch_summary)
+
+    # 3. What was being worked on (recent commit themes)
+    work_focus = _detect_work_focus(cwd)
+    if work_focus:
+        findings.append(work_focus)
+
+    # 4. What changed recently (diff stats)
+    diff_summary = _summarize_recent_diff(cwd)
+    if diff_summary:
+        findings.append(diff_summary)
+
+    # 5. What's in progress right now
+    wip = _detect_work_in_progress(cwd)
+    if wip:
+        findings.append(wip)
+
+    # 6. Technology stack
+    stack = _detect_tech_stack(cwd)
+    if stack:
+        findings.append(f'Technology stack: {", ".join(stack)}')
+
+    # 7. Project structure
+    structure = _summarize_structure(cwd)
+    if structure:
+        findings.append(structure)
+
+    # 8. What files were touched most recently
+    hot_files = _get_hot_files(cwd)
+    if hot_files:
+        findings.append(f'Hot files (most recently changed): {", ".join(hot_files[:6])}')
+
+    return findings
+
+
+def _gather_evidence_anchors(cwd: Path) -> list[str]:
+    """Gather key files as evidence anchors, prioritizing recently changed files."""
+    anchors: list[str] = []
+
+    # Recently changed files first -- these are most relevant
+    hot = _get_hot_files(cwd)
+    for f in hot[:5]:
+        p = cwd / f
+        if p.exists():
+            anchors.append(str(p))
+
+    # Key documentation files
+    for name in ['README.md', 'CLAUDE.md', 'docs/SPEC.md', 'docs/ROADMAP.md',
+                 'docs/ARCHITECTURE.md', 'package.json', 'pyproject.toml',
+                 'Cargo.toml', 'go.mod', 'pom.xml']:
+        p = cwd / name
+        if p.exists():
+            anchors.append(str(p))
+
+    # Source entry points
+    for pattern in ['src/index.*', 'src/main.*', 'src/app.*', 'src/lib.*',
+                    'src/*/cli.py', 'src/*/main.py', 'src/*/__init__.py',
+                    'main.*', 'index.*', 'app.*']:
+        matches = glob.glob(str(cwd / pattern))
+        for m in matches[:3]:
+            anchors.append(m)
+
+    # Dirty files -- these are actively being worked on
+    dirty = _get_dirty_files(cwd)
+    for f in dirty[:5]:
+        p = cwd / f
+        if p.exists():
+            anchors.append(str(p))
+
+    return list(dict.fromkeys(anchors))  # Deduplicate preserving order
+
+
+def _gather_open_questions(cwd: Path, findings: list[str]) -> list[str]:
+    """Generate honest open questions based on what we don't know."""
+    questions: list[str] = []
+
+    dirty = _get_dirty_files(cwd)
+    if dirty:
+        questions.append(f'There are {len(dirty)} uncommitted file(s) -- what is their state? Ready to commit or still in progress?')
+
+    # Detect potential issues
+    failing_tests = _detect_test_failures(cwd)
+    if failing_tests:
+        questions.append(f'Tests may be failing: {failing_tests}')
+
+    todo_count = _count_todos(cwd)
+    if todo_count > 0:
+        questions.append(f'{todo_count} TODO/FIXME comments in the codebase -- which are relevant to the current work?')
+
+    # Branch-specific questions
+    branch = _git_output(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], cwd)
+    if branch and branch not in ('main', 'master'):
+        questions.append(f'Branch "{branch}" -- is it ready to merge, or still in progress?')
+
+    questions.append('What was the immediate next step before this handoff?')
+
+    return questions
+
+
+# ── Task-awareness helpers ──
+
+def _summarize_branch_work(cwd: Path) -> str:
+    """Summarize what this branch has done vs main."""
+    branch = _git_output(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], cwd)
+    if not branch or branch in ('main', 'master'):
+        return ''
+
+    # Count commits ahead of main
+    for base in ['main', 'master']:
+        count = _git_output(['git', 'rev-list', '--count', f'{base}..HEAD'], cwd)
+        if count and count != '0':
+            # Get the commit subjects
+            subjects = _git_output(
+                ['git', 'log', f'{base}..HEAD', '--oneline', '--no-decorate', '--max-count=5'],
+                cwd
+            )
+            if subjects:
+                lines = subjects.splitlines()
+                summary = '; '.join(lines[:4])
+                extra = f'; and {len(lines) - 4} more' if len(lines) > 4 else ''
+                return f'Branch "{branch}" is {count} commit(s) ahead of {base}: {summary}{extra}'
+    return ''
+
+
+def _detect_work_focus(cwd: Path) -> str:
+    """Detect what kind of work was happening from recent commits and file paths.
+
+    Combines commit messages with file-path analysis to produce specific
+    descriptions like "CLI commands and quality scoring" instead of generic
+    theme keywords like "add, update, fix".
+    """
+    # Get recent commit messages
+    log = _git_output(
+        ['git', 'log', '--max-count=8', '--format=%s', '--no-decorate'],
+        cwd
+    )
+    # Get recently changed file paths
+    files_output = _git_output(
+        ['git', 'log', '--max-count=5', '--name-only', '--pretty=format:'],
+        cwd
+    )
+
+    if not log and not files_output:
+        return ''
+
+    messages = log.splitlines() if log else []
+
+    # Analyze file paths to detect code areas
+    areas: dict[str, int] = {}
+    if files_output:
+        for filepath in files_output.splitlines():
+            filepath = filepath.strip()
+            if not filepath:
+                continue
+            area = _classify_file_area(filepath)
+            if area:
+                areas[area] = areas.get(area, 0) + 1
+
+    # Build description
+    parts: list[str] = []
+
+    # Top code areas from file paths (the specific part)
+    if areas:
+        sorted_areas = sorted(areas.items(), key=lambda x: x[1], reverse=True)
+        top_areas = [a for a, _ in sorted_areas[:4]]
+        parts.append(f'Active areas: {", ".join(top_areas)}')
+
+    # Recent commit summaries (the narrative part)
+    if messages:
+        parts.append(f'Last commits: {"; ".join(messages[:3])}')
+
+    return '. '.join(parts) if parts else ''
+
+
+def _classify_file_area(filepath: str) -> str:
+    """Classify a file path into a meaningful code area name."""
+    parts = filepath.replace('\\', '/').split('/')
+    filename = parts[-1] if parts else filepath
+
+    # Strip common prefixes
+    meaningful = [p for p in parts if p not in ('src', 'lib', 'app', 'pkg', 'internal', 'cmd')]
+
+    # Use the module/package name if available
+    if len(meaningful) >= 2:
+        # e.g., "context_handoff_bundle/quality.py" -> "quality"
+        module = meaningful[-1].rsplit('.', 1)[0]  # Remove extension
+        parent = meaningful[-2]
+        # Skip __init__, __main__ etc
+        if module.startswith('__'):
+            return parent
+        return module
+
+    # For top-level files, use the file purpose
+    name = filename.rsplit('.', 1)[0]
+    purpose_map = {
+        'test': 'tests', 'spec': 'tests', 'conftest': 'test config',
+        'readme': 'docs', 'changelog': 'docs', 'contributing': 'docs',
+        'dockerfile': 'docker', 'docker-compose': 'docker',
+        'makefile': 'build', 'setup': 'build config', 'pyproject': 'build config',
+        'package': 'package config', 'tsconfig': 'typescript config',
+        'gitignore': 'git config', 'eslintrc': 'lint config',
+    }
+    lower_name = name.lower()
+    for key, label in purpose_map.items():
+        if key in lower_name:
+            return label
+
+    return name if name else ''
+
+
+def _summarize_recent_diff(cwd: Path) -> str:
+    """Summarize what changed in recent commits by file count and areas."""
+    stat = _git_output(
+        ['git', 'diff', '--stat', '--stat-count=10', 'HEAD~3..HEAD'],
+        cwd
+    )
+    if not stat:
+        # Try with fewer commits
+        stat = _git_output(['git', 'diff', '--stat', '--stat-count=10', 'HEAD~1..HEAD'], cwd)
+    if not stat:
+        return ''
+
+    lines = stat.strip().splitlines()
+    if lines:
+        # Last line is the summary (e.g., "10 files changed, 200 insertions(+), 50 deletions(-)")
+        summary_line = lines[-1].strip()
+        if 'changed' in summary_line:
+            return f'Recent changes: {summary_line}'
+    return ''
+
+
+def _detect_work_in_progress(cwd: Path) -> str:
+    """Detect uncommitted work and characterize it."""
+    dirty = _get_dirty_files(cwd)
+    if not dirty:
+        return ''
+
+    # Categorize dirty files
+    staged = _git_output(['git', 'diff', '--name-only', '--cached'], cwd)
+    unstaged = _git_output(['git', 'diff', '--name-only'], cwd)
+    untracked = _git_output(['git', 'ls-files', '--others', '--exclude-standard'], cwd)
+
+    parts = []
+    if staged:
+        staged_count = len(staged.splitlines())
+        parts.append(f'{staged_count} staged')
+    if unstaged:
+        unstaged_count = len(unstaged.splitlines())
+        parts.append(f'{unstaged_count} modified')
+    if untracked:
+        untracked_count = len(untracked.splitlines())
+        parts.append(f'{untracked_count} untracked')
+
+    file_list = ', '.join(dirty[:5])
+    extra = f' and {len(dirty) - 5} more' if len(dirty) > 5 else ''
+    return f'Work in progress ({", ".join(parts)}): {file_list}{extra}'
+
+
+def _detect_test_failures(cwd: Path) -> str:
+    """Quick check for obvious test failure indicators."""
+    # Look for common test result files
+    for pattern in ['.pytest_cache/v/cache/lastfailed', 'test-results.xml']:
+        p = cwd / pattern
+        if p.exists():
+            try:
+                content = p.read_text(encoding='utf-8')
+                if content.strip() and content.strip() != '{}':
+                    return 'pytest lastfailed cache is non-empty -- tests may have been failing'
+            except Exception:
+                pass
+    return ''
+
+
+def _get_hot_files(cwd: Path) -> list[str]:
+    """Get the most actively changed files across recent commits + dirty state."""
+    files: list[str] = []
+
+    # Files changed in last 5 commits
+    output = _git_output(
+        ['git', 'log', '--max-count=5', '--name-only', '--pretty=format:'],
+        cwd
+    )
+    if output:
+        for f in output.splitlines():
+            f = f.strip()
+            if f and f not in files:
+                files.append(f)
+
+    # Dirty files
+    dirty = _get_dirty_files(cwd)
+    for f in dirty:
+        if f not in files:
+            files.insert(0, f)  # Dirty files are hottest
+
+    return files[:15]
+
+
+# ── Base helpers ──
+
+def _git_output(cmd: list[str], cwd: Path) -> str:
+    try:
+        return subprocess.check_output(
+            cmd, cwd=str(cwd), stderr=subprocess.DEVNULL, text=True
+        ).strip()
+    except Exception:
+        return ''
+
+
+def _extract_readme_purpose(cwd: Path) -> str:
+    readme = cwd / 'README.md'
+    if not readme.exists():
+        return ''
+    try:
+        text = readme.read_text(encoding='utf-8')
+        lines = text.splitlines()
+        content_lines: list[str] = []
+        past_title = False
+        for line in lines:
+            if line.startswith('# ') and not past_title:
+                past_title = True
+                continue
+            if past_title and line.strip():
+                content_lines.append(line.strip())
+                if len(content_lines) >= 3:
+                    break
+            elif past_title and content_lines:
+                break
+        if content_lines:
+            desc = ' '.join(content_lines)
+            if len(desc) > 300:
+                desc = desc[:297] + '...'
+            return desc
+    except Exception:
+        pass
+    return ''
+
+
+def _detect_tech_stack(cwd: Path) -> list[str]:
+    stack: list[str] = []
+    indicators = {
+        'package.json': 'Node.js', 'pyproject.toml': 'Python',
+        'Cargo.toml': 'Rust', 'go.mod': 'Go',
+        'pom.xml': 'Java/Maven', 'build.gradle': 'Java/Gradle',
+        'Gemfile': 'Ruby', 'composer.json': 'PHP',
+        'tsconfig.json': 'TypeScript', 'next.config.js': 'Next.js',
+        'next.config.ts': 'Next.js', 'vite.config.ts': 'Vite',
+        'Dockerfile': 'Docker', 'docker-compose.yml': 'Docker Compose',
+    }
+    for filename, tech in indicators.items():
+        if (cwd / filename).exists():
+            stack.append(tech)
+    return stack
+
+
+def _summarize_structure(cwd: Path) -> str:
+    dirs: list[str] = []
+    for item in sorted(cwd.iterdir()):
+        if item.is_dir() and not item.name.startswith('.'):
+            dirs.append(item.name)
+    if not dirs:
+        return ''
+    return f'Top-level directories: {", ".join(dirs[:12])}'
+
+
+def _get_dirty_files(cwd: Path) -> list[str]:
+    output = _git_output(['git', 'status', '--porcelain', '--short'], cwd)
+    if not output:
+        return []
+    files: list[str] = []
+    for line in output.splitlines():
+        parts = line.strip().split(None, 1)
+        if len(parts) == 2:
+            files.append(parts[1])
+    return files[:20]
+
+
+def _count_todos(cwd: Path) -> int:
+    try:
+        output = subprocess.check_output(
+            ['git', 'grep', '-c', '-E', r'TODO|FIXME'],
+            cwd=str(cwd), stderr=subprocess.DEVNULL, text=True
+        )
+        total = 0
+        for line in output.splitlines():
+            parts = line.rsplit(':', 1)
+            if len(parts) == 2:
+                try:
+                    total += int(parts[1])
+                except ValueError:
+                    pass
+        return total
+    except Exception:
+        return 0