refactor: rename bookmarks anchors→tesserae; exclude generated artifacts; verify subpackage builds - #19
Merged
Merged
Conversation
'Anchor' already named an unrelated retrieval concept in the codebase (surface anchors: explicit quoted phrases/paths/IDs indexed for exact-match retrieval), and Pi's task-anchor plus the reasoning-workspace support-anchor concepts collide with the same word. Rename the memory-bookmark feature to 'tessera' (plural tesserae) so each concept owns an unambiguous term. Core: - types: AnchorRecord/Input/Hit -> TesseraRecord/Input/Hit, ANCHOR_REF_MARKER -> TESSERA_REF_MARKER (value tessera_ref) - schema: anchors table/anchors_fts/triggers -> tesserae (content-anchored bookmark rows); forward-migration renames a pre-rename 'anchors' table in place and rewrites 'anchor_ref' markers to 'tessera_ref' - store: searchAnchors/getAnchorsByIds -> searchTesserae/getTesseraeByIds; writes plan/insert helpers renamed; context.tesserae replaces context.anchors CLI/RPC/integration: - --anchor option -> --tessera; ANCHORS: render header -> TESSERAE: - agent-surface renders 'tessera=path:line' instead of 'anchor=' - search projection exposes context.tesserae DSH plugin: nmg_remember schema exposes tesserae (bookmarks) instead of anchors. Docs: design file renamed memory-anchors-design.md -> memory-tesserae-design.md with terminology note; superseded link updated. Verification: agent:verify all blocking checks passed (check, test:product, build, docs:check, verify:static, complexity gate); 776 product tests green.
All finally-built outputs that are reproducible from source should not be tracked; they regenerate on build and tracking them keeps the tree permanently dirty with drift-prone copies. - .nmg-search-scope: runtime hot-zone manifest (absolute paths, per-machine) - dsh/dsh-nmg/lib/: tsdown build output of the DSH host plugin (src + tsdown config remain; lib regenerates via npm run build in dsh/dsh-nmg) - src/prompts/nmg-prompts.generated.ts: emitted by generate-prompts.ts from nmg-prompts.yaml during npm run build / prompts:generate - dsh/dsh-nmg/package-lock.json: npm install side effect in a linked subpackage package-lock.json at the repository root stays tracked (lockfile for the root package); this commit also syncs its root-package bin entry with package.json (nmg-rcp), which npm install had left stale.
…policy
Generated outputs are excluded from version control, so buildability from a
clean clone becomes the integrity guarantee. Add the verification that makes
that guarantee enforceable, plus the documentation of why artifacts are
untracked (and the anchors rename that motivated the governance pass).
Verification:
- tools/verify-packages.ts: install + build every subpackage with its own
package.json/lockfile from a frozen lockfile (currently dsh/dsh-nmg via
pnpm); wired into verify:static and CI's static job (corepack enables pnpm)
- tools/check-lock.ts: fail when root package-lock.json drifted from
package.json; wired into verify:static
- ci.yml: static job enables corepack pnpm before the shared contract
Docs:
- docs/decisions/rejected/2026-09-02-track-build-artifacts-in-git{.md,.zh-CN.md}:
why regenerable outputs stay untracked (lockfiles are the deliberate
exception), registered in decisions READMEs
- docs/decisions/rejected/2026-09-02-keep-bookmarks-named-anchors{.md,.zh-CN.md}:
why the bookmark feature was renamed anchors -> tesserae (surface/task/support
anchor collision)
- skills/repo-development/SKILL.md: new 'Builds and generated artifacts'
section (reproduction order, verify:packages/check:lock); AGENTS.md points at it
- .gitignore: clarify that dsh/dsh-nmg's real lockfile is pnpm-lock.yaml; the
ignored package-lock.json only appears on an accidental npm install
Verification: verify:static green (check, check:lock, lint, format:check,
docs:check 107 files 0 errors, complexity:gate, verify:packages); docs tests
12/12.
wefio
changed the title
CI's Dependency audit step failed on newly published advisories: - fast-uri <3.1.7 (high): host confusion / SSRF via IDN and IPv6 normalization (GHSA-5jgf-p345-68v8, GHSA-f65p-4m7j-42xc, ...) - qs <6.16 (moderate): array-limit bypass via bracket-key parsing npm audit fix upgraded both within their declared ranges (no overrides); audit now reports 0 vulnerabilities. check + integration tests still green.
Surface the rules added by the artifact-governance pass as explicit pre-merge checklist items so submitters verify them locally instead of relying on CI alone: - verify:static now includes check:lock and verify:packages - dependency/lockfile changes require check:lock + a clean npm audit - subpackage changes require verify:packages + a synced lockfile - regenerable outputs (dist/, dsh/dsh-nmg/lib/, generated prompts, .nmg-search-scope) must not be committed - CI confirmation: Static job includes Dependency audit; when an upstream advisory fails it, fix the lockfile rather than loosening the audit gate
Research characterization imports src/prompts/load.ts → generated prompts. Now that nmg-prompts.generated.ts is untracked (regenerated on build), the research job failed with ERR_MODULE_NOT_FOUND on a clean checkout because it ran test:research without generating first. Align it with the other verification contracts: run prompts:generate first, like verify:static and verify:product-ci already do.
repo-development SKILL now tells an agent what to do when opening a PR and writing a commit, reusing the template as the checklist instead of duplicating it: - Commit: conventional style (type(scope): summary + what/why body), one change per commit, and no claim of a passing check unless it actually ran. - Pull request: read .github/pull_request_template.md and follow it as the PR prompt — fill What/Why/Changes from the change and self-check every box before marking ready. The template stays the single owner of the checklist; the SKILL points at it.
agent:verify auto-discovers the covering contract for ordinary changes, so the SKILL only ever pointed at it — the standalone nmg-rcp CLI (forge-status, plan/compile, receipt-*, reconcile --apply, forge-bind/create) was documented in ci-cd-and-quality.md §7.11 but never surfaced at the agent's decision point, so agents reached for ad-hoc commands instead. Add a section listing the exact scenarios that need manual nmg-rcp, each with the trigger and command, and state the governing rule: when a tool improves, update its owning documentation in the same change — an undocumented improvement is one agents will not use.
Position the template as the operation-layer checklist: each RCP item now carries the exact command that self-verifies it, so a submitter (human or agent) can work through the boxes without consulting the SKILL first — nmg board put for the in-flight goal, agent:verify / nmg-rcp reconcile for evidence, and nmg-rcp forge-status --pr for CI observation instead of manual polling. The SKILL's 'Repository Control Plane beyond agent:verify' section remains the detailed operator manual the template points at.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
变更描述
What（做什么）
将记忆书签功能从 "anchors" 改名为 "tessera"（复数 tesserae），并同步排除可自动再生的产物出版本库。
Why（为什么）
Changes（改动）
AnchorRecord/Input/Hit→TesseraRecord/Input/Hit；ANCHOR_REF_MARKER("anchor_ref")→TESSERA_REF_MARKER("tessera_ref")；anchors表/索引/FTS/触发器 →tesserae（含旧库前向迁移：RENAME + marker kind 重写，实测真实库 45 行完好迁移）。searchAnchors→searchTesserae、getAnchorsByIds→getTesseraeByIds、--anchor→--tessera、ANCHORS:→TESSERAE:渲染、search projection 暴露tesserae。tesserae。memory-anchors-design.md→memory-tesserae-design.md（含 terminology note）+ superseded 链接更新。.gitignore新增.nmg-search-scope、dsh/dsh-nmg/lib/、src/prompts/nmg-prompts.generated.ts、dsh/dsh-nmg/package-lock.json并git rm --cached清残留；根package-lock.json保留并同步 nmg-rcp bin 行。verify:packages（frozen-lockfile 逐子包 install+build，现覆盖 dsh/dsh-nmg pnpm）+check:lock（根 lock 与 package.json 漂移检测）接入verify:static与 CI static job（corepack 启用 pnpm）；CI 在 clean checkout 验证"产物排除后仍可复现构建"。docs/decisions/rejected/双语 ADR 两条（产物为何不入库 / anchors 为何改名）+ decisions README 登记；skills/repo-development/SKILL.md新增 "Builds and generated artifacts" 节 + AGENTS.md 指向。本地质量检查
npm run agent:verify：check / test:product（776 tests）/ build / docs:check / verify:static / complexity:gate 全部 blocking 通过npm run verify:static全链绿：check / check:lock / lint / format:check / docs:check（107 files, 0 errors）/ complexity:gate / verify:packages（dsh/dsh-nmg frozen-lockfile install + tsdown build）npm run check/lint/format:check通过npm run build可正常再生 generated.ts（工作树保持干净）RCP
1788363021276_000009）