AGENT SKILL

lehre-pin

Use once a unit or phase is validated, to make its rules survive without the plugin: emit a CI check that runs the doctrine with no agent in the loop, and write behaviour tests around the code that was changed to conform. Covers CI pinning of the ruleset, durable enforcement once the plugin is uninstalled, and regression tests for conformance edits. Two phases — the durable rule check, then the regression net.

License 许可
MIT
所属仓库
Anselmoo/werkstoff
最近更新
2026-11-02
Stars
★ 1
Forks
0

01 前言 Front Matter

name
lehre-pin
description
Use once a unit or phase is validated, to make its rules survive without the plugin: emit a CI check that runs the doctrine with no agent in the loop, and write behaviour tests around the code that was changed to conform. Covers CI pinning of the ruleset, durable enforcement once the plugin is uninstalled, and regression tests for conformance edits. Two phases — the durable rule check, then the regression net.

03 SKILL.md 正文

Make the doctrine outlive the session. Every enforcement layer above this one depends on an agent being in the loop; this one does not.

Two phases, both run:

Phase 1 — pin the rules

  1. Run the gate before pinning anything. Name the unit(s) being pinned; if the user named none, gate on every declared unit:

    python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/lehre_cli.py" status --require-validated --unit <unit-id>
    

    (repeat --unit per unit; omit it to require them all). Act on the exit code, not on how the printed rows read — plain status exits 0 whatever the states are, so only this flag can stop you:

    • 0 — every required unit holds its done-marker; continue.
    • 1 — stop. Nothing is pinned. Report the units it names and send the user to lehre-validate. Emit the BLOCKED block below, not a CI check.
    • 2 — stop. The ruleset is unusable or the unit does not exist; fix that first. It does not mean the unit is validated.

    In a brownfield ruleset there are no units, so the gate says it has no done-marker to check and exits 0. That 0 is not a validation: confirm lehre-validate passed from its own report before continuing, and say that the confirmation is yours, not the gate's.

  2. Emit a CI invocation of the real gauge, not a reimplementation:

    python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/lehre_cli.py" gauge --severity blocking
    

    Exit 1 fails the job. A hand-written CI script that re-encodes the rules is a second implementation that will drift from the ruleset — the exact defect the shared evaluator exists to prevent.

  3. Prefer the project's own linter where the rule is expressible there. A rule already covered by ruff/eslint/clippy belongs in that tool's config, where it runs on every developer's machine with no Python path and no plugin installed. Convert it and change the ruleset rule to linter kind pointing at the same tool. Reach for the gauge only for what a linter cannot say — layering, forbidden paths, unit ordering.

  4. Cover the write-time gap explicitly. The PreToolUse hook does not see files written through Bash, and linter-kind rules are never write-time denials at all. CI is what closes both. Say so in the emitted config's comment, so the next reader knows why the job exists when a hook already does "the same thing".

Phase 2 — pin the behaviour

  1. Write tests around what conformance changed, not around the rule. The rule is already pinned by phase 1. What is unpinned is whether the conformance edit preserved behaviour — a layering fix that moved a database call behind a service is exactly the kind of change that compiles, passes every rule, and silently changes semantics.

  2. Target the seams the decomposition declared, as read from .lehre/ruleset.json (the same source lehre-validate names). A test at a seam catches a later unit violating the contract long before a rule could; a test buried inside one unit's internals catches only that unit's refactors.

  3. Prove the test can fail. State, per test, the mutation it would catch. A test written after the fact that passes against both the old and the new behaviour pins nothing, and this repo's zeugnis-assertion-audit exists because that failure is common enough to need its own auditor.

Output format

phase 1 — rules pinned

  .github/workflows/lehre.yml     runs lehre_cli.py gauge --severity blocking
                                  covers: Bash-written files, linter-tier rules,
                                  and any session with the plugin uninstalled
  pyproject.toml [tool.ruff]      + "TRY", "BLE"  <- absorbs no-bare-except and
                                  prefer-logging; ruleset rules converted to
                                  linter kind so there is one implementation, not two

  still gauge-only (no linter can express these)
    no-api-to-db             layering across packages
    tests-live-in-tests      file location
    unit build order         .lehre/units/*.done

phase 2 — behaviour pinned

  tests/adapters/test_vendor_a.py::test_code_map_passed_in_not_looked_up
      seam: contracts -> adapters
      would catch: reverting the fix, i.e. re-importing src.db.session to look
                   up the vendor code. Fails on the pre-conformance code.
  tests/contracts/test_schema_stability.py::test_row_schema_field_order
      seam: contracts -> everything
      would catch: a field reordered or renamed in RowSchema, which every
                   adapter and the writer silently depend on.

verified: both tests fail against the pre-conformance revision.

When the gate halts, this is the whole output — no phase 1, no phase 2:

BLOCKED — nothing pinned

  gate: FAILED -- not validated: domain, cli. Run lehre-validate first; do not pin.

  Pinning now would make CI defend behaviour nobody has confirmed is right.
  next: lehre-validate domain, then lehre-validate cli, then re-run lehre-pin.

Rules

  • Never reimplement a rule in CI. Call the gauge. Two implementations of one rule is the drift the shared evaluator was built to eliminate.
  • Never claim a test pins behaviour without naming the mutation it catches. If no mutation can be named, the test asserts nothing and should not be written.
  • Never pin an unvalidated unit. Pinning cements the current behaviour; if lehre-validate has not passed, that behaviour is not known to be right. Step 0's gate is the check: write no CI config, linter change or test until it has exited 0, and never reason around an exit 1 because the unit "looks done".

04 同仓库更多 Skills