Claude Skill

freshness-contract

Categorical decision table for reusing cached evidence — when an artifact you already read, a banked test result, a primer, a worker report, or a probe verdict is still trustworthy, and when it must be spot-checked or re-verified. Inputs are observable (artifact class, age anchor

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download allemaar-open-skills-skills_freshness-contract-acf5f79.zip · 3 KB

Install

skills CLI npx skills add https://github.com/allemaar/open-skills/tree/main/skills/freshness-contract
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
Git git clone https://github.com/allemaar/open-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole allemaar/open-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

/freshness-contract

EXPERIMENTAL. A lookup, not a judgment ritual: it should cost LESS than the vibes it replaces. Fires only when prior evidence is about to be reused for a decision — never on every read, never as per-phase bookkeeping. It decides whether old proof still counts; what fresh proof must show belongs to your verification tools.

The design is deliberately isomorphic to HTTP caching (RFC 9111): explicit invalidation beats heuristics, conflicting signals resolve restrictively, and nothing is served stale silently. No TTL numbers ship in v1 — every "how old is too old" constant would be invented; the table routes by class and events, which are observable.

Step 1 — classify the artifact (volatility class)

Class Meaning Examples
stable exact version-pinned evidence, used for a question about that exact version — byte stability is not applicability: a superseded spec's old bytes still match while the governing version moved a released spec consulted AS that release, a frozen/hash-pinned artifact, an archived record. Supersession or a dependency-version change is a named invalidator whenever the decision asks what is CURRENT
write-coupled valid until someone writes to the source a file you read this session, an index entry, a config, a map/roster document
env-coupled valid until the environment shifts a passing test that touches network/services/installed tools, a capability probe, a build result
clock-coupled decays with time regardless of writes anything embedding "current" state: prices, live statuses, date-dependent results
report someone's account of state, not state itself worker/subagent reports, peer summaries, self-reports of any kind

Class is assigned per artifact kind at first encounter, not re-judged per use by whoever wants to skip a re-read.

Step 2 — check the observable signals

  • Intervening writes — has the source (or its declared dependencies) changed since as_of? (fingerprint, mtime, generation stamp, commit)
  • Named invalidators — did a declared invalidating event occur? (roster change, deploy, sync, schema bump, "re-prime after write")
  • Decision leverage — is the reuse load-bearing for a decision, release, or Handler-facing claim, or merely orientation? Leverage is non-downgradable when the result supports a release, an irreversible or external action, a formal gate, or a Handler-facing recommendation — those are high, not judgment calls.
  • Discriminator availability — does a cheap signal exist that is exclusive to the fresh state (a hash to recompute, a header to stat, a count to re-derive)?

Step 3 — the table (first match wins)

Situation Policy
Any named invalidator fired, or intervening write on a write-coupled source re-verify
Conflicting or ambiguous signals, whatever the class re-verify (restrictive conflict rule)
stable + fingerprint still matches reuse
write-coupled + no intervening write + low/medium leverage reuse
write-coupled + no intervening write + high leverage spot-check the discriminator
env-coupled or clock-coupled + low/medium leverage spot-check the discriminator
env-coupled or clock-coupled + high leverage re-verify
report, any age, load-bearing re-verify (a report is never promoted to state by aging)
report, orientation only reuse, labeled as report
unclassified artifact kind (DEFAULT ROW) spot-check; classify the kind before next reuse

accept-labeled-risk is agent-electable ONLY on the no-cheap-discriminator row — it is never a bypass for a re-verify result elsewhere in the table. On any other row, proceeding despite a re-verify verdict requires explicit Handler authority (that is a Handler override, not a table output). Where it applies, it is never silent: the staleness risk is named next to the conclusion it feeds.

After the first matching policy is selected, handle discriminator availability for every spot-check result, including the default row: if no cheap exclusive discriminator exists, re-verify or explicitly accept labeled risk only where already permitted. Mandatory re-verification for invalidators, conflicts, high-leverage volatile evidence and load-bearing reports remains mandatory; this fallback never loosens those rows.

Output record (one line to a few lines, inline where the evidence is used)

freshness = { artifact, class, as_of, signals: {writes|invalidators|leverage},
              decision: reuse|spot-check|re-verify|accept-labeled-risk,
              discriminator_used?: <what was checked> }

No dedicated log stream, no cards, no sink — the record rides inside whatever report or decision consumed the evidence.

Safety boundary

  • Signals are observable properties of sources and events — never the agent's feeling of confidence about its memory.
  • The table may be narrowed by a Handler's local policy (stricter rows); agents never loosen a row.
  • TTLs, if ever added, must come from logged staleness observations, not authorship-day guesses; until then age alone never justifies reuse or refusal.
  • Foreign freshness metadata (another party's "this is current" claim) is a report, not a signal — classify accordingly.

Self-improvement. On completion, run the Self-Improvement Protocol (self-improve/SKILL.md): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.

Files (open-skills)
  • SKILL.md 6.9 KB
    ---
    name: freshness-contract
    description: Categorical decision table for reusing cached evidence — when an artifact you already read, a banked test result, a primer, a worker report, or a probe verdict is still trustworthy, and when it must be spot-checked or re-verified. Inputs are observable (artifact class, age anchors, intervening writes, named invalidators); output is reuse / spot-check / re-verify / accept-labeled-risk. Conservative by construction — unclassified artifacts and conflicting signals always take the more restrictive path; no invented TTLs. Trigger when the user runs /freshness-contract, asks "is this still current", "can I trust what I read earlier", "do I need to re-check this", or before reusing prior evidence for a decision after time, writes, or environment changes. Not /double-check (re-verifies one claim's content) or /verify (formal phase gate) — freshness-contract decides whether OLD evidence still counts before those tools decide what NEW evidence shows.
    visibility: public
    self-improvable: true
    triggers:
      - "/freshness-contract"
      - "is this still current"
      - "can I trust what I read earlier"
      - "do I need to re-check this"
      - "is this stale"
    next-skills:
      - skill: double-check
        phrase: "/double-check"
        why: "When the table says re-verify, double-check is the targeted re-read that satisfies it"
    ---
    
    # /freshness-contract
    
    > **EXPERIMENTAL.** A lookup, not a judgment ritual: it should cost LESS than the vibes it replaces. Fires only when prior evidence is about to be **reused for a decision** — never on every read, never as per-phase bookkeeping. It decides whether old proof still counts; what fresh proof must show belongs to your verification tools.
    
    The design is deliberately isomorphic to HTTP caching (RFC 9111): explicit invalidation beats heuristics, conflicting signals resolve restrictively, and nothing is served stale silently. No TTL numbers ship in v1 — every "how old is too old" constant would be invented; the table routes by *class and events*, which are observable.
    
    ## Step 1 — classify the artifact (volatility class)
    
    | Class | Meaning | Examples |
    |---|---|---|
    | **stable** | **exact version-pinned evidence, used for a question about that exact version** — byte stability is not applicability: a superseded spec's old bytes still match while the governing version moved | a released spec consulted AS that release, a frozen/hash-pinned artifact, an archived record. **Supersession or a dependency-version change is a named invalidator whenever the decision asks what is CURRENT** |
    | **write-coupled** | valid until someone writes to the source | a file you read this session, an index entry, a config, a map/roster document |
    | **env-coupled** | valid until the environment shifts | a passing test that touches network/services/installed tools, a capability probe, a build result |
    | **clock-coupled** | decays with time regardless of writes | anything embedding "current" state: prices, live statuses, date-dependent results |
    | **report** | someone's account of state, not state itself | worker/subagent reports, peer summaries, self-reports of any kind |
    
    Class is assigned per artifact **kind** at first encounter, not re-judged per use by whoever wants to skip a re-read.
    
    ## Step 2 — check the observable signals
    
    - **Intervening writes** — has the source (or its declared dependencies) changed since `as_of`? (fingerprint, mtime, generation stamp, commit)
    - **Named invalidators** — did a declared invalidating event occur? (roster change, deploy, sync, schema bump, "re-prime after write")
    - **Decision leverage** — is the reuse load-bearing for a decision, release, or Handler-facing claim, or merely orientation? **Leverage is non-downgradable when the result supports a release, an irreversible or external action, a formal gate, or a Handler-facing recommendation — those are high, not judgment calls.**
    - **Discriminator availability** — does a cheap signal exist that is exclusive to the fresh state (a hash to recompute, a header to stat, a count to re-derive)?
    
    ## Step 3 — the table (first match wins)
    
    | Situation | Policy |
    |---|---|
    | Any named invalidator fired, or intervening write on a write-coupled source | **re-verify** |
    | Conflicting or ambiguous signals, whatever the class | **re-verify** (restrictive conflict rule) |
    | stable + fingerprint still matches | **reuse** |
    | write-coupled + no intervening write + low/medium leverage | **reuse** |
    | write-coupled + no intervening write + high leverage | **spot-check** the discriminator |
    | env-coupled or clock-coupled + low/medium leverage | **spot-check** the discriminator |
    | env-coupled or clock-coupled + high leverage | **re-verify** |
    | report, any age, load-bearing | **re-verify** (a report is never promoted to state by aging) |
    | report, orientation only | **reuse, labeled as report** |
    | **unclassified artifact kind (DEFAULT ROW)** | **spot-check**; classify the kind before next reuse |
    
    `accept-labeled-risk` is **agent-electable ONLY on the no-cheap-discriminator row** — it is never a bypass for a `re-verify` result elsewhere in the table. On any other row, proceeding despite a `re-verify` verdict requires explicit Handler authority (that is a Handler override, not a table output). Where it applies, it is never silent: the staleness risk is named next to the conclusion it feeds.
    
    After the first matching policy is selected, handle discriminator availability for every spot-check result, including the default row: if no cheap exclusive discriminator exists, re-verify or explicitly accept labeled risk only where already permitted. Mandatory re-verification for invalidators, conflicts, high-leverage volatile evidence and load-bearing reports remains mandatory; this fallback never loosens those rows.
    
    ## Output record (one line to a few lines, inline where the evidence is used)
    
    ```text
    freshness = { artifact, class, as_of, signals: {writes|invalidators|leverage},
                  decision: reuse|spot-check|re-verify|accept-labeled-risk,
                  discriminator_used?: <what was checked> }
    ```
    
    No dedicated log stream, no cards, no sink — the record rides inside whatever report or decision consumed the evidence.
    
    ## Safety boundary
    
    - Signals are observable properties of sources and events — never the agent's feeling of confidence about its memory.
    - The table may be narrowed by a Handler's local policy (stricter rows); agents never loosen a row.
    - TTLs, if ever added, must come from logged staleness observations, not authorship-day guesses; until then age alone never justifies reuse or refusal.
    - Foreign freshness metadata (another party's "this is current" claim) is a report, not a signal — classify accordingly.
    
    > **Self-improvement.** On completion, run the Self-Improvement Protocol (`self-improve/SKILL.md`): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.