tambo 0.14.0

Install and prove the whole AI knowledge-tool kit
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

#!/usr/bin/env python3
"""Fail when user-facing docs teach beads (br/bd) for work tracking.

Work items are tracked with Seeds (`sd`). beads is a legacy tracker: Tambo can
import its JSONL exports, and an agent's `bd` habit is aliased to `sd`. Those
facts may be documented, but new guidance must not tell anyone to track work
with `br` or `bd`.

Two kinds of line are refused in docs/book/src, docs/design/vision.md,
README.md and skills/**/*.md:
  1. a br/bd command form such as `br ready` or `bd create`, inline or in a
     code block;
  2. `br` or `bd` named as a tool on the same line as tracking language
     (track, tracker, issue, work item).
A line that must mention the legacy tracker carries the marker
`<!-- legacy-tracker -->` (hidden in the rendered book), so every exception
is visible in review.

# arming: ci  run by the Documentation workflow on every push and pull request.
Usage: check-tracker-guidance.py [ROOT]   exit 0 clean, 1 findings, 2 unreadable
"""
import re
import sys
from pathlib import Path

MARKER = "<!-- legacy-tracker -->"
VERBS = (
    "ready|show|create|update|close|list|comments?|search|dep|label|init|sync|q|"
    "prime|reopen|defer|blocked|stats|count|graph|history|delete|doctor"
)
COMMAND = re.compile(rf"(?<![\w./-])(?:br|bd)\s+(?:{VERBS})\b")
TOOL = re.compile(r"`(?:br|bd)`")
TRACKING = re.compile(r"\b(?:track(?:s|ed|ing|er)?|issues?|work items?)\b", re.IGNORECASE)


def targets(root: Path):
    book = root / "docs/book/src"
    yield from sorted(book.rglob("*.md"))
    if (root / "README.md").is_file():
        yield root / "README.md"
    if (root / "docs/design/vision.md").is_file():
        yield root / "docs/design/vision.md"
    yield from sorted((root / "skills").rglob("*.md"))


def findings(text: str):
    for number, line in enumerate(text.splitlines(), 1):
        if MARKER in line:
            continue
        if COMMAND.search(line):
            yield number, "br/bd command", line.strip()
        elif TOOL.search(line) and TRACKING.search(line):
            yield number, "br/bd presented as the tracker", line.strip()


def main(argv):
    root = Path(argv[1] if len(argv) > 1 else Path(__file__).resolve().parents[1])
    paths = list(targets(root))
    if not any(p.is_relative_to(root / "docs/book/src") for p in paths):
        print(f"UNKNOWN: no book pages under {root}/docs/book/src", file=sys.stderr)
        return 2
    bad = 0
    for path in paths:
        try:
            text = path.read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError) as error:
            print(f"UNKNOWN: cannot read {path}: {error}", file=sys.stderr)
            return 2
        for number, kind, line in findings(text):
            bad += 1
            print(f"{path.relative_to(root)}:{number}: {kind}: {line}")
    if bad:
        print(f"{bad} line(s) teach br/bd for work tracking; use sd (Seeds), "
              f"or mark a deliberate legacy mention with {MARKER}", file=sys.stderr)
        return 1
    print(f"tracker guidance clean: {len(paths)} file(s) checked")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))