Skip to content

docs: rename 11 dead identifiers in specs to the live names - #38338

Merged
iamwhatever merged 1 commit into
mainfrom
docs/dockeeper-dead-ids-2026-11-17
Nov 17, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
docs/dockeeper-dead-ids-2026-11-17

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

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.py on 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

  • No change to scripts/docs_lint.py or .github/docs-lint-baseline.txt.
  • No edit to docs/decisions/ (byte-immutable) or to RFC proposal text.
  • No rewrite of design specs whose names are planned, not built (see the floor table below).

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.

File Was Now
prompt-optimizer.md draft-URL rule, draft_url_redacted, TestOptimizerDraftUrls, redact_exfiltration_urls rule removed in #37408; bullet says redact_credentials only
security.md credential_records(..., reveal_scope=slot.key) reveal_pending= plus _commit_reveals
subagent.md spawn_retry, spawn_delete tools api_spawn_retry, api_spawn_delete routes
learn-cron-dashboard.md GuideAgentNote; ::test_redaction_runs_exfil_before_credentials GuideMateNote; deleted test dropped
memory-skills-hooks.md _custom_model_id(path, configured_label) configured
platform-compat.md trusted_absolute_path parameter path
website/docs/i18n-catalog.md type_verb_to_confirm type_token_to_confirm
website/docs/testing.md pickerSettledFor helper helper gone; test file kept

Count: 604 → 593.

The floor is far above 500 without rewriting docs that are right as written:

Source Count Why left
connector-capability-manifest.md 214 schema for a validator not built yet; the spec says so
kas-nondestructive-session-teardown.md 60 KAS engine code, not in this repo
OAuth guides, vendor scopes, Codex, Claude, llama.cpp, AWS, goose ~120 external names
harness-plugin-mapping.md 41 other harnesses' plugin APIs
testing-conventions.md 47 probe class names and history
docs/decisions/, CHANGELOG.md 12 immutable
rest ~100 built at runtime (f"instances_{op}"), in test/ or website/public/ (not indexed), or a true "there is no X" note

Backwards 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/ or test/ on d36674eb46.

Related Issues

N/A — DocKeeper doc-drift pass.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

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.
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 17, 2026 08:50
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 17, 2026
@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision fed1f2ba15b1630b1178dcdde87e43475ef9ee72 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of fed1f2ba15b1630b1178dcdde87e43475ef9ee72 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of fed1f2ba15b1630b1178dcdde87e43475ef9ee72 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of fed1f2ba15b1630b1178dcdde87e43475ef9ee72 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] fed1f2b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt fed1f2ba15b1630b1178dcdde87e43475ef9ee72 false-positive: <reason, 20 to 500 characters>

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed fed1f2ba15b1630b1178dcdde87e43475ef9ee72 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] fed1f2b

Verdict parsed from the review's SHA-scoped output markers for commit fed1f2ba15b1630b1178dcdde87e43475ef9ee72.

False positive or not applicable? A repository writer can comment:
/ai-review override fable fed1f2ba15b1630b1178dcdde87e43475ef9ee72 false-positive: <reason, 20 to 500 characters>

@iamwhatever
iamwhatever enabled auto-merge (squash) November 17, 2026 09:06
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 17, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_urls and 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-busy wait. FilePickerMenu.projectPlaceholder.test.tsx may be the better example.

@iamwhatever
iamwhatever merged commit 3b4f976 into main Nov 17, 2026
101 of 102 checks passed
@iamwhatever
iamwhatever deleted the docs/dockeeper-dead-ids-2026-11-17 branch November 17, 2026 11:14
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants