[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 validates or scaffolds a declarative Guster Hub for durable project state.

• status, scan, doctor, score and the one-pass check patrol report drift, broken pointers and resident budgets; 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, with per-plan backups and rollback. State writes are concurrency-safe (atomic replace + file lock).
• A versioned context format spec (skills/guster/reference/spec.md, rules CTX-01..10, markdownlint-style stable IDs) defines the shapes doctor can verify — AGENTS.md instruction files, llms.txt-shaped indexes, machine-verifiable pointers, machine-readable dates, the six .agents/ slots, one home per fact, credential references, and a machine-readable project registry checked by a three-way registry-drift diff (machine table ↔ hub table ↔ disk). A legacy-reformat playbook and a new-project onboarding playbook ride along.
• JSON Schema contracts (draft 2020-12) for hub.yaml and the plan JSON ship in schemas/; the scaffolded hub manifest carries a yaml-language-server modeline, so the VS Code YAML extension validates it with zero configuration, and an agent hand-writing a batch plan has the exact field contract.
• The hub is declarative (hub.yaml, schema 2): sections may live outside the hub root, zones support light profiles, first run probes conventional roots under a banner and never silently scans the whole home directory, and zones add|remove manages machine zones.
• Scoring stays honest about missing evidence: an empty denominator reports n/a instead of 1.0, a failed git probe becomes a loud git-unavailable finding, and a waiver greens the gate but never the score.

中文 — 新增 guster：发现、审计、规划与演进 agent 真正依赖的上下文（项目、入口文档、Skill、工具、知识与凭据引用），校验或脚手架化声明式 Guster Hub 承载长期状态。格式契约版本化且开源惯例有出处（CTX-01..10：AGENTS.md、llms.txt 形态索引、可机检指针、机器可读日期、六槽位、一事一仓、凭据引用、三方对账的机器可读项目登记表），并附遗留格式化与新项目开张两份 playbook；hub.yaml 与 plan JSON 附带 JSON Schema（draft 2020-12）契约，脚手架 manifest 自带 yaml-language-server modeline 零配置可校验；首跑探测+横幅绝不静默扫全 HOME，check 一条命令巡检，状态写入原子+并发安全；指标对缺失证据诚实，waiver 只让门禁变绿不改分数。

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

• python3 -m unittest discover -s tests → 159 passed; node --test tests/test_plugin.mjs → 2 passed (macOS arm64, dev runs on stock Python 3.14, code targets 3.9+).
• Sandbox new-user walkthrough (fresh home, ~/code layout): probe banner, init pinning, project onboarding loop, check, registry-drift round-trip — 7/7; a two-process write race read zero torn registry updates (atomic replace + file lock).
• 0.9.1 smoke on an isolated HOME: init → hub init → hub validate OK → plan findings output re-validated against schemas/plan.schema.json, rendered hub manifest against schemas/hub.schema.json (modeline on line 1).
• Each release since 0.7.4 came out of a fresh-eyes review round with every defect reproduced first — e.g. 0.9.1's superseded_by note key leaking into the naked-pointer scan (front-matter is now stripped before pointer extraction) and plan version: true passing as 1 via bool/int coercion.
• 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.

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/ (40 files), manifest and marketplace.json entry both at 0.9.1.
• 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), plus config.json and a .lock in the state dir; --no-write suppresses each command's own state file.
• 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.9.1
• 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).

[Lumos-789]

0.7.4 — fresh-eyes review round, every defect reproduced first.

• The opt-in note-header check flagged legacy prose notes that declare no type:, violating the CTX-09 opt-in contract ("checked only when it declares type:") → notes without type: are now left alone regardless of shape.
• YAML block-scalar headers (updated: |) parsed as malformed → supported, consistent with the front-matter parser.
• A failed batch apply rollback left a .moved.md pointer claiming a move that had been rolled back → pointers and fresh writes are now backed up and rolled back with everything else.
  Tests: 80 passed (was 74) + node 2. Manifest + marketplace entry at 0.7.4.

[panda920]

Thanks for the contribution! This PR no longer applies cleanly on top of the latest main (conflicts in: marketplace.json). Please rebase onto main and push again; it will be picked up automatically.

🤖 Copy this prompt into Claude Code / Codex to fix it

You are updating my pull request #170 to github.com/zai-org/zcode-plugins (the ZCode plugin marketplace).
The maintainers' automated intake reported: the PR conflicts with the latest main

Conflicting files: marketplace.json

Fix it in this repository:
- New external plugins belong under external_plugins/<my-plugin>/; keep existing plugins in their current directory;
  never modify .github/, scripts/, tests/, .gitignore, .gitattributes or AGENTS.md.
- Follow CONTRIBUTING.md and AGENTS.md: the manifest lives at <plugin-directory>/.zcode-plugin/plugin.json,
  its name/version must match marketplace.json, names are kebab-case, keep the required i18n fields.
- Fetch the latest main of zai-org/zcode-plugins and rebase onto it; if marketplace.json conflicts,
  keep every existing entry and re-add mine.
- Run `python scripts/validate.py` until it passes, then force-push my PR branch.

[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 updated 0.7.4 → 0.9.1 (head 1e7ffd7, 40 files, verified byte-for-byte against the source repo).

What changed since the last push:

• 0.8.0 — declarative hub: hub.yaml contract (schema 2, sections may live outside the hub root), configurable zones with light profiles, de-privatized defaults.
• 0.9.0 — installed and fully usable: first-run probing under an explicit banner (the silent whole-home fallback is gone), guster check one-pass patrol, zones add|remove, uniform fail-loud config validation, registry-drift three-way diff (machine table ↔ hub registry table ↔ git roots), concurrency-safe state writes (atomic replace + file lock), new-project onboarding playbook in the skill. 145 tests.
• 0.9.1 — format-spec release: JSON Schema (draft 2020-12) contracts for hub.yaml and the plan JSON in schemas/, yaml-language-server modeline on the scaffolded manifest, CTX-09 optional note keys (name/description/superseded_by), front-matter excluded from pointer scans, open-conventions sourcing (AGENTS.md, llms.txt shapes, YAML front-matter, markdownlint-style rule IDs). 159 tests + 2 node.

[panda920]

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