Repository navigation
docs: rename 11 dead identifiers in specs to the live names - #38338
Conversation
docs_lint reported names that no code tree carries. Each one was traced to the code: renamed ones now use the real name, removed ones (the optimizer's draft-URL rule, a deleted test, a gone helper) are dropped. Report-only count on main goes from 604 to 593.
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. The PR only changes markdown specs, so it adds no user-visible control and needs no screenshot. [UX-REVIEWED] fed1f2b Description read[DESCRIPTION-READ] f40eaf5bf260658a68ec009475d40dc4c41670990894e570274c28d609b36db3 That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: this PR only changes spec prose, so no reader breaks and it renders nothing new. [DESIGN-REVIEWED] fed1f2b Description read[DESCRIPTION-READ] 9ac9d69382411adb984297fea9ca4dc23117e43858980d25b8846c116c53ed0d That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
This review checked all 11 renames at head fed1f2b against the code. Examples: process_can_read_under_sandbox(pid, path), _custom_model_id(path, configured, ...), credential_records(..., reveal_pending=...) with _commit_reveals, GuideMateNote, and pages.schedulePage.type_token_to_confirm. It also checked that the 7 removed names appear nowhere in src, test, website or scripts. The diff is 8 markdown files with no code change, and no other open PR touches these lines.
Done well: the subagent.md fix corrects a false claim as well as a name. Retry and delete are REST handlers in the _spawn_scope_refusal map, not MCP tools.
The design is signed off under the standing maintainer sign-off for changes by team members.
Optional:
- docs/system-specs/modules/security.md:2510 still names
_scan_span_urlsand the retired optimizer draft-URL walk. That is the same dead rule this PR removes from prompt-optimizer.md. - docs/system-specs/modules/learn-cron-dashboard.md:4392 still says the exfil-first order matters because the URL rewriter "removes the whole URL". The one test it still cites asserts that the link is kept and only the credential value is masked.
- website/docs/testing.md:606 cites ChatPage.dirStaging.test.tsx, which no longer has the
aria-busywait. FilePickerMenu.projectPlaceholder.test.tsx may be the better example.
Problem / Motivation
Goal: Specs name the code's real identifiers, so
docs_lint's dead-identifier report on main shrinks by every name that is plain doc rot.python3 scripts/docs_lint.pyon main (d36674eb46) reports 604 backticked names that no code tree carries. Some are rot: a renamed function, a removed test, a feature that shipped and was taken out again while its spec bullet stayed.Why it matters
A reader who greps for a name the spec gives finds nothing, or trusts a rule the code no longer runs (the prompt optimizer's draft-URL rule is the clearest case).
Not a goal
scripts/docs_lint.pyor.github/docs-lint-baseline.txt.docs/decisions/(byte-immutable) or to RFC proposal text.What changed (motivation → approach → change)
Each dead name was traced to the code. A renamed one now uses the real name. A removed one is dropped.
prompt-optimizer.mddraft_url_redacted,TestOptimizerDraftUrls,redact_exfiltration_urlsredact_credentialsonlysecurity.mdcredential_records(..., reveal_scope=slot.key)reveal_pending=plus_commit_revealssubagent.mdspawn_retry,spawn_deletetoolsapi_spawn_retry,api_spawn_deleterouteslearn-cron-dashboard.mdGuideAgentNote;::test_redaction_runs_exfil_before_credentialsGuideMateNote; deleted test droppedmemory-skills-hooks.md_custom_model_id(path, configured_label)configuredplatform-compat.mdtrusted_absolute_pathparameterpathwebsite/docs/i18n-catalog.mdtype_verb_to_confirmtype_token_to_confirmwebsite/docs/testing.mdpickerSettledForhelperCount: 604 → 593.
The floor is far above 500 without rewriting docs that are right as written:
connector-capability-manifest.mdkas-nondestructive-session-teardown.mdharness-plugin-mapping.mdtesting-conventions.mddocs/decisions/,CHANGELOG.mdf"instances_{op}"), intest/orwebsite/public/(not indexed), or a true "there is no X" noteBackwards compatibility
Compatible: docs only.
Removes nothing: only prose in specs changes; no code, key or path.
Tests
Proof: not provable -- docs or config only
python3 scripts/docs_lint.py: exit 0, "All documentation checks passed", 593 dead identifiers.bash scripts/docs-lint.sh: exit 0.pytest test/test_docs_lint_fact_checks.py test/test_docs_lint_owners.py test/test_docs_gate_table_matches_fast_gate.py test/test_docs_mock_pid_convention.py: 150 passed.Manual verification
Each new name was grepped in
src/,website/src/ortest/ond36674eb46.Related Issues
N/A — DocKeeper doc-drift pass.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement