Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
6b7cd13
docs(topics): add context-engineering-integration decision contract (…
claude Sep 1, 2026
48d851e
docs(topics): absorb validator findings into the integration contract
claude Sep 1, 2026
0c8bc33
docs(topics): execute the signed-off corpus-integration batch (C2, C3…
claude Sep 1, 2026
f635f7f
docs(topics): record sign-off resolutions and execution receipts in t…
claude Sep 1, 2026
1729541
feat(conventions): add the instruction exception register and wire th…
claude Sep 1, 2026
5c19ae1
docs(topics): graduate the context-engineering corpus out of the memo…
claude Sep 1, 2026
a3ad449
docs(topics): resolve the context-management figure contradiction fro…
claude Sep 1, 2026
575f145
Merge origin/main into the context-engineering integration branch
claude Sep 1, 2026
1f7a11a
docs(specs): graduate the context-engineering corpus through the know…
claude Sep 1, 2026
835e037
docs(topics): prune the context-engineering integration contract slice
claude Sep 1, 2026
b85fb12
docs(specs): repair the relative links the graduation left one direct…
claude Sep 1, 2026
1d25ba1
chore(plugins): bump claude-config, instruction-placement and session…
claude Sep 1, 2026
9970e0c
docs(specs): record the model-upgrade re-test decision the pruned con…
claude Sep 1, 2026
1d27afd
fix(claude-config): wire the two register consumers the convention ta…
claude Sep 1, 2026
1e2a073
fix(ci): accept the CLAUDE_SHIM gitleaks false positive by fingerprint
claude Sep 2, 2026
db8573a
Merge origin/main into the context-engineering integration branch
claude Sep 2, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 17 additions & 6 deletions .gitleaksignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,22 @@
# policy names for intentional findings). One fingerprint per line:
# commit:file:rule:startline
#
# False positive: generic-api-key matching the shell variable inits
# `CLAUDE_TOKEN=""` / `CLAUDE_SHIM=0` in the AGENTS.md pointer-line resolver on
# the retired-conventions feature branches ("token" is a parsing token, not a
# credential; the flagged value is an empty string). The hygiene lane fetches
# every branch and scans --all, so this finding turns every PR red until the
# branch merges or rewrites; remove this line when that lands differently.
# False positive: generic-api-key firing on the AGENTS.md pointer-line resolver
# on the retired-conventions feature branches. TOKEN there is the parsing sense,
# never a credential: the `AGENTS_TOKEN=""` / `CLAUDE_TOKEN=""` inits supply the
# rule's keyword context, and the reported secret is the following line,
# `CLAUDE_SHIM=0`, a flag set to zero.
#
# The hygiene lane fetches every branch and scans --all, so this finding turns
# every PR red until the branch merges or rewrites. Verified against CI's pinned
# gitleaks 8.30.1, so the next reader need not retry them: renaming the flag
# still fires, and so does separating it from the TOKEN lines by a blank line.
# An inline `gitleaks:allow` marker does clear the working file, and the
# branches carry one, but it cannot clear a finding already recorded against an
# earlier commit, because the scan walks history and that blob is immutable.
# Hence fingerprints.
#
# Remove each line when the commit it names is no longer reachable (its branch
# squash-merged or deleted); the entry is dead config from that point on.
f7aec1549dec60407a24a7d8ea720696b7b099af:plugins/claude-config/lib/resolve-convention-home.sh:generic-api-key:248
708739fb2ba1b0196e93f9c07d3293bddfeed2f0:plugins/plugin-quality/lib/resolve-convention-home.sh:generic-api-key:249
79 changes: 79 additions & 0 deletions docs/conventions/instruction-exception-register/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Instruction exception register — what a trimming pass may not delete

Owner doc for the classes of standing instruction that survive an instruction-audit trim on
consequence grounds, whatever a length, redundancy, or model-era check says about them.

The register exists because subtraction guidance has no natural floor. The current generation of
prompting guidance is explicitly subtractive: strip prescriptive scaffolding, let the model use
judgment, delete rules written for older models. That guidance is sound and this repo follows it,
but it is stated for behavioral rules and carries a carve-out its own wording leaves undefined,
"avoid making them overconstrained, **except in highly important areas**". Without a written
answer to which areas those are, a trimming pass has no principled stopping point.

## The classes are Gate 0's, adopted by reference

The consequence classes this register protects are exactly the six hard-deny classes in
[`plugins/instruction-placement/context/routing-rubric.md`](../../../plugins/instruction-placement/context/routing-rubric.md),
Gate 0: `irreversible-action`, `secret-handling`, `data-integrity`, `external-publication`,
`legal-compliance`, `agent-authority`.

**This document does not restate that table, and no other surface may fork it.** One concern keeps
one adjudication chain: the class list has a single owner, and a second enumeration under a second
name is the drift this repo has already paid for elsewhere.

What this register adds is the **operation**. Gate 0 governs *relocation*: whether a rule may be
demoted out of an always-loaded surface into a path-scoped or skill destination. Deletion is a
different operation with a strictly worse failure mode, because a demoted rule that fails to fire is
recoverable by re-promoting it while a deleted rule leaves nothing to re-promote. So:

> A candidate matching any Gate 0 class is **not deletable** by an instruction-audit trim. It may be
> compressed in place, given a rationale, or converted to a deterministic mechanism such as a hook.
> It is never removed on redundancy, brevity, or "the model already does this" grounds.

## Non-exhaustive, and tighten-only

Two properties are load-bearing and neither is decoration:

- **Non-exhaustive.** The classes are the recognized floor, never the complete set of things worth
keeping. **Omission from this register is not licence to delete.** A rule outside every class is
judged on its own merits by the auditing skill's normal criteria, exactly as it was before this
document existed; it does not inherit a deletion warrant from its absence here.
- **Tighten-only.** A consuming repo or a downstream skill may add protected classes. Nothing that
reads this register may use it to *weaken* a protection, and no argument, including an operator
asking in the moment, removes a Gate 0 class from the protected set. That is Gate 0's own rule and
it travels with the classes.

**Recognition is by consequence, not by phrasing**, also inherited from Gate 0. Ask what breaks when
the instruction is absent at the moment it was needed, not how the sentence is worded. A one-line
"never force-push a shared branch" is a protected rail; a paragraph preferring one git subcommand
over another is style.

## Who consumes this

| Consumer | How it uses the register |
|---|---|
| `claude-config:audit-instructions` | Deletion-class criteria (I1, I4, I5) hold back a candidate matching a protected class and report the hold rather than proposing the cut |
Comment thread
kyle-sexton marked this conversation as resolved.
| `claude-config:unhobble` | The bare-baseline experiment may strip a protected rule during the run, since the strip is reversible and branch-local, but Phase 4 restores it regardless of whether the ledger logged a stumble against it — a protected rule is never left deleted on the evidence of "no stumble was observed" |
| `instruction-placement:*` | Unchanged. It owns the classes and the relocation verdict; this register is the deletion counterpart and defers to it on class membership |

A consumer that reads this register names it in its own criteria text. A register nothing consumes
changes no behavior, which is the failure mode this table exists to prevent.

## What this is not

- Not a second opinion on relocation. Gate 0 decides that, and a candidate held here may still be
legitimately relocated.
- Not a suppression record. A finding an operator has judged and accepted is the
[finding-suppression](../finding-suppression/README.md) convention's axis.
- Not a licence to keep everything. The subtractive posture stands for every candidate outside the
protected classes, and compression in place remains the right answer for a protected rule that has
genuinely grown bloated.

## Provenance

Adopted 2026-09-01 from the context-engineering corpus integration, decision Q2. That decision
contract is contract tier and was pruned before merge; it survives as the `<details>` paste in its
pull request, and the evidence behind it is in
[`docs/specs/context-engineering-corpus-knowledge.md`](../../specs/context-engineering-corpus-knowledge.md). The carve-out this register answers is quoted from a vendor-voice source and carries
that source's status: the wording is first-party, the definition of "highly important areas" is
this repo's own and is not claimed to be upstream doctrine.
21 changes: 21 additions & 0 deletions docs/conventions/upstream-drift/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,27 @@ Notable changes to the upstream-drift contract (SemVer). Changing a required par
name, or an enforceability verdict is a major bump; additive guidance is a minor bump; docs-only
clarification is a patch.

## 1.6.3 — 2026-09-01

Recorded near-miss evidence ADJACENT to the content-hashing deferral; docs-only, the deferral's
verdict does not change and its trigger has NOT fired.

The context-engineering-integration corpus pass (signed off 2026-09-01; its decision contract is
contract tier and was pruned before merge, surviving as the `<details>` paste in its pull request,
with the durable evidence in
[`docs/specs/context-engineering-corpus-knowledge.md`](../../specs/context-engineering-corpus-knowledge.md))
found the live
anthropic.com/research/building-effective-agents page silently revised after publication: the
page still says "Published Dec 19, 2024" while its body now names models and products that
post-date that date, so any citation of "the December 2024 post" at that URL quotes post-hoc
edits. This is the failure class a stored content hash would flag — but the deferral's recheck
trigger ("a stale stamp causes a real defect a stored hash would have flagged, or a fleet audit
completes without re-fetching every stamped claim") has not fired: no committed stamp on that
page exists, so no stale stamp caused a defect in a tracked record. Recorded here as adjacent
evidence for the eventual designed issue the deferral itself prescribes ("a hash store becomes
its own designed issue, not an inline addition here"); that issue is filed as a tracker item by
the integration effort. The deferral stays as written.

## 1.6.2 — 2026-08-31

Recorded firing of the no-adoption-gate decision's recheck trigger; docs-only under this contract's
Expand Down
Loading
Loading