fresh-making

Files (1)

• SKILL.md

SKILL.md (first lines)

# fresh-making — restore derivation consistency

It does not own the source canon, the generator's domain semantics, or the executor. It owns the **freshness decision and restoration discipline** connecting them.

## Core contract

```text
fresh != recent
fresh == provably consistent with declared current inputs
```

A target is **fresh** only when all of the following are true:

1. every required input has an exact current identity;
2. the receipt records those same input identities;
3. the generator identity and generation contract match the current declaration;
4. every declared output exists and matches its recorded content digest;
5. the verifier passes against the current output;
6. no required relation is unresolved as `hmmm`.

A timestamp may aid operations and audit. It never proves freshness.

## Load this when

- A source commit, schema, package version, corpus digest, skill, generator, or configuration changes and derived outputs may need regeneration.
- A user asks whether an artifact is stale/current/fresh, or asks to make it fresh.
- Computing which MSDMD collections, organization aggregations, website projections, generated docs, package surfaces, calibration products, or reports must rebuild after a change.
- Building a durable regeneration backend that must survive failed, missing, or unreliable GitHub Actions runs.
- Designing executor-independent retries, leases, receipts, verification, or dependency ordering for derived work.
- A cross-repository work graph has exact identities but still needs a deterministic derivation/freshness layer.

When the derivation crosses authority boundaries, load `interdependent-work-graph` as well. When designing a continuing automated feedback cycle around make-fresh operations, load `loop-eng` as well.

## Non-trigger

Do not load this skill merely because code is being compiled, tests are being run, or a user says "rebuild" once.

It is unnecessary when:

- the build has no persistent derived artifact;
- no later consumer needs to know whether an existing artifact remains valid;
- the operation is already completely owned by a repository-local deterministic build with no stored freshness decision;
- the question is only about scheduling or queue implementation rather than derivation correctness.

Fresh-making may use a scheduler or queue, but it is not queue doctrine.

## Authority boundary

Fresh-making never promotes a derived consumer into the authority for its inputs.

```text
producer authority -> exact input identity
                          |
                          v
                  fresh-making decision
                          |
                          v
                  derived artifact + receipt
```

- A UCNS-derived artifact does not become UCNS canon because it was regenerated successfully.
- An organization projection does not become authority for repository-owned MSDMD declarations.
- A backend may trigger an owning repository's generator; it must not silently substitute its own interpretation of that repository's canon.
- Successful regeneration proves derivation consistency under the declared contract, not theorem status, empirical validity, semantic correctness, certification, or publication approval unless those are separately verified by their owning authorities.

## State model

Use these target states:

```text
fresh
making-fresh
blocked
hmmm
```

`stale` is a **diagnosis**, not a durable workflow state. It means a known freshness predicate is false and therefore induces make-fresh work.

Keep execution attempt state separate from target freshness state. A useful attempt state machine is:

```text
requested
-> ready
-> leased
-> running
-> verifying
-> succeeded

          \-> failed
          \-> cancelled
          \-> hmmm
```

Important distinctions:

- a target can be not fresh even when no attempt has failed;
- an attempt can fail while the previously published target remains valid for its older declared inputs;
- a successful process exit is not a fresh result until verification and receipt publication succeed;
- unknown identity, ambiguous authority, or unverifiable output is `hmmm`, not fresh and not fabricated failure evidence.

## Derivation specification

Every make-fresh target needs a declared derivation specification. The minimal conceptual shape is:

```json
{
  "schema": "the-interdependency.fresh-making-spec",
  "version": "1.0.0",
  "target": "org-msdmd",
  "inputs": [
    {"name": "ucns", "identity": "git:<40-hex-sha>"},
    {"name": "edcm", "identity": "git:<40-hex-sha>"}
  ],
  "generator": {
    "identity": "git:<generator-repo>@<40-hex-sha>",
    "command": "python -m ..."
  },
  "outputs": [
    {"path": "generated/example.ts"}

From The-Interdependency/skill-lib, MPL-2.0.

More from The-Interdependency/skill-lib