@topmindspace/topmind-handoff 0.5.2 → 0.6.3

package/topmind_handoff/compile.py

@@ -3,10 +3,13 @@
 from __future__ import annotations
 
 import re
+from datetime import date
 from pathlib import Path
 
 from topmind_handoff.model import (
-    SLICE_TITLE,
+    CARD_STALE_DAYS,
+    REVIEW_MARK,
+    SLICES,
     Card,
     ClaimResult,
     Compiled,
@@ -15,13 +18,20 @@ from topmind_handoff.model import (
     compiler_version,
     origin_markdown,
     parse_authority,
+    parse_day,
+    review_suffix,
     scenario_filename,
     parse_card,
     parse_outbox,
+    safe_origin,
     scenario_names,
+    slice_title,
+    view_slice_order,
 )
 
 VIEW_ORDER = ("identity", "boundaries", "preference", "project", "fact")
+_REVIEW_AS_OF = re.compile(r"^review_as_of:\s*(\d{4}-\d{2}-\d{2})\s*$", re.M)
+_CITE_EDGE = r"[A-Za-z0-9_.-]"
 
 
 def _ensure_nl(text: str) -> str:
@@ -66,7 +76,9 @@ def _conflict_block(result: ClaimResult) -> list[str]:
     return lines
 
 
-def _section_lines(results: list[ClaimResult], *, inline_detail: bool) -> dict[str, list[str]]:
+def _section_lines(
+    results: list[ClaimResult], *, inline_detail: bool, today: date | None = None
+) -> dict[str, list[str]]:
     sections = {name: [] for name in VIEW_ORDER}
     for result in sorted(results, key=lambda item: item.claim_id):
         if result.conflict or result.retracted or not result.heads:
@@ -75,20 +87,25 @@ def _section_lines(results: list[ClaimResult], *, inline_detail: bool) -> dict[s
         if head.kind != "set":
             continue
         bucket = sections.setdefault(head.slice, [])
-        bucket.append(_fact_line(head))
+        bucket.append(_fact_line(head, review_suffix(head, today)))
         if inline_detail and head.detail:
             bucket.extend(f"  {line}" for line in head.detail.splitlines())
     return sections
 
 
-def render_scope_view(title: str, results: list[ClaimResult], *, inline_detail: bool) -> str:
-    sections = _section_lines(results, inline_detail=inline_detail)
+def render_scope_view(
+    title: str, results: list[ClaimResult], *, inline_detail: bool, today: date | None = None
+) -> str:
+    sections = _section_lines(results, inline_detail=inline_detail, today=today)
     conflicts = [result for result in results if result.conflict]
     conflicts.sort(key=lambda item: item.claim_id)
     lines = [f"# {title}", ""]
-    for slice_name in VIEW_ORDER:
-        lines.append(f"## {SLICE_TITLE[slice_name]}")
+    for slice_name in view_slice_order(sections):
+        lines.append(f"## {slice_title(slice_name)}")
         body = sections.get(slice_name) or []
+        # An unknown slice with no rows is not a section. Known slices stay, even when empty.
+        if slice_name not in VIEW_ORDER and not body:
+            continue
         lines.extend(body or ["（无）"])
         lines.append("")
     lines.append("## 冲突")
@@ -101,9 +118,11 @@ def render_scope_view(title: str, results: list[ClaimResult], *, inline_detail:
     return _ensure_nl("\n".join(lines))
 
 
-def render_views(compiled: Compiled, *, inline_detail: bool = True) -> dict[str, str]:
+def render_views(
+    compiled: Compiled, *, inline_detail: bool = True, today: date | None = None
+) -> dict[str, str]:
     shared = [result for (scope, _cid), result in compiled.claims.items() if scope == "shared"]
-    rendered = {"shared.md": render_scope_view("共享", shared, inline_detail=inline_detail)}
+    rendered = {"shared.md": render_scope_view("共享", shared, inline_detail=inline_detail, today=today)}
     names = scenario_names(compiled.authority, compiled.cards, _all_ops(compiled))
     for name in names:
         filename = scenario_filename(name)
@@ -111,7 +130,9 @@ def render_views(compiled: Compiled, *, inline_detail: bool = True) -> dict[str,
             continue
         scope = f"scenario:{name}"
         results = [result for (item_scope, _cid), result in compiled.claims.items() if item_scope == scope]
-        rendered[filename] = render_scope_view(f"场景：{name}", results, inline_detail=inline_detail)
+        rendered[filename] = render_scope_view(
+            f"场景：{name}", results, inline_detail=inline_detail, today=today
+        )
     return rendered
 
 
@@ -124,9 +145,20 @@ def _all_ops(compiled: Compiled) -> list[Op]:
     return ops
 
 
-def render_status(compiled: Compiled) -> str:
+def render_status(compiled: Compiled, today: date | None = None) -> str:
     version = compiler_version()
-    lines = ["# STATUS", "", f"compiler: topmind-handoff {version}", "", "## compiled_from"]
+    lines = [
+        "# STATUS",
+        "",
+        "本文件和 views/ 是本机编译产物，不是权威。权威是 outbox/、authority.md 和 environments/。对不上就丢掉视图，重新编译。",
+        "",
+        f"compiler: topmind-handoff {version}",
+        "",
+    ]
+    if today is not None:
+        lines.append(f"review_as_of: {today.isoformat()}")
+        lines.append("")
+    lines.append("## compiled_from")
     if compiled.tips:
         for origin in sorted(compiled.tips):
             tip = compiled.tips[origin] or "-"
@@ -170,6 +202,14 @@ def render_status(compiled: Compiled) -> str:
             lines.append(f"  text: {op.text}")
     else:
         lines.append("（无）")
+    lines.extend(["", "## 待提炼"])
+    refine = refinement_lines(
+        list(compiled.claims.values()),
+        compiled.cards,
+        today,
+        known_ids=_current_ids(compiled),
+    )
+    lines.extend(refine or ["（无）"])
     lines.extend(["", "## origins"])
     origins = sorted(set(compiled.tips) | set(compiled.cards))
     if origins:
@@ -185,19 +225,40 @@ def render_status(compiled: Compiled) -> str:
     return _ensure_nl("\n".join(lines))
 
 
-def compile_repo(repo: Path) -> Compiled:
-    """Regenerate views and STATUS from outboxes. Existing view text is discarded."""
+def stored_review_today(repo: Path) -> date | None:
+    """The explicit day a previous compile or organize used. Absent means unlabeled views."""
+    path = Path(repo) / "STATUS.md"
+    if not path.is_file():
+        return None
+    match = _REVIEW_AS_OF.search(path.read_text(encoding="utf-8"))
+    if not match:
+        return None
+    return parse_day(match.group(1))
+
+
+def compile_repo(repo: Path, today: date | None = None) -> Compiled:
+    """Regenerate views and STATUS from outboxes. Existing view text is discarded.
+
+    Review labels are rendered from `at` and `today`. A later compile with no day
+    reuses `review_as_of` so it does not wipe labels. The day never picks a head.
+    """
     repo = Path(repo)
+    if today is None:
+        today = stored_review_today(repo)
     compiled = build_compiled(repo)
     views = repo / "views"
     views.mkdir(parents=True, exist_ok=True)
-    rendered = render_views(compiled, inline_detail=True)
+    rendered = render_views(compiled, inline_detail=True, today=today)
     for path in views.glob("scenario-*.md"):
         if path.name not in rendered:
             path.unlink()
     for name, text in rendered.items():
         (views / name).write_text(text, encoding="utf-8")
-    (repo / "STATUS.md").write_text(render_status(compiled), encoding="utf-8")
+    (repo / "STATUS.md").write_text(render_status(compiled, today=today), encoding="utf-8")
+    # Local import: admin imports this module. Only a stock README this skill wrote is replaced.
+    from topmind_handoff.admin import upgrade_stock_readme
+
+    upgrade_stock_readme(repo)
     return compiled
 
 
@@ -237,6 +298,22 @@ def status_is_valid(repo: Path) -> tuple[bool, str]:
     return True, "STATUS 与信箱末尾一致"
 
 
+def append_outbox(repo: Path, actor: str, origin: str, blocks: list[str]) -> Path:
+    """Append to one origin's outbox. A different actor is refused and nothing is written."""
+    dest = origin_markdown(Path(repo) / "outbox", origin)
+    origin_name = dest.name[: -len(".md")]
+    if actor != origin_name:
+        raise PermissionError(f"{actor} 只能追加自己的信箱 {origin_name}")
+    if not blocks:
+        return dest
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    existing = dest.read_text(encoding="utf-8") if dest.is_file() else f"# outbox {origin_name}\n"
+    if not existing.endswith("\n"):
+        existing += "\n"
+    dest.write_text(existing + "\n".join(blocks) + "\n", encoding="utf-8")
+    return dest
+
+
 def save_environment_card(repo: Path, actor: str, origin: str, content: str) -> Path:
     """Replace one origin's environment card. Other origins are refused."""
     dest = origin_markdown(Path(repo) / "environments", origin)
@@ -248,7 +325,9 @@ def save_environment_card(repo: Path, actor: str, origin: str, content: str) ->
     return dest
 
 
-_FACT_LINE = re.compile(r"^- (?P<body>.*)\{id:(?P<cid>[^}]+)\}(?P<suffix>\s*（未复核）)?\s*$")
+_FACT_LINE = re.compile(
+    rf"^- (?P<body>.*){{id:(?P<cid>[^}}]+)}}(?P<suffix>\s*{re.escape(REVIEW_MARK)})?\s*$"
+)
 
 
 def _override_line(line: str, overrides: dict[str, str]) -> str | None:
@@ -334,6 +413,103 @@ def _project_shared(repo: Path, shared: str, overrides: dict[str, str]) -> str:
     return _ensure_nl("\n".join(output))
 
 
+def _results_for(compiled: Compiled, scope: str) -> list[ClaimResult]:
+    return [result for (item_scope, _cid), result in compiled.claims.items() if item_scope == scope]
+
+
+def _current_heads(results: list[ClaimResult]) -> list[Op]:
+    heads: list[Op] = []
+    for result in results:
+        if result.conflict or result.retracted or not result.heads:
+            continue
+        head = result.heads[0]
+        if head.kind == "set":
+            heads.append(head)
+    return heads
+
+
+def _current_ids(compiled: Compiled) -> set[str]:
+    found: set[str] = set()
+    for result in compiled.claims.values():
+        for head in _current_heads([result]):
+            found.add(head.claim_id)
+    return found
+
+
+def _scope_heads(compiled: Compiled, scope: str) -> dict[str, Op]:
+    return {head.claim_id: head for head in _current_heads(_results_for(compiled, scope))}
+
+
+def cites_claim(text: str, claim_id: str) -> bool:
+    """True when text names another claim id as a whole token, not as a prefix."""
+    if not text or not claim_id or claim_id not in text:
+        return False
+    pattern = re.compile(
+        r"(?<!" + _CITE_EDGE + r")" + re.escape(claim_id) + r"(?!" + _CITE_EDGE + r")"
+    )
+    return pattern.search(text) is not None
+
+
+def card_is_due(card: Card, today: date | None) -> bool:
+    if card.stale:
+        return True
+    if today is None or not card.refreshed:
+        return False
+    written = parse_day(card.refreshed)
+    if written is None:
+        return False
+    return (today - written).days >= CARD_STALE_DAYS
+
+
+def refinement_lines(
+    results: list[ClaimResult],
+    cards: dict[str, Card],
+    today: date | None,
+    *,
+    known_ids: set[str],
+) -> list[str]:
+    """List review work. Does not retract, rewrite, or touch outboxes.
+
+    Lines are sentences, not `- ` claims, so a package import does not store them as facts.
+    """
+    heads = _current_heads(results)
+    heads.sort(key=lambda op: (op.scope, op.claim_id, op.op_id))
+    lines: list[str] = []
+    for head in heads:
+        if head.slice not in SLICES:
+            lines.append(f"维度 `{head.slice}` 单独成节，没有并进事实。id: {head.claim_id}")
+    for head in heads:
+        blob = f"{head.text}\n{head.detail}"
+        for other in sorted(known_ids):
+            if other == head.claim_id:
+                continue
+            if cites_claim(blob, other):
+                lines.append(f"引用 `{head.claim_id}` 提到当前说法 `{other}`。不撤回，不改写。")
+    for origin in sorted(cards):
+        if card_is_due(cards[origin], today):
+            lines.append(f"环境卡片 `{origin}` 未刷新。")
+    return lines
+
+
+def _label_line(line: str, heads: dict[str, Op], today: date | None) -> str:
+    if today is None:
+        return line
+    match = _FACT_LINE.match(line.rstrip())
+    if not match:
+        return line
+    head = heads.get(match.group("cid"))
+    if head is None:
+        return line
+    suffix = review_suffix(head, today)
+    return f"- {match.group('body').rstrip()} {{id:{match.group('cid')}}}{suffix}"
+
+
+def _label_text(text: str, heads: dict[str, Op], today: date | None) -> str:
+    if today is None:
+        return text
+    return _ensure_nl("\n".join(_label_line(line, heads, today) for line in text.splitlines()))
+
+
 def _conflicts_for_origin(compiled: Compiled, origin: str) -> str:
     blocks: list[str] = []
     for result in sorted(compiled.claims.values(), key=lambda item: (item.scope, item.claim_id)):
@@ -346,41 +522,49 @@ def _conflicts_for_origin(compiled: Compiled, origin: str) -> str:
     return _ensure_nl("\n".join(blocks))
 
 
-def _origin_projection(compiled: Compiled, origin: str) -> str:
-    """Sets whose scope is this origin. Conflicts stay in the conflict section."""
+def _origin_projection(compiled: Compiled, origin: str, today: date | None = None) -> str:
+    """Sets whose scope is this origin, each slice under its own heading.
+
+    Conflicts stay in the conflict section. Origin text is not part of the shared view.
+    """
     scope = f"origin:{origin}"
-    results = [result for (item_scope, _cid), result in compiled.claims.items() if item_scope == scope]
-    lines: list[str] = []
-    for result in sorted(results, key=lambda item: item.claim_id):
-        if result.conflict or result.retracted or not result.heads:
-            continue
-        head = result.heads[0]
-        if head.kind != "set":
-            continue
-        lines.append(_fact_line(head))
-        if head.detail:
-            lines.extend(f"  {line}" for line in head.detail.splitlines())
-    if not lines:
+    results = _results_for(compiled, scope)
+    sections = _section_lines(results, inline_detail=True, today=today)
+    filled = [name for name in view_slice_order(sections) if sections.get(name)]
+    if not filled:
         return ""
-    return "## 本环境范围\n\n" + "\n".join(lines) + "\n"
+    lines = ["## 本环境范围", ""]
+    for name in filled:
+        lines.append(f"### {slice_title(name)}")
+        lines.extend(sections[name])
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
 
 
-def startup_read(repo: Path, origin: str) -> str:
-    """Shared view, this origin's scenario, its card, and conflicts that involve it.
+def projection_body(repo: Path, origin: str, today: date | None = None) -> str:
+    """One origin projection shared by startup and the offline package.
 
-    Card overrides are applied only in this projection. views/shared.md is not rewritten.
+    Reads views when they are inside the repo. Does not write files.
     """
     repo = Path(repo)
+    origin = safe_origin(origin)
     compiled = build_compiled(repo)
+    if today is None:
+        today = stored_review_today(repo)
     views = repo / "views"
+    rendered = render_views(compiled, today=today)
     shared_path = views / "shared.md"
     if shared_path.is_file() and _path_inside(shared_path, views):
         shared = shared_path.read_text(encoding="utf-8")
     else:
-        shared = render_views(compiled)["shared.md"]
+        shared = rendered["shared.md"]
     card = compiled.cards.get(origin)
     overrides = card.overrides if card else {}
-    projected = _project_shared(repo, shared, overrides)
+    projected = _label_text(
+        _project_shared(repo, shared, overrides),
+        _scope_heads(compiled, "shared"),
+        today,
+    )
     role = card.role if card else ""
     filename = scenario_filename(role) if role else None
     scenario_path = views / filename if filename else None
@@ -389,14 +573,18 @@ def startup_read(repo: Path, origin: str) -> str:
     if scenario_path is not None and scenario_path.is_file():
         scenario = scenario_path.read_text(encoding="utf-8")
     elif filename:
-        scenario = render_views(compiled).get(filename, "# 场景\n\n（无）\n")
+        scenario = rendered.get(filename, "# 场景\n\n（无）\n")
     else:
         scenario = "（无）\n"
+    scenario = _label_text(scenario, _scope_heads(compiled, f"scenario:{role}") if role else {}, today)
     card_text = card.raw if card else "（无）\n"
-    origin_text = _origin_projection(compiled, origin).rstrip("\n")
+    origin_text = _origin_projection(compiled, origin, today=today).rstrip("\n")
+    visible: list[ClaimResult] = list(_results_for(compiled, "shared"))
+    if role:
+        visible.extend(_results_for(compiled, f"scenario:{role}"))
+    visible.extend(_results_for(compiled, f"origin:{origin}"))
+    refine = refinement_lines(visible, compiled.cards, today, known_ids=_current_ids(compiled))
     parts = [
-        f"# 开工读取（{origin})",
-        "",
         "## 冲突（与本环境有关）",
         _conflicts_for_origin(compiled, origin).rstrip("\n"),
         "",
@@ -409,5 +597,26 @@ def startup_read(repo: Path, origin: str) -> str:
     ]
     if origin_text:
         parts.extend([origin_text, ""])
-    parts.extend(["## 环境卡片", card_text.rstrip("\n"), ""])
+    parts.extend(
+        [
+            "## 环境卡片",
+            card_text.rstrip("\n"),
+            "",
+            "## 待提炼",
+            "\n".join(refine) if refine else "（无）",
+            "",
+        ]
+    )
     return _ensure_nl("\n".join(parts))
+
+
+def startup_read(repo: Path, origin: str, today: date | None = None) -> str:
+    """Shared view, this origin's scenario, its card, and conflicts that involve it.
+
+    Card overrides are applied only in this projection. views/shared.md is not rewritten.
+    Due labels and the 待提炼 list are printed. Nothing is retracted.
+    """
+    repo = Path(repo)
+    origin = safe_origin(origin)
+    body = projection_body(repo, origin, today=today).rstrip("\n")
+    return _ensure_nl(f"# 开工读取（{origin})\n\n{body}")

package/topmind_handoff/model.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import json
 import re
+from collections.abc import Iterable
 from dataclasses import dataclass, field
+from datetime import date, datetime
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
@@ -21,11 +23,44 @@ REVIEW_DAYS = {
     "boundaries": 180,
     "preference": 90,
     "project": 30,
+    "fact": 30,
 }
+CARD_STALE_DAYS = 90
+REVIEW_MARK = "（未复核）"
 INDEX_LINE_BUDGET = 200
 INDEX_BYTE_BUDGET = 25 * 1024
 
 
+def parse_day(value: str) -> date | None:
+    try:
+        return datetime.strptime(value, "%Y-%m-%d").date()
+    except ValueError:
+        return None
+
+
+def review_suffix(op: Op, today: date | None) -> str:
+    """Label a current head from its own `at`. The date never picks a chain head."""
+    if today is None:
+        return ""
+    limit = REVIEW_DAYS.get(op.slice)
+    written = parse_day(op.at)
+    if limit is None or written is None:
+        return ""
+    if (today - written).days >= limit:
+        return f" {REVIEW_MARK}"
+    return ""
+
+
+def slice_title(name: str) -> str:
+    """Known slices keep their Chinese headings. Anything else stays its own section."""
+    return SLICE_TITLE.get(name, f"维度：{name}")
+
+
+def view_slice_order(present: Iterable[str]) -> list[str]:
+    extras = sorted({name for name in present if name not in SLICES})
+    return list(SLICES) + extras
+
+
 def compiler_version() -> str:
     pkg = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))
     return str(pkg["version"])
@@ -162,9 +197,9 @@ def parse_outbox(text: str, origin: str) -> list[Op]:
         base_raw = fields.get("base", "none").strip() or "none"
         kind = fields.get("op", "set").strip() or "set"
         scope = fields.get("scope", "shared").strip() or "shared"
+        # Missing slice stays fact. An unknown value, including `environment`, is kept.
+        # Coercing it would hide the row under 事实 and a typo must not abort the ledger.
         slice_name = fields.get("slice", "fact").strip() or "fact"
-        if slice_name not in SLICES:
-            slice_name = "fact"
         ops.append(
             Op(
                 op_id=op_id,