[Lumos-789]

Plugin type (required) / 插件类型（必填）

• UI Plugin / 是 UI 插件 — provides MCP Apps interactive pages / 提供 MCP Apps 交互页面
• Standard plugin / 普通插件（非 UI） — does not provide MCP Apps interactive pages / 不提供 MCP Apps 交互页面
• Not applicable / 不适用 — repository-only changes; no plugin content changed / 仅仓库级改动，不涉及插件内容

Affected plugin name(s) / 涉及的插件名称：guster

What / 改动内容

EN — Adds guster, an agent-context manager: it discovers, audits, plans and evolves the context an agent actually relies on — projects, entry documents, skills, tools, knowledge and credential references — and can scaffold a lightweight Guster Hub for durable project state.

• status, scan, doctor and score report drift, broken pointers and the resident budget; every command that moves workspace files or writes Guster config (apply --yes, init --yes, hub init --yes, hub attach) needs a plan and an explicit --yes.

• Scoring is deliberately honest about missing evidence: an empty denominator reports n/a instead of 1.0, a failed git probe becomes a loud git-unavailable finding instead of looking clean, and credentials registered in the credentials registry are no longer penalised.

• Workspace/group checkout roots are marked as containers and skipped, so they stop inflating Projects: and permanently failing placement.

• A versioned context format spec (skills/guster/reference/spec.md, CTX-01..09, markdownlint-style stable IDs) defines the shapes doctor can verify: AGENTS.md instruction files, llms.txt-shaped indexes, machine-verifiable pointers (including ~-prefixed cross-repo links), machine-readable dates, the six .agents/ slots, one home per fact, skill metadata budgets, credentials by reference, and opt-in Obsidian-convention note headers (note-header-malformed).

• A legacy reformat playbook (reference/reformat.md) guides an agent that inherits a scattered, pre-spec context site: classify every artifact before touching it, place before rewriting pointers, transform content per a CTX symptom table, then verify with doctor / score --trend — meaning-preserving, never auto-deleting. Field-tested on two real projects; the lessons (search referencers by stem before a move, override shape-based slot suggestions by classification, drop .moved.md transition pointers once referencers update) are folded back into the playbook.

中文 — 新增 guster：发现、诊断、规划与演进全机 agent 上下文（项目、指令、Skill、工具、知识与凭据引用），可初始化轻量 Guster Hub 承载长期状态。指标口径对缺失证据诚实（空分母记 n/a、git 探测失败显式报警、已登记凭据不再扣分），工作区容器不再被当作项目计分。带版本化的上下文格式规范（CTX-01..09 稳定规则 ID，定义 doctor 可机检的文档形态），以及一份遗留上下文格式化 playbook——指引 agent 把散乱的前规范上下文按四遍法（盘点分类→先落位→后内容→doctor 验证）收进格式契约，保义不造事实、删除先经用户批准。

Visible behavior and testing / 可见行为与测试

• python3 -m unittest discover -s tests → 74 passed; node --test tests/test_plugin.mjs → 2 passed (macOS 27.0 arm64, Python 3.14.4).
• Run against this machine's real layout: Projects: 62 (workspace containers: 2), PCR 9/41 compliant (25 extra entries, 3 missing slots, 4 no index), CHI 77.2 → 77.4 after the container correction — a denominator fix, not a governance win.
• Degradation paths exercised: a repository with git unavailable produces the git-unavailable finding and marks credentials unverified; a scope with no evidence reports CHI: n/a.
• Docs checked against behaviour: the previously documented “red-line failures override the score” rule was never implemented and is gone; doctor exit codes (3 critical / 2 high) are what enforce criticals.

Not covered by this round / 本轮未覆盖：

• The plugin has only been run on macOS with a single-host layout; Windows paths and multi-host hubs are unexercised.

Version and marketplace registration / 版本与市场注册

• New plugin directory external_plugins/guster/ (38 files), manifest and marketplace.json entry both at 0.7.3.
• Category developer-tools; icon added at the repo-root path the entry uses (assets/guster/icon.png, 512×512).
• description_i18n carries en and zh-CN, identical in both files; README.md / README_CN.md both present.

Dependencies, network, permissions, side effects / 依赖、网络、权限与副作用

• Python 3.9+ and the standard library only — no pip dependencies.
• git is optional: when it is missing, tracked-file and commit-date probes degrade to a named finding rather than a clean result.
• State written under ~/.agents/guster/: registry.json (any scanning command), findings.json (doctor), metrics.jsonl (score); --no-write suppresses all three.
• Reads entry documents, skills, tool configs and .env key names; credential values are referenced by path or variable and never stored or printed. No network access and no telemetry.

