A source-of-truth link did not make the review obligation explicit, so reviewers could treat green documentation checks as sufficient. Make dsh-prose-standard a blocking requirement for every added or changed prose form and require semantic comparison with the owning code or behavior.
A saved complete-file candidate could overwrite newer skill guidance, while a provider-wide outage was indistinguishable from a healthy no-op run. Record the source blob and provenance, reject drift during promotion, and make total adapter failure visible.
Align cadence and feedback acquisition with the evidence contract, and narrow the borrowed-state and negative-control checks so they do not contradict the package and testing standards.
Move the agent-spine bundle and the stdio/ACP/JSON-RPC app packages out of
core/ and ui/ into a new packages/examples/ group, renamed with a -demo
suffix so the npm name marks them as non-product surface:
core/agent-core -> examples/agent-spine-demo (dsh-agent-spine-demo)
ui/stdio-agent -> examples/stdio-demo (dsh-stdio-demo)
ui/acp-agent -> examples/acp-demo (dsh-acp-demo)
ui/jsonrpc-agent -> examples/jsonrpc-demo (dsh-jsonrpc-demo)
Update every code/config/test reference and reference-only doc mentions, and
regenerate module-graph, config-catalog, and doc-graphs. The jsonrpc bin
(dsh-jsonrpc-agent) and single-file exe (dsh-jsonrpc-agent-pkg) keep their
names; the SDK runtime-startup surface is reconciled separately.
Verified against gh: --base filters server-side and exactly, so any
open dependent guarantees a non-zero print, but --jq length counts the
fetched page and gh's default --limit is 30 (--limit 5 prints 5 when
the true count is 20). The printed number is min(actual, limit), so the
skill no longer claims it as the auto-close count; only 0 clears a
delete.
Review comment on the verify step: dumping every open PR under
--limit 1000 wastes agent context and re-truncates past 1000. Ask the
exact question server-side instead: gh pr list --state open
--base <branch> --json number --jq length, whose output is a single
count that is exact at any number of open PRs. Skill, checklist, and
the cookbook dependent-check line all use the per-branch form.
Second review round: 'gh pr merge' can return after merely enabling
auto-merge when required checks are pending or a merge queue is active,
so retargeting the next PR could run against a master that does not yet
contain the parent. The procedure and checklist now require
'gh pr view <n> --json state' to report MERGED after every merge.
Codex review caught three procedure defects: the dependent check used
bare 'gh pr list', whose default pagination can hide an open dependent
and make branch deletion look safe (now --state open --limit 1000); the
refresh step merged local master, which 'gh pr merge' leaves stale (now
fetch and merge origin/master); and the quick checklist omitted pushing
the dependent after the local merge.
Commit the stacked-PR landing procedure as a repo skill so every
collaborator's agent discovers it: merge bottom-up, retarget and refresh
each dependent, and delete no branch until the whole stack has landed
(deleting a base branch auto-closes the open PR that bases on it).
The responding-to-pr-review-on-a-stack cookbook guide's dependent-check
step links the skill as the full landing procedure.
Define the in-file RFC contract in docs/rfc/README.md § The file format:
the header block (`# RFC: <title>` plus a dateless Status enum
cross-checked against the lifecycle folder), the per-lifecycle body
skeleton (a Problem opener everywhere; Proposal/Alternatives considered/
Acceptance criteria/Risks in proposed/; present-tense Decision/
Consequences with proposal-era headings banned in implemented/; the
frozen proposal shape in rejected/), and a mandatory Alternatives
considered section with a date-fenced grandfather comment for pre-format
RFCs whose alternatives are not reconstructible from the record.
Enforce it with a new doc-sync gate, scripts/verify-rfc-format.ts, and
normalize all 112 RFCs to it: ~15 Status-line spellings collapse to the
enum, 29 Context openers become Problem, the 39 legacy-format XXX debt
markers are resolved and banned from reappearing, proposal-era sections
in implemented RFCs are rewritten to shipped reality (including the
web/fs/subagent seam RFCs' migration plans and test checklists, closing
the doc-tiers deferred-work item on the web seam), every RFC gains an
Alternatives considered section or the grandfather comment, and the
bilingual pair is re-mirrored and re-recorded.
Move the generated index tables out of README.md into a fully generated
docs/rfc/INDEX.md — gen-rfc-index now writes the whole file, and
verify-rfc-classification checks its freshness and rejects index-shaped
rows in the curated README — which makes room for the format contract to
live in the README front door instead of a separate FORMAT.md.
The decision record, and the first RFC written in the new format, is
docs/rfc/implemented/process/2026-07-05-uniform-rfc-format.md.
Human-annotated gold pairs land as docs/i18n/style-samples.md (bilingual
by construction, excluded from pairing) and outrank prose tone rules.
translation-rules gains a Voice section; shape stays gate-owned so the
writer optimizes for natural Chinese. The skill's translate step becomes
two passes: native-author writing, then clause-level fidelity check.
Terminology rulings: hash -> 哈希 (blob 哈希/提交哈希), HMR and fiber
confirmed as tabled.
Master's docs-overhaul stack (#142-#144) rewrote AGENTS.md into the
slim budget-gated form and repointed the review skill's citations.
Resolutions:
- AGENTS.md: master's rewrite wins; the no-hardcoded-tunables
convention is re-added as one terse bullet in the new style, after
'Explicit > implicit at package seams'. Within the verify-doc-budgets
ceiling, so no displacement or raise needed.
- dsh-code-review SKILL.md: master's repointed citations win; the
hardcoded-tunables reviewer check and the Conventions keyword are
re-applied on top.
- packages/README.md: master replaced the hand-maintained dependency
list (which carried this branch's chars-per-token wording) with a
pointer to the generated module graph — master's side taken whole;
the estimator wording lives on in the compact package READMEs.
A number or string that two reasonable deployments could want set
differently — a timeout, grace period, output cap, result-count limit,
model name, base URL — belongs on the plugin's schemastery Config with
the shipped value as its default, not in a bare literal or module
constant. A DEFAULT_* constant or a test-only injection seam is not
configurability: the test is whether a cordis.yml deployment can change
the value without a code edit. Protocol/wire constants, semantic
constants, values pinned by an external spec, and security invariants
stay hardcoded.
The convention lands in AGENTS.md § Conventions (the authoritative
source the review skill cites); dsh-code-review gains the matching
reviewer-only check, since no mechanical gate can detect a hardcoded
tunable.
Exact-size ceilings turned every two-word wording fix into a gate
event. The policy amends to: a ceiling sits at least 5% above the
doc's current size (pre-rewrite) and keeps that margin when ratcheted
to target — routine edits pass, real growth still trips the gate.
Amended together in all four policy homes (docs/AGENTS.md § Budgets,
the doc-tiers RFC, the gate script's module comment, the skill's
ratchet rule) plus the manifest values, so prose and mechanics stay
consistent.
Applies the documentation standard to its biggest offender. Every rule
survives as one to three lines plus a link to its durable home; the
stories, duplicate statements, and re-narrations go:
- Situational clusters evict to new homes: docs/testing.md (tiers,
with-key policy, real-over-mock, world-verification, real-entry-path
guards), docs/defensive-patterns.md (the bug-class rules), and
docs/cookbook/responding-to-pr-review-on-a-stack.md (the stacked-PR
review procedure).
- Doc-authoring rules consolidate into docs/AGENTS.md § Writing rules
(current-state-never-history, md-wrap, ts-block compilation, @mode,
catalog same-change, pair same-change).
- packages/README.md drops to the group table + the extension-vs-bundle
dependency rule; the hand ASCII graph yields to the generated
module-graph.md; group READMEs are the canonical per-package map.
- packages/AGENTS.md keeps only its packages-specific rules (export
shape, ctx.get, real-Loader coverage); examples/AGENTS.md repoints
its with-key-policy link; rfc/README.md loses a narrated-history
aside; dsh-code-review / dsh-find-simplifications / verify-md-wrap
references follow the moved content.
- Budget manifest ratchets: AGENTS.md 8200 -> 1500 (now 1,495 words),
packages/README.md 1900 -> 600, packages/AGENTS.md 600 -> 450; the
two new eviction docs join the budget set (testing 800, defensive
550); docs/AGENTS.md raises 1000 -> 1250 for the absorbed writing
rules (the one justified increase). The doc-tiers RFC's deferred list
prunes the two items this change ships.
Standing docs accrete a paragraph per PR with nothing pushing back; the
root AGENTS.md reached 8,130 words in 50 commits with the same rule
stated two and three times. This encodes the counter-pressure:
- docs/AGENTS.md becomes the documentation standard: the tier taxonomy
(one home per fact), target word budgets, and the slop checklist.
- verify-doc-budgets joins doc-sync: word ceilings for the six
accretion-prone standing docs, manifest-driven, frozen at current
sizes and ratcheted down as each doc is brought to target.
- .agents/skills/dsh-doc-standards: the thin placement/audit/red-gate
workflow over the standard, mirroring the dsh-translate-docs split.
- RFC (implemented/process) records the decision, alternatives, and
the first audit cycle's deferred work list.
The gate's first catch was the standard itself (1,057 > 1,000); it
ships condensed to 984 words rather than with a raised ceiling.
Redesign per review: neither language is canonical. A pair is three
sibling files — foo.md, foo.zh.md, foo.i18n.yaml — and either language
may be authored first (a Chinese-first RFC is as legitimate as an
English-first one). The sidecar record holds the FULL git blob hash of
both sides as of the last confirmed-consistent state, replacing the
in-file one-directional fingerprint; editing either side without
re-confirming the pair goes red. New --write mode re-records a pair
after both sides are brought in line, making the confirmation a
reviewable yaml diff. Pairs merge whole (completeness enforced).
- gate rewritten around pair anchors (union of .zh.md and .i18n.yaml
remnants) so half-deleted pairs are caught from either side; red/green
proven for en-only edit, zh-only edit, missing record, and a record
for an excluded file
- verify-rfc-classification now skips .zh.md counterparts (same RFC,
indexed via its English filename; the pairing gate owns consistency)
- docs/i18n/README.md + translation-rules.md reframed bidirectionally
(terminology table binds both directions; typography section governs
the Chinese side); zh counterparts updated; skill workflow updated
- RFC amended to the shipped design, records the English-canonical
in-file-fingerprint model as considered-and-revised; RFC translated
(docs/rfc/.../2026-07-02-bilingual-docs-and-pairing-gate.zh.md) and
added to the required frontier
- generated docs stay excluded with the follow-up recorded: teach the
generators to emit Chinese, then de-list
Tianyi Cui
NI0317
imccyu
Ziya
Turtle
Yichen Jiang