Skip to content

Cut the model-read ecosystem specifics from docs-hygiene: compress and rename-references #17773

Open

Description

@kyle-sexton

Part 1 of 3 of #16760. Refs #15703. Blocks #15732 through #16760.

Problem

docs-hygiene:compress requires markdownlint-cli2 as its lint step (R4) and names code-file extensions and one vendor's plugin as examples. rename-references reads a manifest detection list and Python/Rust/C#/JS examples.

Rows (6: R11 5, R4 1)

Row Rule Kind Cited at (as of 5b66a7f) Fact
F0166 R4 K3 plugins/docs-hygiene/skills/compress/SKILL.md:153-154 (also :33, :95, :101, :146, :160, :165, :193; compress/context/integration.md:9,38,45; compress/context/fan-out-orchestration.md:64) compress requires markdownlint-cli2 as the lint step
F0176 R11 K7 .../compress/SKILL.md:184 (also compress/context/integration.md:37) .cs, .py, .ts, .sh as out-of-scope examples
F0182 R11 K5 .../compress/SKILL.md:174 (also plugins/docs-hygiene/skills/audit-derivability/SKILL.md:74) the OpenAI Codex plugin as an example cross-vendor advisor
F0173 R11 K2 plugins/docs-hygiene/skills/rename-references/context/patterns.md:552-570 mode ladder maps plugin.json, package.json, pyproject.toml to container mode
F0174 R11 K7 .../rename-references/context/patterns.md:357-375 TOML-declaration alternative for pyproject.toml, Cargo.toml
F0175 R11 K7 .../rename-references/SKILL.md:176,191 Python class, C# type, JS function renames as examples

The compress rows stay together (F0166 with F0176 and F0182). compress ships scripts/audit-scan.sh, which hits markdownlint-cli2 at d46efa9: the script-reader search decides whether F0166's call sites are model-read or script-run.

