Loopx Material

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 goal still needs explicit Material Lifecycle authority.

Activation Gate

Before changing a material store:

1. Resolve the current project, goal_id, registered agent, and active todo through loopx start-goal --guided, loopx status, or loopx diagnose.
2. Run loopx project-skill status --project . --skill loopx-material and confirm the required host surfaces are current.
3. Confirm the selected todo explicitly targets material_lifecycle, or that the goal authority declares an active Material Lifecycle profile and its source store. A catalog entry or project-local skill is not activation.
4. Confirm the goal boundary covers the exact private adapter and authority paths. Public LoopX contracts never grant access to private source content.
5. Run loopx material-lifecycle architecture --format json and preserve its default-off, owner-gated, provider-neutral boundaries.

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 substantially duplicative materials;
• keep candidate intake and ranking as separate receipts and, when ranking changes, separate authority revisions; then join them with an intake-ranking settlement receipt;
• preserve displaced Top-N entries in the ranked backlog and preserve protected anchors unless changed Decision Context or explicit owner authority moves them.

If ranking apply, readback, projection, or rollback readiness fails, repair or roll back before reporting the intake as complete.

5. Rebuild Ranked Entries

A ranked entry must represent one independently sortable reading or action unit, not a display bucket.

• Default to at most three primary materials per ranked entry.
• When an entry exceeds the limit, create deterministic child entries and rank them independently.
• Do not hide overflow in an unranked supporting index.
• Preserve exact membership: every selected material appears exactly once across the ranked set.
• Preserve stable material references and canonical source records.
• Keep an explicit ranked backlog beyond a visible Top-N.

Splitting is semantic, not mechanical. Group materials only when they jointly support one decision or learning outcome; separate materials whose value, urgency, reader action, or evidence maturity differs.