Licensing / provenance / 许可与来源

• MIT (LICENSE ships in the plugin directory); code written for this submission.
• No third-party code, assets or services.

Self-check / 自查清单

• Plugin name is unique kebab-case; new external plugin directory is external_plugins/guster/; existing fixes retain ownership / 插件名唯一且 kebab-case，外部新增插件位于 external_plugins/guster/，已有插件修复保留原归属
• Usage category is set independently of publisher ownership / 用途分类 category 已填写，与维护归属分开：developer-tools
• Plugin type and affected names are declared above / 已在上方声明插件类型与涉及的插件名称
• version bumped in BOTH plugin.json and marketplace.json (artifacts are immutable) / plugin.json 与 marketplace.json 两处版本号已同步升级：0.7.3
• README.md (EN) and README_CN.md (中文) both updated and equivalent / 中英文 README 均已更新且语义一致
• description_i18n has both en and zh-CN / description_i18n 包含 en 与 zh-CN
• No secrets, machine-specific paths, or private dependencies / 不含密钥、机器专属路径或私有依赖
• Model/API/network dependencies documented / 模型、API、网络依赖已写明（见上方依赖小节与两个 README）
• python3 scripts/validate.py passes on this branch, and the plugin artifact was built through the same build_zip() code path CI uses (size and sha256 in the comment below). The full python3 scripts/build_dist.py needs the repo's UI-plugin pnpm build and fails identically on upstream main (excalidraw: incomplete build), so CI runs it here — see the note above. / 本地 validate.py 通过，本插件产物用 CI 同一条 build_zip() 路径打出（体积与 sha256 见下方评论）；完整 build_dist.py 依赖仓库自带 UI 插件的 pnpm build，在 main 上同样失败，交由 CI 执行

[Lumos-789]

0.5.4 — verification (2026-11-04)

Environment: ZCode CLI 0.17.1, macOS 27.0.1 arm64, Python 3.14.4.

Installed from a local marketplace → guster@0.5.4. Both skills resolve from the plugin cache (skills/guster/SKILL.md, skills/guster-hub/SKILL.md), not from a repo checkout.

Ran the bundled CLI from that installed cache against a one-project scratch root:

Step	Result
bin/guster scan --root <root>	discovery summary only (projects, .agents, skills, knowledge, state)
bin/guster doctor --root <root>	scoped report with CHI: 70.0 / 100 (project scope) and an explicit “machine-level findings hidden in project scope” section
bin/guster plan findings	review checklist, one item per finding; nothing applied

Repo-side gates for the same tree: python3 -m pytest tests -q → 48 passed, node --test tests/test_plugin.mjs PASS, plugin_acceptance.py PASS guster@0.5.4, marketplace_check.py OK (codex, zcode, package and __version__ all read 0.5.4).

Not covered: a machine-wide doctor/apply round against a heavily drifted home directory — that writes plans and needs an operator in the loop.

[Lumos-789]

Addendum — also run inside a real ZCode agent session

Not only the CLI from the cache: a headless ZCode session (sess_08ba1068-7b27-43bf-a85d-a5e3f2cb3e65) with the skill forced by its qualified name. The agent ran guster status, scan --root <project> --json and doctor --root <project>, reported CHI 70.0 / 100 (project scope), one INFO-level finding, the five machine-level findings hidden by project scope, and that the project itself has no AGENTS.md / .agents/ slots yet. It did not run plan or apply.

[panda920]

✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically.

[Lumos-789]

Third round — review & simplification (2026-11-05)

No new features this round. The question was: is the documentation still true, is the same knowledge stored twice, is anything built for a case that does not exist.

Two claims in the docs were wrong, and they are user-visible:

• The plugin claimed "read-only by default: status, scan, doctor and score report drift". That is not what the code does: scan rewrites registry.json, doctor writes findings.json, and score appends metrics.jsonl under ~/.agents/guster/ unless you pass --no-write. The README, AGENTS.md and the skill now disclose the three state files and the --no-write switch, and the PR description matches.
• FRS was described as counting "every document on the state plane". It counts documents under four prefixes (projects/, handoff/, provision/, .agents/plans/). Also, profile: in hub.yaml is a label — the scanner walks directories that exist, it does not switch modes.

Dead code removed (218 lines of src/, 4119 → 3901): every deletion was pre-verified as zero-call.