Files

  • Cut: plugins/docs-hygiene/skills/compress/SKILL.md, .../compress/context/integration.md, .../compress/context/fan-out-orchestration.md, plugins/docs-hygiene/skills/audit-derivability/SKILL.md (F0182's second site), plugins/docs-hygiene/skills/rename-references/context/patterns.md, .../rename-references/SKILL.md.
  • Outside references at d46efa9: scripts/shell-portability-skill-md-baseline.txt:27 (patterns.md), :29 (rename-references SKILL.md). Update an entry if the cut removes the portability finding it records.

Rules this part follows (from #16760, rules revision 5)

  • R11 (shipped knowledge): model-read K2, K3, K4, K5 or K7 text. Generic text replaces it only at a routing site where the skill still takes a language-specific step; anywhere else it is deleted with no replacement. An item kept only because a removed item consumes it goes in the same pull request.
  • R4 (consumer default): the value picks a tool or library for the consumer. It goes: no bundled default survives (ADR 0101 decision 2, "Ship no bundled default"); the choice is resolved from the consumer through docs/contracts/ecosystem-resolution/.
  • R8 (measured fact): cut it like the other rows and mark it in the pull request body as pending its targeted case; the host session's eval (below) decides whether it comes back, annotated portability-ok: measured <case-id>.
  • AC1's named exceptions are the kept classes of ADR 0101 (docs/adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md, Decision and the 2026-11-17 amendment). Bundled defaults that pick a tool, command or library are retired wherever they appear (Interview Q32, D4 of the Brief).
  • Line numbers below were read at 5b66a7fa and may have moved; find each row by its cited text.

After the pull request opens (host session, not the lane)

The lane opens the pull request with Closes this issue and stops; it adds no label. The pull request stays held for the eval:

  • Hold line: a sweep or host session adds do-not-merge and posts, from a listed human's account, a comment with <!-- pr-hold reason=eval --> on a line of its own.
  • Targeted case per changed skill: one before-and-after case on sonnet at 3 runs a side, --case, --runs 3, a --max-cost-usd ceiling; opus only to confirm a sonnet loss; a new case gets a 1 to 3 run smoke first; start no batch after a usage-limit error (owner decision of 2026-11-16).
  • Controls: the owner's Q53 decision of 2026-11-17 (owner-decisions.md L202) reads: "each cut pull request is gated on a no-loss compare alone, with no wrong-text side". It supersedes Cut the model-read ecosystem specifics from docs-hygiene #16760's Controls line and its AC7 sentence ("each partial cut carries a detection-control result"). A whole-page deletion still states its predicted outcome in the pull request body before the first batch, and the record says the case cannot detect wrong text.
  • On a LOSS reading: a trace read of each dropped case and an opus confirm; only a loss traced to the changed text counts.
  • R8 rows: the row's targeted case with and without it; on a case drop or a mean fall of 0.15 or more without it, restore the row annotated portability-ok: measured <case-id>; a deterministic grader states before the run in how many of n runs it must fail.
  • Record: on a VALID no-loss run, post from a listed human's account <!-- eval-pair verdict=no-loss validity=VALID head=<40-hex head SHA> --> naming the current head, with no "do not merge" text (docs/contracts/loop-lane/README.md, "Cross-lane PR hold"). pr-merge's "Release eval holds whose record matches the head" step (.github/scripts/pr-merge/release-eval-hold.mjs) then removes do-not-merge; a later push needs a new record.

Out of scope

Rows outside this part's table, the parent's kept rows, every other plugin, toolchain's bundled defaults (#15733), and widening the portability gate (#15732).

Done when

  • Every row in this part's table is cut or replaced at a routing site, and compress no longer requires a named linter; a row whose cited text is already gone on main is listed as GONE.
  • The pull request body states this part's row count (6) and lists every row id with its rule and outcome.
  • Each R11 row's script-reader search is quoted in the pull request body; a row whose file a script reads (for example compress/scripts/audit-scan.sh) is not cut, and is listed in the pull request body under a Script readers heading.
  • The pull request body names, for each changed skill (compress, audit-derivability, rename-references), the existing eval case that reads the cut text, or says none does.
  • The pull request body says, for each changed file, whether the cut deletes the whole page or part of it.
  • scripts/shell-portability-skill-md-baseline.txt:27,29 still match the files after the cut.
  • AC10: no new enforcement-placing skill is added.

Activity

  1. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 21, 2026
  2. github-actions commented on Nov 21, 2026

    @github-actions
    Contributor

    Size: Medium
    Complexity: Medium
    Uncertainty: Known
    Flags: none
    Blocked by: none
    Blast radius: six docs-hygiene skill and context files (compress, audit-derivability, rename-references) plus possibly two entries in the shell-portability baseline; read by the model when those skills run.
    Reversible: yes; revert the pull request, or restore a row with a portability-ok: measured <case-id> annotation.
    Open questions: none
    I understood this as part 1 of 3 of #16760: cut or replace the six listed rows (F0166, F0173-F0176, F0182) per rules R11 and R4. Compress must no longer require a named linter. Rows read by scripts are listed rather than cut. The pull request body must carry the row count, the script-reader search, the eval-case mapping and the whole-page or partial-cut statement. The done-when is exact and the design is chosen in the issue. The eval and hold steps run in a host session after the pull request opens. I found no duplicate among the open issues and no merged pull request that already does this.

    Automated triage. A maintainer reviews it.

  3. removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 21, 2026
  4. melodic-automation-lanes commented on Nov 21, 2026

    @melodic-automation-lanes
    Contributor

    {"v":1,"actor_id":337595936,"title_sha256":"5911cd6250e4dc85ef1d59521021a71a280188ee8a2cfca69c6ef4ec49c37090","body_sha256":"e1e98a54bd9a3ab312e2443f5fce940ead0ac979a02767d87177d640963a72af"}

  5. melodic-automation-lanes commented on Nov 21, 2026

    @melodic-automation-lanes
    Contributor

    {"v":1,"actor_id":337595936,"title_sha256":"5911cd6250e4dc85ef1d59521021a71a280188ee8a2cfca69c6ef4ec49c37090","body_sha256":"e1e98a54bd9a3ab312e2443f5fce940ead0ac979a02767d87177d640963a72af"}

  6. github-actions commented on Nov 21, 2026

    @github-actions
    Contributor
    No description provided.
  7. github-actions commented on Nov 21, 2026

    @github-actions
    Contributor
    No description provided.
  8. added
    host-runNeeds an unattended run on a host; the host runner takes it, not a person or the issue lane.
    on Nov 21, 2026
  9. melodic-automation-lanes commented on Nov 21, 2026

    @melodic-automation-lanes
    Contributor

    The work-resolve-issue lane stopped on this issue (patch-protected-path): the change needs a path the issue lane may not push, which a maintainer session builds by hand.
    It added host-run and set Work status to confirmed: an agent run on a host builds it, and it waits on no decision from a person.

    In the run's words:

    The run stopped early (patch-protected-path): its change needs a path the issue lane may not push, which a person changes instead. In the run's words: patch-protected-path: .claude/skills/control-claude-code-plugins/features/docs-hygiene/README.md. Cutting compress's markdownlint-cli2 requirement (row F0166) means /docs-hygiene:setup's markdownlint-cli2 check goes in the same pull request: that check exists only because compress consumes it (R11's consumed-item rule; setup/SKILL.md says 'No other skill in this plugin needs the binary'). Setup's description then changes, and line 14 of that protected feature index copies the old description ('Verify that markdownlint-cli2, the lint gate /docs-hygiene:compress requires, resolves and runs'). This lane cannot write under .claude/, and leaving the line stale would be a workaround.

    What the run says it did not do:

    • All six rows (F0166, F0176, F0182, F0173, F0174, F0175) are left uncut. The run stopped before any edit because the consumed setup check can't be removed without also updating the protected .claude/skills/control-claude-code-plugins/features/docs-hygiene/README.md.
    • Tidy, review, verify and checks pipeline steps were not run because there is no diff.

    Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/44867882300

    To hand it back to the lane, remove host-run and set Work status to agent-ready again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    host-runNeeds an unattended run on a host; the host runner takes it, not a person or the issue lane.

    Type

    Fields

    Work status

    confirmed

    Priority

    medium

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions