@tanlinfeng/project-docs-workflow 2.2.0 → 3.0.0

package/skills/docs-html-view/scripts/gen_nav.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""Generate docs-html-view navigation under docs/docsHtmlView.
+
+Writes only marked files inside the workspace: ``docsHtmlView/index.md`` and
+``docsHtmlView/nav/**/index.md``. Never writes into source trees. Validates every
+symlink and collision in a preflight pass *before* the first write or prune, so a
+refusal leaves the tree unchanged. Removes only stale files carrying the marker.
+Runs before ``make html``; it never invokes Sphinx itself.
+
+Exit codes: 0 = generated (or nothing needed); 1 = refused, or no documents in
+the approved trees (so a later ``make`` cannot silently build a stale site).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import posixpath
+import re
+import sys
+
+MARK = "% docs-html-view: generated navigation; do not edit"
+DEFAULT_ROOTS = ["pdr", "current", "adr"]
+SUFFIXES = (".md", ".rst")
+RESERVED = {"build", "docsHtmlView"}
+BIG = float("inf")
+
+
+def die(msg: str) -> None:
+    sys.exit("refusing: " + msg)
+
+
+def warn(msg: str) -> None:
+    print("warning: " + msg, file=sys.stderr)
+
+
+def sanitize(text: str) -> str:
+    text = re.sub(r"[<>`{}\[\]|]", "", text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def display_name(name: str) -> str:
+    name = re.sub(r"^\d+[-_. ]*", "", name).replace("-", " ").replace("_", " ").strip()
+    return sanitize(name) or "section"
+
+
+def num_key(name: str):
+    match = re.match(r"^(\d+)", name)
+    return (0, int(match.group(1))) if match else (1, 0)
+
+
+def has_docs(path: str) -> bool:
+    for _dirpath, _dirnames, filenames in os.walk(path, followlinks=False):
+        if any(f.lower().endswith(SUFFIXES) for f in filenames):
+            return True
+    return False
+
+
+def file_owned(path: str) -> bool:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return fh.read().lstrip().startswith(MARK)
+    except OSError:
+        die("cannot read " + path)
+
+
+def read_config(workspace: str) -> dict:
+    path = os.path.join(workspace, "docs-html-view.config.json")
+    if not os.path.lexists(path):
+        return {}
+    if os.path.islink(path):
+        die("config is a symlink: " + path)
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError) as exc:
+        die("cannot parse config %s: %s" % (path, exc))
+    if not isinstance(data, dict):
+        die("config must be a JSON object: " + path)
+    return data
+
+
+def validate_dir_name(name: str) -> None:
+    if not name or name in (".", ".."):
+        die("invalid allowed_dirs entry: %r" % (name,))
+    if "/" in name or "\\" in name:
+        die("allowed_dirs entry must be one directory name, no separators: %r" % (name,))
+    if name.startswith("."):
+        die("allowed_dirs entry must not be hidden: %r" % (name,))
+    if name in RESERVED:
+        die("allowed_dirs entry may not be %r" % (name,))
+
+
+def resolve_roots(cfg: dict, docs: str):
+    allowed = cfg.get("allowed_dirs")
+    if allowed is None:
+        candidates = list(DEFAULT_ROOTS)
+    else:
+        if not isinstance(allowed, list):
+            die("allowed_dirs must be a list of simple directory names")
+        for name in allowed:
+            if not isinstance(name, str):
+                die("allowed_dirs entries must be strings")
+            validate_dir_name(name)
+        candidates = list(dict.fromkeys(allowed))
+
+    present, missing = [], []
+    for name in candidates:
+        path = os.path.join(docs, name)
+        if os.path.islink(path):
+            die("approved dir is a symlink: " + path)
+        if os.path.isdir(path) and has_docs(path):
+            present.append(name)
+        else:
+            missing.append(name)
+    return present, missing
+
+
+def assert_no_symlinks(base: str, label: str) -> None:
+    if not os.path.isdir(base):
+        return
+    for dirpath, dirnames, filenames in os.walk(base, followlinks=False):
+        for name in list(dirnames) + filenames:
+            path = os.path.join(dirpath, name)
+            if os.path.islink(path):
+                die("symlink under %s: %s" % (label, path))
+
+
+def toctree(entries, maxdepth=1) -> str:
+    if not entries:
+        return "<!-- (no documents) -->\n"
+    lines = ["```{toctree}", ":maxdepth: %d" % maxdepth, ""] + list(entries) + ["```"]
+    return "\n".join(lines) + "\n"
+
+
+def build_outputs(docs, workspace, roots, order_map, site_title):
+    outputs = {}
+
+    def order_key(base_rel):
+        def key(name):
+            rel = posixpath.join(base_rel, name) if base_rel else name
+            return (order_map.get(rel, BIG), num_key(name), name.casefold())
+        return key
+
+    def generate(source_root, rel_parts, src_dir):
+        base_rel = posixpath.join(source_root, *rel_parts)
+        out_rel = posixpath.join("docsHtmlView", "nav", source_root, *rel_parts)
+        children = []
+        for name in sorted(os.listdir(src_dir)):
+            path = os.path.join(src_dir, name)
+            if os.path.islink(path):
+                die("symlink in source tree: " + path)
+            if os.path.isdir(path):
+                if has_docs(path):
+                    children.append((name, "dir"))
+            elif name.lower().endswith(SUFFIXES):
+                children.append((name, "file"))
+        children.sort(key=lambda item: order_key(base_rel)(item[0]))
+
+        entries = []
+        for name, kind in children:
+            if kind == "dir":
+                entries.append(posixpath.join(name, "index"))
+            else:
+                target = posixpath.join(source_root, *rel_parts, name)
+                entries.append(posixpath.relpath(target, out_rel))
+
+        title = display_name(rel_parts[-1]) if rel_parts else display_name(source_root)
+        out_file = os.path.join(docs, *out_rel.split("/"), "index.md")
+        outputs[out_file] = MARK + "\n\n# " + title + "\n\n" + toctree(entries)
+
+        for name, kind in children:
+            if kind == "dir":
+                generate(source_root, list(rel_parts) + [name], os.path.join(src_dir, name))
+
+    for source_root in roots:
+        generate(source_root, [], os.path.join(docs, source_root))
+
+    index_entries = [posixpath.join("nav", r, "index") for r in roots]
+    outputs[os.path.join(workspace, "index.md")] = (
+        MARK + "\n\n# " + site_title + "\n\n" + toctree(index_entries, maxdepth=2)
+    )
+    return outputs
+
+
+def collision_preflight(outputs, nav_root) -> None:
+    out_abs = {os.path.abspath(p) for p in outputs}
+    for path in sorted(out_abs):
+        if os.path.islink(path):
+            die("symlinked output: " + path)
+        if os.path.lexists(path) and not file_owned(path):
+            die("existing unmarked file: " + path)
+    if os.path.isdir(nav_root):
+        for dirpath, _dirnames, filenames in os.walk(nav_root, followlinks=False):
+            for name in filenames:
+                path = os.path.abspath(os.path.join(dirpath, name))
+                if path in out_abs:
+                    continue
+                if os.path.islink(path):
+                    die("symlinked nav file: " + path)
+                if not file_owned(path):
+                    die("unmarked file under nav/: " + path)
+
+
+def verify_inside(outputs, workspace) -> None:
+    workspace_real = os.path.realpath(workspace)
+    for path in outputs:
+        real = os.path.realpath(path)
+        if real != workspace_real and not real.startswith(workspace_real + os.sep):
+            die("output escapes workspace: " + path)
+
+
+def write_outputs(outputs) -> None:
+    for path in sorted(outputs):
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(outputs[path])
+
+
+def prune(nav_root, outputs) -> None:
+    out_abs = {os.path.abspath(p) for p in outputs}
+    if not os.path.isdir(nav_root):
+        return
+    for dirpath, _dirnames, filenames in os.walk(nav_root, followlinks=False):
+        for name in filenames:
+            path = os.path.abspath(os.path.join(dirpath, name))
+            if path not in out_abs and file_owned(path):
+                os.remove(path)
+    for dirpath, _dirs, _files in os.walk(nav_root, topdown=False):
+        if dirpath == nav_root:
+            continue
+        try:
+            os.rmdir(dirpath)  # only succeeds when empty
+        except OSError:
+            pass
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Generate docs-html-view navigation (marked files only).")
+    ap.add_argument("--project-root", default=os.getcwd())
+    ap.add_argument("--title", default=None, help="site title override")
+    ap.add_argument("--json", action="store_true", help="print a machine-readable summary on stdout")
+    args = ap.parse_args()
+
+    root = os.path.abspath(args.project_root)
+    docs = os.path.join(root, "docs")
+    if not os.path.isdir(docs):
+        die("no docs/ directory at " + root)
+    if os.path.islink(docs):
+        die("docs/ is a symlink")
+
+    workspace = os.path.join(docs, "docsHtmlView")
+    if not os.path.isdir(workspace):
+        die("no docs/docsHtmlView workspace; run quickstart/setup first")
+    if os.path.islink(workspace):
+        die("docsHtmlView/ is a symlink")
+
+    cfg = read_config(workspace)
+    site_title_cfg = cfg.get("site_title")
+    if site_title_cfg is not None and not isinstance(site_title_cfg, str):
+        die("site_title must be a string")
+    order = cfg.get("navigation_order")
+    if order is None:
+        order = []
+    elif not isinstance(order, list) or not all(isinstance(x, str) for x in order):
+        die("navigation_order must be a list of strings")
+    order_map = {rel.strip("/"): i for i, rel in enumerate(order)}
+
+    roots, missing = resolve_roots(cfg, docs)
+    if missing:
+        warn("missing/empty trees: " + ", ".join(missing))
+    if not roots:
+        print(
+            "no documents in the approved trees; nothing to scaffold (run after adding docs)",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    for name in roots:
+        assert_no_symlinks(os.path.join(docs, name), "source tree " + name)
+    nav_root = os.path.join(workspace, "nav")
+    if os.path.islink(nav_root):
+        die("nav/ is a symlink")
+    assert_no_symlinks(nav_root, "nav/")
+
+    site_title = sanitize(str(site_title_cfg or args.title or "Documentation"))
+    outputs = build_outputs(docs, workspace, roots, order_map, site_title)
+    collision_preflight(outputs, nav_root)
+    verify_inside(outputs, workspace)
+
+    write_outputs(outputs)
+    prune(nav_root, outputs)
+
+    if args.json:
+        print(
+            json.dumps(
+                {"roots": roots, "generated": sorted(os.path.relpath(p, root) for p in outputs)},
+                indent=2,
+            )
+        )
+    else:
+        print("generated %d nav file(s) for roots: %s" % (len(outputs), ", ".join(roots)))
+
+
+if __name__ == "__main__":
+    main()

package/skills/docs-html-view/scripts/prepare_env.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Prepare the docs render environment for docs-html-view.
+
+Stdlib only. Never installs Python or uv, and never touches global/system
+site-packages. It creates or reuses one *recognized* virtualenv and, only when
+explicitly asked, installs the pinned requirements into that venv.
+
+Run this only AFTER the user has approved the packages, the environment, and the
+files (the Skill asks; this helper stores no consent state).
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+
+MIN_PY = (3, 12)
+
+
+def venv_python(venv: str) -> str:
+    if os.name == "nt":
+        return os.path.join(venv, "Scripts", "python.exe")
+    return os.path.join(venv, "bin", "python")
+
+
+def is_recognized_venv(venv: str) -> bool:
+    return os.path.isfile(os.path.join(venv, "pyvenv.cfg"))
+
+
+def python_version(python: str):
+    code = "import sys;print('%d.%d' % sys.version_info[:2])"
+    try:
+        out = subprocess.run(
+            [python, "-I", "-c", code], capture_output=True, text=True, check=True
+        ).stdout.strip()
+    except (OSError, subprocess.CalledProcessError) as exc:
+        return None, str(exc)
+    try:
+        return tuple(int(x) for x in out.split(".")[:2]), out
+    except ValueError:
+        return None, out
+
+
+def run(cmd, cwd=None):
+    print("+ " + " ".join(cmd))
+    return subprocess.run(cmd, cwd=cwd)
+
+
+def has_pip(python: str) -> bool:
+    try:
+        return subprocess.run(
+            [python, "-m", "pip", "--version"], capture_output=True, text=True
+        ).returncode == 0
+    except OSError:
+        return False
+
+
+def venv_prefix(python: str):
+    try:
+        out = subprocess.run(
+            [python, "-c", "import sys;print(sys.prefix)"], capture_output=True, text=True
+        )
+    except OSError:
+        return None
+    return out.stdout.strip() if out.returncode == 0 else None
+
+
+def pip_in_venv(python: str, venv: str):
+    if not has_pip(python):
+        return False, "pip is not available in the interpreter"
+    prefix = venv_prefix(python)
+    if prefix is None or os.path.realpath(prefix) != os.path.realpath(venv):
+        return False, "interpreter does not belong to %s (sys.prefix=%s)" % (venv, prefix)
+    return True, ""
+
+
+def main() -> None:
+    default_req = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), os.pardir, "requirements.txt"
+    )
+    ap = argparse.ArgumentParser(
+        description="Create/reuse the docs render venv and optionally install pinned requirements."
+    )
+    ap.add_argument("--project-root", default=os.getcwd())
+    ap.add_argument("--venv", default=".venv-docs", help="venv path (relative to project root unless absolute)")
+    ap.add_argument("--base-python", default=None, help="interpreter used to create the venv (default: this one)")
+    ap.add_argument("--requirements", default=default_req)
+    ap.add_argument("--install", action="store_true", help="install the pinned requirements (post-consent)")
+    ap.add_argument("--freeze", metavar="PATH", default=None, help="write `pip freeze` output to PATH (post-consent)")
+    args = ap.parse_args()
+
+    root = os.path.abspath(args.project_root)
+    venv = args.venv if os.path.isabs(args.venv) else os.path.join(root, args.venv)
+    requirements = os.path.abspath(args.requirements)
+
+    if os.path.lexists(venv) and not is_recognized_venv(venv):
+        sys.exit("refusing: %s exists but is not a virtualenv (no pyvenv.cfg); move it aside first" % venv)
+
+    if not is_recognized_venv(venv):
+        base = args.base_python or sys.executable
+        ver, raw = python_version(base)
+        if ver is None or ver < MIN_PY:
+            sys.exit("refusing: %s reports %s; need Python >= %d.%d" % (base, raw, *MIN_PY))
+        print("+ %s -m venv %s" % (base, venv))
+        created = subprocess.run(
+            [base, "-m", "venv", venv], capture_output=True, text=True
+        )
+        if created.returncode != 0:
+            detail = (created.stderr or created.stdout or "").strip()
+            sys.exit(
+                "failed to create virtualenv at %s (exit %d).\n%s\n"
+                "Ensure python3-venv/ensurepip is available, or pass --venv pointing at "
+                "an existing project docs environment." % (venv, created.returncode, detail)
+            )
+    else:
+        print("reusing virtualenv: " + venv)
+
+    py = venv_python(venv)
+    ver, raw = python_version(py)
+    if ver is None or ver < MIN_PY:
+        sys.exit("refusing: venv python reports %s; need Python >= %d.%d" % (raw, *MIN_PY))
+
+    if args.install or args.freeze:
+        ok, why = pip_in_venv(py, venv)
+        if not ok:
+            sys.exit("refusing: %s; point --venv at a working docs environment" % why)
+
+    if args.install:
+        if not os.path.isfile(requirements):
+            sys.exit("requirements not found: " + requirements)
+        result = run(
+            [py, "-m", "pip", "install", "--no-input", "--disable-pip-version-check", "-r", requirements],
+            cwd=root,
+        )
+        if result.returncode != 0:
+            sys.exit("pip install failed (exit %d)" % result.returncode)
+
+    if args.freeze:
+        result = subprocess.run([py, "-m", "pip", "freeze"], capture_output=True, text=True)
+        if result.returncode != 0:
+            sys.exit("pip freeze failed (exit %d)" % result.returncode)
+        dest = args.freeze if os.path.isabs(args.freeze) else os.path.join(root, args.freeze)
+        os.makedirs(os.path.dirname(dest) or ".", exist_ok=True)
+        with open(dest, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(result.stdout)
+        print("wrote freeze: " + dest)
+
+    print("python: " + py)
+    print("install: " + ("yes" if args.install else "no"))
+
+
+if __name__ == "__main__":
+    main()

package/skills/project-docs-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-docs-workflow
-description: Initialize or align a project's documentation workflow — issue tracker, ADRs, PDR product specs (goal/current), recommended five-step development workflow, and domain terminology. Run manually once per project (idempotent); creates missing files and reports alignment without overwriting.
+description: Initialize or align a project's documentation workflow — issue tracker, ADRs, PDR target specs with a separate Current status tree, recommended five-step development workflow, and domain terminology. Run manually once per project (idempotent); creates missing files and reports alignment without overwriting.
 disable-model-invocation: true
 ---
 
@@ -20,10 +20,16 @@ Run it manually, once per project — on adoption, or again after the skill's te
 
 ## 依赖解析（两级）
 
-External skill references resolve in two levels:
+External capability references resolve in two levels:
 
-1. **Invoke the skill by name** — the user has the full version installed, or the bundled lite version ships with the package (canonical names: `grilling`, `domain-modeling`, `tdd`, `deepwork`, `retro`, `doc-opt`, `improve-codebase-architecture`; the full version wins when present).
-2. **Fallback** — if that skill is absent, follow `references/deps/<name>.md`; `deepwork` / `retro` / `improve-codebase-architecture` share `references/deps/boundaries.md`.
+1. **Invoke the installed skill by name** — when the user has the standalone skill installed (canonical names: `grilling`, `grill-me`, `grill-with-docs`, `domain-modeling`, `tdd`, `deepwork`, `retro`, `improve-codebase-architecture`, plus the first-party `doc-opt`); the installed version wins.
+2. **Internal fallback** — otherwise **execute** the bundled reference(s) as instructions; do **not** invoke them as skills (there are none). Most names map to `references/deps/<name>.md`; the aliases map explicitly:
+   - `grill-me` → `references/deps/grilling.md` (entry alias of `grilling`, no separate flow)
+   - `grill-with-docs` → `references/deps/grilling.md` **+** `references/deps/domain-modeling.md`, interleaved (grilling rounds + immediate term/ADR writes)
+   - `deepwork` / `retro` / `improve-codebase-architecture` → `references/deps/boundaries.md`
+   The package ships **no** standalone dependency skills; these internal references are the always-available fallback.
+
+> **Trigger policy.** Follow each installed skill's invocation metadata; wrappers such as `grill-me` / `grill-with-docs` may be user-invoked only. An optional name does **not** imply availability: if it is not installed, use the internal fallback — never invoke a missing skill or autonomously invoke a user-only wrapper. Per-name routing lives in `references/workflow.md`.
 
 Canonical wording (templates use the same line with the deps path parameterized): 调用 `<skill>`（未安装则按 `<deps 路径>/<file>.md` 执行）— skill-internal docs use `references/deps/<file>.md`, materialized project files use `docs/agents/deps/<file>.md`.
 
@@ -32,7 +38,7 @@ Canonical wording (templates use the same line with the deps path parameterized)
 Run from the target project root (`cwd`).
 
 1. **Inventory** every artifact in the checklist below. Classify each as *missing* or *existing*. Done when every row has a classification.
-2. **Create missing** files from their template, and create the issue directory tree.
+2. **Create missing** files from their template, and create the issue directory tree. Create the `docs/current/00-README.md` overview when missing — do not force module files.
 2b. **Fill placeholders**: fill only obvious, determinable *fill-in* placeholders (e.g. project name from the repo/directory name); list every remaining fill-in placeholder under `Next:` in the report. Format notation such as `<标题>` is documentation, not a placeholder — skip it.
 3. **Compare existing** files against their template: classify *aligned*, or *diff* with the specific differences listed.
 4. **Report** using the format below.
@@ -49,13 +55,16 @@ Run from the target project root (`cwd`).
 | `docs/issues/` directory tree | none — create dirs (below) |
 | `docs/adr/README.md` | `assets/templates/project/adr-readme.md` |
 | `docs/pdr/00-README.md` | `assets/templates/project/pdr-00-readme.md` |
+| `docs/current/00-README.md` | `assets/templates/project/current-00-readme.md` |
 | `CONTEXT.md` | `assets/templates/project/context.md` |
 
 - Create `AGENTS.md` only if missing — its whole content is this block; a file containing only this section is intentional (projects add their own guidance around it). If `AGENTS.md` exists: heading `## Agent skills` present → compare the block in place (never edit); absent → append the block at end of file, separated by one blank line. Only `AGENTS.md` is touched, never `CLAUDE.md`.
 - The provenance line sits immediately under the `## Agent skills` heading and is intentional — keep it (it identifies materialized files and their generation).
 - Issue tree: `bug/{human,agent,history}`, `feature/{human,agent,history}`, `chore/{human,agent,history}`, `suggestion/{human,agent}`; add a `.gitkeep` to each leaf directory (one containing no files). Do not run `git init`.
 - Dep fallbacks: init copies `references/deps/*` into the project's `docs/agents/deps/` as a whole-directory copy (content unchanged), so target projects are self-sufficient even without this skill installed.
+- Current tree: init creates the `docs/current/00-README.md` overview when missing; it does **not** force module files — add them as modules need describing. The Current tree is peer to PDR, never embedded in it.
 - Domain glossaries (e.g. `docs/common/glossary.md`) are **not** scaffolded; the rules cover them and projects create them on demand.
+- Rendering is **out of scope for init**: init creates no renderer config, artifacts, or hooks. HTML rendering is an optional, manual first-party skill (`docs-html-view`); see `references/rendering.md`.
 
 ### Alignment comparison (existing files)
 
@@ -63,6 +72,8 @@ Compare **rules, not bytes**. An existing file is **aligned** when every require
 
 **diff** = a required rule/section is missing, or a default rule is contradicted. Diffs are informational; init never auto-fixes. One bullet per file: `- <file>: <missing or contradicted rule>`.
 
+**Legacy drift** (existing projects): embedded current/progress material found in an existing project — e.g. per-module `04-current.md`, a `当前进展` section in the PDR README — is reported as informational legacy drift. init never moves, rewrites, or deletes it, and there is no installation migration script; migrating to a separate Current tree requires the user's explicit authorization.
+
 Ignore in every comparison: the provenance line; filled placeholders; index/table rows; module/term/entry names; language; extra content.
 
 Required elements per artifact:
@@ -70,9 +81,10 @@ Required elements per artifact:
 - `AGENTS.md` block: `## Agent skills` heading + three subsections (`### Issue tracker`, `### Domain docs`, `### Development workflow`).
 - `docs/agents/issues.md`: directory contract; human/agent responsibility; entry format (`Status:` line, `## 完成判据`, `## 步骤`, `## Log`; the `## 结果` section itself is optional); archiving suffixes (`-done`/`-drop`); suggestion routing.
 - `docs/agents/domain.md`: read CONTEXT.md + docs/adr before exploring; silently continue if missing; glossary vocabulary rule; ADR-conflict flagging.
-- `docs/agents/workflow.md`: recommended five-step flow (规划 / 骨架 / 细节 / 异常 / 回顾 with 回顾 = docs-sync wrap-up); align-before-build ordering; conversational alignment (no freeze); elastic granularity suggestion (≈0.5 人天 heuristic); issue `## 步骤` tracking + resume anchor; PDR goal/current gap→issue derivation; boundaries (deepwork / tdd / retro / grilling 调用 + 兜底指针).
-- `docs/adr/README.md`: lifecycle rules (edit+Log, delete→tombstone stub, no renumber); catalog table present.
-- `docs/pdr/00-README.md`: purpose; 最终目标 / 当前进展 overview sections; module index; reading order.
+- `docs/agents/workflow.md`: recommended five-step flow (规划 / 骨架 / 细节 / 异常 / 回顾 with 回顾 = docs-sync wrap-up); align-before-build ordering; conversational alignment (no freeze); elastic granularity suggestion (≈0.5 人天 heuristic); issue `## 步骤` tracking + resume anchor; PDR-target / Current gap→issue candidate derivation; wrap-up updates Current in place (facts only, no self-link or task history); boundaries (deepwork / tdd / retro / grilling 调用 + 兜底指针).
+- `docs/adr/README.md`: lifecycle rules (edit+Log, delete→tombstone stub, no renumber); catalog table present; reference sweep covers both `ADR-XXXX` and `adr/<NNNN>-<slug>.md` path links (any relative prefix).
+- `docs/pdr/00-README.md`: purpose; end-state overview; module index; reading order; link to the peer Current tree (no progress section, no embedded current); optional descriptive ADR link rule.
+- `docs/current/00-README.md`: purpose; the baseline (revision/date) the tree describes; module/topic index; reading order; link to the peer PDR tree; records as-built capabilities/limits, not task logs or planned work; optional descriptive ADR link rule.
 - `CONTEXT.md`: glossary structure (term blocks with `_Avoid_`).
 - `docs/issues/` tree: leaf directories exist (`.gitkeep` may be checked); extras informational only.
 - `docs/agents/deps/`: leaf files exist (`grilling.md`, `domain-modeling.md`, `tdd.md`, `doc-opt.md`, `boundaries.md`); extras informational only.
@@ -86,6 +98,7 @@ Write the report in the project's documentation language (default: Chinese, matc
 - Created: …
 - Aligned: …
 - Diff: one bullet per file: `- <file>: <missing or contradicted rule>`（仅供参考，不自动改；multi-file → multiple bullets）
+- Legacy drift: embedded current/progress paths found (e.g. `04-current.md`, `当前进展` section) — informational only, never moved or rewritten; migration needs explicit user authorization.
 - Next: remaining placeholders plus a one-line "do this first".
 ```
 
@@ -95,14 +108,16 @@ Rules carry the detail; read the one you need.
 
 - `references/issues.md` — issue tracker directory contract, entry format, `suggestion` routing.
 - `references/adr.md` — ADR lifecycle (edit + Log, delete → tombstone stub, reference sweep, catalog index), body shape.
-- `references/pdr.md` — PDR product-spec structure (`00-README` / `01-spec` / `02-interfaces` / `03-nfr` / `04-current` + `design/`), the goal/current & gap→issues layer, PDR↔ADR boundary.
+- `references/pdr.md` — PDR target-spec structure (`00-README` / `01-spec` / `02-interfaces` / `03-nfr` + `design/`), the target & gap→candidate-issue layer, PDR↔ADR and PDR↔Current boundaries.
+- `references/current.md` — Current as-built tree (`00-README` + module/topic docs), baseline & verification confidence, sync semantics, peer relationship to PDR, legacy-drift adoption.
+- `references/rendering.md` — optional docs HTML rendering contract: render scope (`docs/pdr` + `docs/current` + the complete `docs/adr`, not issues / agents), link-authoring rules (PDR↔Current, optional descriptive ADR path links), sources never rewritten, manual opt-in.
 - `references/terminology.md` — `CONTEXT.md` primary glossary, domain glossary, usage rules.
 - `references/workflow.md` — recommended single-issue development flow (five steps, alignment, granularity, tracking, docs-sync hooks, skill boundaries).
-- `references/coexistence.md` — how this profile sits beside `domain-modeling`, `grilling`, `deepwork`, `tdd`, `retro`, and the bundled `doc-opt`; and how its docs/issues conventions supersede older `.scratch`-style trackers.
-- `references/deps/` — fallback procedures for the two-level resolution: `grilling` / `domain-modeling` / `tdd` / `doc-opt` / `boundaries` (`deepwork` / `retro` / `improve-codebase-architecture` share `boundaries.md`).
+- `references/coexistence.md` — how this profile sits beside `domain-modeling`, `grilling`, `deepwork`, `tdd`, `retro`, and the first-party `doc-opt`; and how its docs/issues conventions supersede older `.scratch`-style trackers.
+- `references/deps/` — internal fallback references for the two-level resolution: `grilling` / `domain-modeling` / `tdd` / `doc-opt` / `boundaries` (`deepwork` / `retro` / `improve-codebase-architecture` share `boundaries.md`).
 
 ## Templates
 
 - `assets/templates/project/*` — the files init materializes (Chinese). They carry the provenance marker (current generation: `v2`; in `agents-block.md` it sits just under the `## Agent skills` heading) — keep it; future generations update the marker so stale copies are detectable.
-- `references/deps/*` — fallback procedures when an external skill is absent. init copies the whole directory as-is into the project's `docs/agents/deps/`; they are not materialized templates and carry no provenance marker.
+- `references/deps/*` — internal fallback references used when a standalone dependency skill is absent. init copies the whole directory as-is into the project's `docs/agents/deps/`; they are not materialized templates and carry no provenance marker.
 - `assets/templates/entries/*` — day-to-day authoring aids used when this skill is at hand (copy the skeleton when creating a new entry). NOT materialized by init; the rule docs are self-sufficient without them; materialized docs may reference their path opportunistically.

package/skills/project-docs-workflow/assets/templates/entries/current-module.md

@@ -0,0 +1,19 @@
+<!-- 文件名：<模块>.md，位于 docs/current/；记录实际能力与限制；基线默认继承 00-README.md；不写任务日志 / 待办 / 计划中的能力。 -->
+
+# <模块> 现状
+
+> 关联：[PDR <模块>](../pdr/NN-<模块>/00-README.md)（需要指向决策时可加描述性短语 + 稳定 ADR 链接，例：支持 [离线使用](../adr/0003-offline.md)；不转述 ADR 理由、不自动推断链接）
+
+<基线默认继承 `00-README.md`；仅当本文件基于不同基线时在此覆写：基线 <具体 revision / release> ｜ 快照 YYYY-MM-DD。>
+
+## 实际能力
+
+- <现已具备的能力，行为口径；对应 PDR 的 FR-<模块>-NN（如有）。>
+
+## 关键行为与限制
+
+- <关键行为 / 边界；已知限制、注意事项。>
+
+## 验证信心（仅例外时写）
+
+- <仅当某结论的验证信心需单独说明（未验证 / 推断）时列出；已按默认口径验证的结论不必逐条举证。>

package/skills/project-docs-workflow/assets/templates/entries/pdr-spec.md

@@ -2,7 +2,7 @@
 
 # <模块> 功能规格
 
-> 定位：<模块> 目标态功能规格（FR-<模块>-NN，逐条给验收判据）。依据见 [design/](design/)（无 design/ 目录则删去该链接）与相关 ADR。
+> 定位：<模块> 目标态功能规格（FR-<模块>-NN，逐条给验收判据）。依据见 [design/](design/)（无 design/ 目录则删去该链接）；需要指向决策时，用描述性短语 + 指向稳定 ADR 文件的普通 Markdown 链接（例：支持 [离线使用](../../adr/0003-offline.md)）——不转述 ADR 理由，不要求每条 FR 都挂 ADR，也不自动推断链接。
 
 ## 1. <功能分组>
 

package/skills/project-docs-workflow/assets/templates/project/adr-readme.md

@@ -17,7 +17,8 @@
   - `> 经 ADR-XXXX 修订（日期）：一句话`
   - `> 已废弃（日期）：原因`
   - `> 已删除（日期）：原因`（墓碑桩）
-- **删除或语义修改**触发引用核查：优先派 subagent，无则自行 grep `ADR-\d{4}`（范围 = 全仓库；`docs/` 必改，代码注释逐一判定：保留 / 更新 / 就地注释；逐一处理后再收尾）。引用优先改指替代 ADR 编号；无替代则删去该句或就地注明「（ADR-XXXX 已删除）」。
+- **删除或语义修改**触发引用核查：优先派 subagent，无则自行 grep；须覆盖两种写法——`ADR-\d{4}` 编号，以及指向 ADR 文件的 Markdown 路径链接（按稳定文件名 `adr/<NNNN>-<slug>.md` 匹配，相对前缀任意，如 `docs/adr/…`、`../adr/…`、`../../adr/…`，可带 `#fragment`）。范围 = 全仓库；`docs/` 必改，代码注释逐一判定：保留 / 更新 / 就地注释；逐一处理后再收尾。引用优先改指替代 ADR 编号；无替代则删去该句或就地注明「（ADR-XXXX 已删除）」。
+- PDR / Current 可用描述性短语 + 普通 Markdown 链接指向 ADR 文件（例：支持 [离线使用](../adr/0003-offline.md)），不强制写 `ADR-XXXX` 标签；不要求每条需求都挂 ADR，也不自动推断链接。路径链接在墓碑桩化后仍有效（文件名不可变、墓碑桩照常渲染）；但语义修改改变了链接所指内容，故语义修改后须重新核对路径链接，而不只是编号。
 
 ## 目录
 

package/skills/project-docs-workflow/assets/templates/project/agents-block.md

@@ -12,4 +12,4 @@
 
 ### Development workflow
 
-推荐五步流程：规划 / 骨架 / 细节 / 异常 / 回顾。开工前先读 PDR 目标与现状（各模块 `04-current.md`），与用户对齐本次范围与粒度；步骤记录在 issue 的 `## 步骤`。约定见 `docs/agents/workflow.md`。
+推荐五步流程：规划 / 骨架 / 细节 / 异常 / 回顾。开工前先读 PDR 目标（`docs/pdr/`）与 Current 现状（`docs/current/`），与用户对齐本次范围与粒度；步骤记录在 issue 的 `## 步骤`。约定见 `docs/agents/workflow.md`。

package/skills/project-docs-workflow/assets/templates/project/agents-domain.md

@@ -11,9 +11,9 @@
 - 根目录的 **`CONTEXT.md`**。
 - **`docs/adr/`**：读取与将要改动的领域相关的 ADR；规则与目录见 `docs/adr/README.md`。
 
-如果这些文件不存在，**静默继续**：不要提示缺失，也不要主动建议创建它们。`/domain-modeling`（未安装则按 `docs/agents/deps/domain-modeling.md` 执行；经 `/grill-with-docs` 与 `/improve-codebase-architecture` 到达，后者未安装则按 `docs/agents/deps/boundaries.md` 执行）会在词条或决策真正定案时按需创建。
+如果这些文件不存在，**静默继续**：不要提示缺失，也不要主动建议创建它们。`domain-modeling`（未安装则按 `docs/agents/deps/domain-modeling.md` 执行）会在词条或决策真正定案时按需创建。
 
-外部技能未安装时的兜底流程物化在 `docs/agents/deps/`。
+外部技能未安装时的兜底流程物化在 `docs/agents/deps/`。**组合回退**：`grill-with-docs` 是 `grilling` + `domain-modeling` 的包装（术语确定即写入 `CONTEXT.md`，满足三条判据记 ADR）；未安装该包装时，按 `docs/agents/deps/grilling.md` 与 `docs/agents/deps/domain-modeling.md` 交织执行。`improve-codebase-architecture` 未安装时按 `docs/agents/deps/boundaries.md` 执行。以上均为**可选的独立技能名，不代表本包已随附**；本 skill 不会自动安装它们。
 
 ## File structure
 
@@ -35,7 +35,7 @@
 
 当你的产出提到某个领域概念（issue 标题、重构提案、假设、测试名）时，使用 `CONTEXT.md` 中定义的术语。不要漂移到术语表明确回避的同义词。
 
-如果你需要的概念还不在术语表里，这本身是一个信号：要么你在发明项目不使用的语言（重新考虑），要么存在真实缺口（记下来，交给 `/domain-modeling`；未安装则按 `docs/agents/deps/domain-modeling.md` 执行）。
+如果你需要的概念还不在术语表里，这本身是一个信号：要么你在发明项目不使用的语言（重新考虑），要么存在真实缺口（记下来，交给 `domain-modeling`；未安装则按 `docs/agents/deps/domain-modeling.md` 执行）。
 
 ## Flag ADR conflicts