Removed	Why it could not run
hosts scan + 7 helpers + registry field	no reader in policy/metrics/report/cli
evidence-in-plans rule	.agents/plans only collects .md/.json/.yaml/.yml, so media files never reach it
append operation chain	no plan generator emits append; the executor branch was unreachable
unclassified artifact scan	summary.unclassified has no consumer
4 helpers, PATH_KEYS, --strict, a batch of parameters nothing read	zero references

Verification: 55 Python tests + 2 Node tests pass (I re-ran both independently of the agent that made the change); a real CLI smoke pass covered scan/doctor/score/status/link/export, hub init → validate → doctor --scope hub, and plan move → apply --yes.

Payload: re-synced, 36 files, verified blob-by-blob against Lumos-789/guster@dba81ec.

Not verified this round: no change was made to scoring behaviour beyond removing unreachable code, so I did not re-run the multi-project CHI comparison from the previous comment.

[panda920]

✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically.

[Lumos-789]

Payload refreshed to 0.6.0 (f6509c4, 36 files, verify_pr_payload.py → MATCH against Lumos-789/guster@2be915d).

This round is a measurement-honesty pass: the index used to claim knowledge it did not have.

before	after
an empty denominator scored 1.0	n/a, dropped from CHI, weights renormalized
a failed git ls-files/git log read as "nothing tracked" / "no dates"	None, a git-unavailable finding, SIR counts it as unverified
SIR penalised credentials already declared in registry.md	numerator is unregistered-outside + tracked + unverified + inline
a filename date was any 8-digit run (ticket-20261105-…)	must open the name (2026-11-05-…, 20261105-…)
最后更新 matched anywhere in the body	first 40 lines only
directory pointers (knowledge/general/) were invisible to PHR	counted, and resolved against the enclosing repo root
resident budget read a hardcoded ~/.zcode/AGENTS.md	probes the host entry files that exist, deduped by real path
status mixed a cached registry with a fresh policy pass	reports the stored snapshot and says so

Effect on the author's machine: SIR 31.4 → 92.0 and PHR 95.8 → 97.6, CHI 70.9 → 77.2 — not because governance improved, but because the old numbers were wrong. 30 of 31 in-place company .env files were being counted as failures while the matching finding was already waived.

Two documentation corrections that matter for reviewers:

• The README/skill claimed "red-line failures override the score". No such code ever existed; critical findings only set doctor's exit code (3 critical / 2 high). The docs now say that, and score --fail-under N is the explicit gate.
• The previous PR body said "Requires Python 3.10+"; requires-python has always been >=3.9, and the body is corrected.

Verification: 64 Python tests + 2 Node tests, py_compile, zcode plugins validate, marketplace_check (zcode=6 codex=4), simplify_gate, public_release_gate repo (0 blocking), and a real score/doctor/export run on this machine. The CLI is 3.9-compatible by construction (typing generics + from __future__ import annotations); this machine only has 3.14, so 3.9 itself is not executed here — flagging that rather than claiming it.

[Lumos-789]

Payload refreshed to 0.6.1 (fe9f22b, 36 files, verify_pr_payload.py → MATCH against Lumos-789/guster@a6ee57a).

One correctness fix on top of 0.6.0: workspace/group containers were being scored as projects.

~/IdeaProjects and the per-group checkout roots (ame-dev/, bar-dev/, …) carry group-level AGENTS.md files, so the scanner treated them as projects:

• Projects: reported 64 when there are 62 repositories;
• one container has a partial .agents/ (a single plans/ slot, no index), so it sat in the placement denominator forever as a failure that no amount of tidying could clear — and it also depressed index coverage.

Containers are now marked in registry.json and skipped by PCR/ICR. The report reads Projects: 62 (workspace containers: 2).

Same commit makes PCR answer the question a reader actually has. It used to print 9/41 compliant — a number that looks like a crisis and says nothing about what to do. It now prints 9/41 compliant (25 extra entries, 3 missing slots, 4 no index): the shortfall is classified, so the fix is obvious (move task bundles under evidence/).

I also wrote down two boundaries rather than "fixing" them, because both looked like bugs and neither should be one:

• PCR's denominator stays adopters-only. A repo whose sole context asset is one well-placed AGENTS.md has nothing to place; requiring six empty slot directories there would be structure theater, which contradicts the plugin's own position (ask why a thing must exist). <repo>/skills/ is likewise product source in a skill repository — I checked the four repos that would have been flagged and all four are legitimate (Claude's .claude/skills/ convention, or skills-as-product).
• SIR does not scan arbitrary file content for token shapes. SIR covers credential files plus literal tokens in host configuration; content scanning belongs to the release gate. Claiming more coverage than was measured is the same class of error 0.6.0 set out to remove.

Tests: 66 Python + 2 Node; marketplace_check, simplify_gate, public_release_gate all green.

[Lumos-789]

Re-pushed this branch as 282cfed0 and fixed two classes of defect that were ours, not the repository's. Nothing about the plugin's behaviour changed.

1. The PR now follows .github/PULL_REQUEST_TEMPLATE.md. The body had drifted into hand-written prose and lost the two parts a reviewer checks first: the Plugin type declaration and the Self-check list. Both are back, the five sections CONTRIBUTING asks for are filled in (problem / visible behaviour and testing / version and marketplace registration / dependencies and side effects / licensing), and the title carries the (<plugin-name>) scope the template requires for the squash commit on main.

2. The entry named the repo-root assets/guster/icon.png, but that file was never uploaded with the branch — the catalogue would have shown a broken icon. It is committed now (512×512) and the entry uses the same absolute CDN form as every other icon-bearing entry in marketplace.json.

Re-verified against the branch itself (not a local checkout):

check	result
python3 scripts/validate.py @ 282cfed0	OK: 53 plugin(s) validated
plugin artifact via build_zip() — the same code path CI runs	78477 B, sha256 9241f982b066295e7c267a2cd4d99fc4820a9d82d0ce0f44ecb81275f03e1a25
assets/guster/icon.png	present, 512×512
README.md + README_CN.md in the payload	both present

Request: the earlier validate status was bound to fe9f22be, so it is stale after this push. Could you re-run the external validation on 282cfed0? The full build_dist.py still needs the repository's UI-plugin pnpm build and fails identically on main (excalidraw: incomplete build; run pnpm build first), which is why I am relying on CI for that step.

中文摘要：本轮只补元数据与载荷完整性 —— 恢复了模板要求的插件类型声明与自查清单、标题加上 (插件名) scope（模板说明该标题会成为 main 上的 squash commit）、把条目引用的根级图标真正提交并以 CDN 绝对地址引用。分支上 validate.py 通过，插件产物按 CI 同一代码路径打包成功（体积与 sha256 见上表）。旧的 validate 状态绑定在 fe9f22be 上已失效，请在 282cfed0 上重跑一次校验。

[Lumos-789]

Update: payload bumped to 0.7.1 (head 07e1092). Payload refreshed to the current main repo (byte-identical, verified MATCH). This round is a behavior-preserving cleanup: redundant comments and dead code removed, docs re-aligned with the code. Full test suite, packaging gates (plugin acceptance / simplify / public release) and the install lifecycle matrix all pass locally.

[Lumos-789]

Payload refreshed to 0.7.3 (head 4e0ddbd, 38 files, byte-identical to Lumos-789/guster@main). Two version increments since the last update:

0.7.2 — CTX-09 structured note headers (opt-in). Knowledge notes may carry YAML front-matter following the Obsidian properties convention (the interchange format Foam/Quartz/Logseq also accept — guster defines no schema of its own). A header that declares type: is machine-checked (note-header-malformed): it must parse and carry a machine-readable date, and the note's body then joins the CTX-03 pointer scan. Legacy prose notes without type: are unaffected — verified against a real hub (58 findings, unchanged before/after).

0.7.3 — legacy context reformat playbook. skills/guster/reference/reformat.md: step-by-step guidance for an agent that inherits a scattered, pre-spec context site — classify every artifact before touching it, place files before rewriting pointers, transform content per a CTX symptom table, then verify with doctor (zero new findings) and score --trend. Meaning-preserving: deletions and distillations are proposed to the user, never silent.

Field-tested on two real projects before this push:

• A repo with a stray root state doc and a research note parked at the top of .agents/: moved via plan move (backup + pointer), the stale referencer in AGENTS.md that the move surfaced was fixed, the transition pointer removed — findings 1 HIGH + 1 MEDIUM → 0, CHI 75 → 100.
• A migrated repo whose standard doc still linked its pre-migration home (../knowledge/..., target gone): .agents/ scaffolded via plan init, the broken cross-repo link repointed to the hub (~-prefixed links are resolved by the pointer check, so it stays machine-verified), CTX-04 date lines added from git dates. PCR/ICR n/a → 100.

The lessons from those runs (search referencers by stem before a move; override shape-based slot suggestions by classification; drop .moved.md transition pointers once referencers update) are folded back into the playbook — the doc shipped here is the tested one.

Tests: 74 passed (unittest) + 2 passed (node), Python 3.14 / macOS arm64. Not covered: Windows paths, multi-host hubs, non-macOS (unchanged from the last update).