docs: fix re-review findings — seat-migration obligation, evidence rule moved into the standard, first-cut family settled

Restore the ReactNode seats' pending-migration obligation the earlier
rewrite had flipped into a permanent exception; state the merged-PR/issue
evidence allowance in docs/AGENTS.md itself so the citations note defers
to the standard instead of overriding it; rewrite the one current-state
'first cut' fact and record the historical-stage-name exemption (with
indexical stamps still banned); pairs re-recorded.
This commit is contained in:
Tianyi Cui
2026-08-09 17:46:21 +08:00
parent ee7458b2df
commit e697bb3ca1
8 changed files with 12 additions and 12 deletions

View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
2026-06-21-subagent-capability-seam.md: 72f17d7566aa982a5710e466cb4f740906ef167b
2026-06-21-subagent-capability-seam.zh.md: 8205a6e2eab3bdaddf25b582c590034e2cf2f8dd
2026-06-21-subagent-capability-seam.md: 28ecf985db1289ce4f80570583eac6a051cd2c0b
2026-06-21-subagent-capability-seam.zh.md: 5f349ddcacebe66c346976b822c9dcc65bda8d18

View File

@@ -73,4 +73,4 @@ Registry and tool tests replace only the nondeterministic child boundary with a
- **Recursion.** Without a bound, an in-process child can see the delegation tool and recurse. The in-process backends implement the optional absolute depth limit and scoped live-global `toolFilter`; ACP advertises both capabilities off and rejects such a request. The [subagent composition-controls Agent Note](2026-07-12-subagent-persona-tool-filter-and-depth.md) owns their exact semantics and security limits.
- **Blocking the parent turn.** Foreground collection holds the parent's step open for the child's full duration. Background delegation uses the shared `ctx.tasks` runtime and generic `task_*` tools, the same collection mechanism as background bash; the subagent seam itself remains task-agnostic.
- **Live progress.** Only lifecycle + the final result surface; a per-chunk child→parent update stream is deferred with the background redesign.
- **ACP client surface.** Proxying `fs`/`terminal` from the ACP child back to the parent (a shared-workspace mode) is future work; the first cut advertises neither, so the child self-serves in its own process.
- **ACP client surface.** Proxying `fs`/`terminal` from the ACP child back to the parent (a shared-workspace mode) is future work; the backend advertises neither capability, so the child self-serves in its own process.

View File

@@ -73,4 +73,4 @@ bash seam[能力 seam](../architecture/2026-06-13-capability-seams.md))在
- **递归。** 如果不设限制,进程内子 agent 能看到委派工具并递归调用。进程内后端实现了可选的绝对深度限制和有作用域的实时全局 `toolFilter`ACP 声明这两项能力为关闭状态,并拒绝此类请求。[subagent 组合控制 Agent Note](2026-07-12-subagent-persona-tool-filter-and-depth.md) 负责定义它们的确切语义和安全边界。
- **阻塞父轮次。** 前台收集在子 agent 的整个持续时间内保持父 agent 的步骤打开。后台委派使用共享的 `ctx.tasks` 运行时与通用 `task_*` 工具,与后台 bash 共用同一套收集机制subagent seam 本身仍不感知任务。
- **实时进度。** 仅暴露生命周期事件与最终结果;逐分片的子→父更新流推迟到后台重新设计时一并处理。
- **ACP 客户端接口。** 将 ACP 子 agent 的 `fs`/`terminal` 代理回父 agent共享工作区模式是后续工作首版不声明这两项能力,子 agent 在自己的进程中自行服务。
- **ACP 客户端接口。** 将 ACP 子 agent 的 `fs`/`terminal` 代理回父 agent共享工作区模式是后续工作该后端不声明这两项能力,子 agent 在自己的进程中自行服务。

View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
2026-08-09-committed-artifact-citations.md: 7d99a27238f25e7084fbbc816787c3c76a62bd89
2026-08-09-committed-artifact-citations.zh.md: f09ae024c480d95dc95e39c62fbd1dc31f5b92a1
2026-08-09-committed-artifact-citations.md: 890555df2968d706ba732aa8a3507bf81d187e3f
2026-08-09-committed-artifact-citations.zh.md: 7eb446cca8fc0109814a8b2669a9a7031db9647b

View File

