/loopx-material

name: loopx-material
description: Operate an explicitly activated LoopX Material Lifecycle for a connected project. Use for material-store inventory, lossless migration, candidate/archive transitions, exact-read-backed ranking, ranked-entry rebuilds, bounded Explore intake, owner-gated apply, rollback, and audit. Do not use for ordinary one-off reading or research when the project has not activated Material Lifecycle.

LoopX Material

Use this skill for the lifecycle and authority of a project's durable material store. Source discovery, domain-specific scoring, and note writing may be provided by project skills; this skill owns the generic lossless lifecycle.

LoopX ships the canonical source for this skill, but does not install it into the user's global skill directory. Install a managed copy only in a connected project that explicitly enables Material Lifecycle:

loopx project-skill install \
  --project . \
  --skill loopx-material \
  --surface codex \
  --execute

Use `--surface claude-code` or `--surface opencode` for those hosts; repeat the flag to install multiple host-native copies in one transaction. Managed copies live under `.agents/skills/`, `.claude/skills/`, or `.opencode/skills/` and are upgraded or removed through the same CLI. Project-local discovery does not itself activate material-store writes; the selected execution owner still needs explicit Material Lifecycle source authority.

Activation Gate

Before changing a material store:

1. Resolve the current project and execution owner. For a Goal route, use the existing registered agent/active Todo. For an ordinary project route, resolve the current Core project context and accepted request; do not run `start-goal` or create a dummy Goal merely to obtain material metadata. 2. Run `loopx project-skill status --project . --skill loopx-material` and confirm the required host surfaces are current. 3. Require explicit activation: either the selected Goal Todo targets `material_lifecycle`/the Goal declares its source profile, or the project source owner declares an active material profile and an existing Core workspace write grant. A catalog entry, scope reference or skill copy is not activation. 4. Confirm the Goal boundary or Core project write grant covers the exact private adapter/authority paths. The project source verifier must bind the current caller, audience, store/profile and owner gate, including expiry and revocation. Ref names never grant access; enforce the authorization fence within staging/publication as well as preflight checks. 5. Run `loopx material-lifecycle architecture --format json` and preserve its default-off, owner-gated, provider-neutral boundaries. The project source route supports inventory, candidate intake/rollback, rerank packets, readable projection and settlement; it does not widen Goal-only migration, rebuild or Explore APIs.

If the project-local skill is missing, preview an explicit project install; do not fall back to a global copy. If activation or authority is missing, stop before source mutation. Create a bounded setup todo or owner gate; do not invent a store or treat chat history as authority.

Ownership Boundary

Keep these responsibilities separate:

• **Project source adapter**: locates and reads the project's private source

files, database, documents, or provider.

• **Research/reader skill**: recalls candidates, performs exact reads, and

produces source-quality and domain-value evidence.

• **Decision Context**: supplies revision-bound objectives, changed facts,

conflicts, and accepted decisions.

• **Material Lifecycle**: owns inventory, migration, lifecycle transitions,

ranked-entry rebuild, rerank proposals, apply receipts, and rollback.

• **Content or notes workflow**: consumes selected material and produces an

artifact; it does not rewrite candidate/archive/ranking truth by itself.

Workflow

1. Snapshot And Inventory

Read the source authority before proposing structural change.

• Record source revision, byte/content digest, lifecycle counts, parse errors,

stable material references, and a verified backup.

• Keep raw content, private paths, URLs, provider payloads, and credentials out

of public packets and commits.

• Preserve the original source until a verified cutover and rollback rehearsal

have both succeeded.

No migration, rebuild, or rerank may begin from an unverified partial parse.

2. Normalize Lifecycle

Use stable material references across:

candidate -> active -> archived
                 \-> carryover
archived -> active

Every transition needs a revisioned evidence or decision reference. Archiving must preserve the original source reference and an archive reference. Reading, summarizing, or publishing a note does not implicitly archive a material.

3. Promote Exact-Read Evidence

Recall is advisory. Before a material affects ranking or lifecycle:

1. retrieve the candidate through the configured provider or local search; 2. exact-read the authoritative source; 3. record source revision and read scope; 4. reject stale, conflicting, unreadable, or only-secondary claims; 5. pass only promoted evidence into Decision Context or ranking.

Do not start Explore merely because the current list feels incomplete. Explore begins only from a named evidence gap, bounded query plan, budget, and stop condition.

4. Settle Candidate Ranking

Before reporting candidate intake complete, settle its ranking against the current Decision Context:

• record exactly one disposition: `top_window`, `ranked_backlog`, or

`no_change`;

• let the project adapter classify value from exact-read evidence, current

objectives, overlap, and artifact convertibility rather than tier alone;

• require high-value materials to gain verified membership in the Top-N or

explicit ranked backlog;

• require a reason for `no_change` and use it only for standard-value or

substantiall