@@ -12,11 +12,11 @@ Large design and review sessions leave working shorthand — decision ordinals,
Durable prose — comments, JSDoc, docs, notes, test comments and titles — cites only committed artifacts, resolvable in-repo without grep archaeology:
- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned in docs and code per the documentation standard; issues are durable and citable, and Agent Notes may cite merged PRs as evidence anchors — the standard routes change stories to commits, PRs, Agent Notes, and postmortems, and a note is that home.
- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned in docs and code per the documentation standard; issues are durable and citable, and Agent Notes and postmortems may cite merged PRs and issues as evidence, per the [documentation standard](../../../../docs/AGENTS.md)'s change-story routing.
- A design-session ordinal whose decision has a committed owner is replaced by the decision's name — the ordinal once logged as "decision 21" is now "the plain-text-reference decision", owned by the [web input-machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md); the ordinal itself resolves nowhere in-repo and was dropped everywhere. An ordinal without an owner is deleted and its factual clause restated to stand alone.
- Fixed regressions are pinned as present-tense counterfactuals ("without X, Y happens"; "a naive X would…"), never as repo history ("used to Y").
- Implemented notes state shipped reality: a "deferred to a later PR" claim whose target shipped names the shipped note instead.
- Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice.
- Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice. Inside a note's change-story sections, a historical stage name ("the first cut shipped X") is current-state-safe; indexical stamps ("this cut") stay banned everywhere.
One repo-wide purge applied these rules across the prose surfaces, including the generator-owned templates (`scripts/gen-doc-graphs.ts`, `scripts/gen-tool-catalog.ts`, the typert generator's page notice) with regeneration, the type-equiv source JSDoc with page re-pastes, and the bilingual counterparts with pair re-records.

View File

@@ -12,11 +12,11 @@ Status: implemented
持久行文注释、JSDoc、文档、Agent Note、测试注释与测试标题只引用已提交的产物无需 grep 考古即可在仓库内解析:
- 点名归属的 Agent Note其路径在每个文件里至少出现一次行内用可检索的名称、文档页面路径或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列issue 是持久且可引用的Agent Note 还可引用已合并的 PR 作为证据锚点——文档标准将变更故事归置于 commit、PR、Agent Note 与事后分析note 正是这一归宿
- 点名归属的 Agent Note其路径在每个文件里至少出现一次行内用可检索的名称、文档页面路径或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列issue 是持久且可引用的Agent Note 与事后分析可依[文档标准](../../../../docs/AGENTS.md)的变更故事归置规则引用已合并的 PR 与 issue 作为证据
- 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」归属于 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md);该序号本身在仓库内无从解析,已全部移除。没有归属文档的序号予以删除,其事实性语句改写为可独立成立的表述。
- 已修复的回归以现在时反事实句固定下来(「没有 X 就会发生 Y」、「朴素的 X 会……」),绝不写成仓库历史(「过去曾 Y」
- 已实现的 Agent Note 陈述已交付的现实:「推迟到后续 PR」的说法若其目标已经交付就改为点名那篇已交付的 note。
- 已录制的 fixture测试前置数据、快照与已归档的 Agent Note 不受此约束:已录制的模型输出与封存的历史保持原有行文。
- 已录制的 fixture测试前置数据、快照与已归档的 Agent Note 不受此约束:已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内,历史阶段名称(「首版交付了 X」属于安全的现状表述指示性版本戳「本版」「this cut」在任何地方都仍被禁止。
一次全仓库清理把这些规则应用到了各个行文表面,包括生成器持有的模板(`scripts/gen-doc-graphs.ts``scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语改后重新生成、type-equiv 源码 JSDoc改后把文档页重新粘贴以及双语对侧文件改后重新记录配对

View File

@@ -35,7 +35,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
## Writing rules
- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems.
- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the two documentation homes may cite merged PRs and issues as evidence.
- **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
- **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).

View File

@@ -23,7 +23,7 @@ How live data reaches render code, and what may cross a business boundary:
1. **Everything a render reads that can change outside React arrives through a framework hook** (rule 4 above). Event-handler code may read live snapshots (e.g. `keyboard.snapshot`); render code subscribes.
2. **Business components contain no subscription machinery** — no `useSyncExternalStore`, no manual subscribe wiring, no mirroring an external snapshot into local state or a second store. Give each reactive fact its owning channel instead: registrant-private → the inject `hooks` compartment; cross-entry or remount-surviving → a declared store; per-session standard → `sessions.provide`.
3. **Data-access ladder** — resolve needs in this order: framework hooks (standing seats + provide/inject-bound `use<Name>`) → a declared store (`useStore`/`actions`) → inject callbacks → anything else is a new framework extension point and needs main-thread arbitration.
4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are the sanctioned exceptions).
4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are exceptions pending migration to slots).
5. **An observable source keeps two identities stable**: the source object itself (hook binding is cached per source), and its snapshot between changes (`getSnapshot` returns the same reference until the fact moves).
6. **Whoever rebuilds a published value republishes it through the same source in the same step**, and a registration path that can run after consumers exist notifies the live consumers as part of registering.