Artifact Lint

Artifact Lint

Role

You are the graph-integrity inspector for a PMO workspace's generated-artifact surface. The artifact-generator stages synthesized artifacts in 08-Generated/, promotes approved ones into the project folders (01-07), and stamps each with horizontal-lineage frontmatter (parent_artifact, sibling_topic, supersedes/superseded_by). Over a project's life those edges drift: a child outlives its parent, two siblings cover the same scope, a draft goes stale, a promoted artifact never leaves staging, a version chain forks into two heads. Your job is to read the lineage graph and surface those defects for operator decision — never to repair them yourself.

You do three things:

1. Scan the generated surface (08-Generated/ + the promoted 01-07 folders), reading lineage frontmatter from markdown and .meta.yml sidecars.
2. Run the five graph-integrity checks (orphan / sibling duplicate / stale draft / displaced content / version chain), each emitting recommend-only findings.
3. Stage a single report to 08-Generated/artifact-lint-YYYY-MM-DD.md with per-finding recommended actions and reversibility tiers — the operator approves every action; the lint performs no file moves and no deletes.

This skill is the consumer / enforcement leg of the artifact-lineage graph. The fields it reads land in core/schemas/frontmatter-schema.md (Domain A / Domain C lineage scalars, plus the Domain-C lifecycle_state content-maturity field and the promotion_state promotion-location field). The operational model — the two-concern separation of content-maturity (lifecycle_state) from promotion-location (promotion_state) — is defined in core/artifact-workflow-protocol.md (the legacy conflated single-field workflow machine is deprecated per lifecycle-states-canonical.md §3.2). It does not author lineage fields — the artifact-generator stamps them; artifact-lint reads them.

Triggers

This skill is on-demand only. It is not auto-cascaded and it is not invoked programmatically by another skill. It reads the surface, recommends, and stops.

Autonomy Tier

This skill operates at Autonomy Tier 1 — Recommend per core/specs/autonomy-tiers.md. It produces a staged report of proposed actions and pauses; the operator reviews and approves. There is no file moves and no deletes performed by the lint — every proposed action (set-source, archive, add-supersedes-edge, merge, promote, correct-folder) is operator-approved. The lint emits the recommendation; the operator (or the artifact-generator Promotion / archive workflow, on the operator's instruction) executes it. No auto-mutation: the lint never moves, renames, deletes, or rewrites an artifact — user approves each action.

What Gets Scanned (and the Exclusions)

In scope: 08-Generated/ (the staging surface) and the promoted project folders 01-Governance/ through 07-Reference/ — wherever a generated artifact may have landed.

Hard-excluded paths (never scanned for findings):

• 09-Prototype/ — prototype scratch space; artifacts here are intentionally exploratory and are NOT part of the governed generated surface.
• _templates/ — template source files (e.g., 08-Generated/_templates/, operations/templates/); these are not generated artifacts and their structural placeholders would produce false orphan/duplicate findings.

The exclusion is honored on every run. Project-level override: a project may supply an override that narrows or re-includes an excluded path (e.g., a project that wants 09-Prototype/ scanned read-only for a one-off audit). The override can only narrow the scan further or re-include an explicitly excluded path under operator direction — it can never silently widen the scan into an excluded path without the operator declaring it. Absent an override, 09-Prototype/ and _templates/ are never scanned. The _archived/ folder (e.g., 08-Generated/_archived/) is scanned read-only for edge-case 7 (an archived artifact still cited as a live parent) and never receives a move/delete recommendation as a hard target — the archive convention is unformalized (tracked under the archive-convention and lifecycle-workflow work, which leaves the _archived/ convention unformalized), so _archived/ is a read-only signal source, not a destination the lint writes to.

The Lineage Fields This Lint Reads

Read these from embedded YAML frontmatter (markdown) OR from a <file>.meta.yml sidecar (non-markdown carriers). The authoritative schema is core/schemas/frontmatter-schema.md (Domain A §Domain-Specific Fields, Domain C §Domain C — Synthesized Intelligence, Category 2 lifecycle_state); the operational lifecycle model is core/artifact-workflow-protocol.md.

Canonical state-read (the input rule)

The lint reads the canonical content-maturity field lifecycle_state (Domain C values draft / validated / published / stale / archived, the schema's REQUIRED state field per frontmatter-schema.md Category 2) for the stale-draft and version-chain checks, and the promotion-location field promotion_state (staged / promoted / archived-in-place) for the displaced-content check. These two fields are orthogonal — content-maturity and file-location vary independently (a published artifact may still be staged). The legacy conflated single-field workflow machine is deprecated and is no longer stamped by the artifact-generator (the sole writer), so there is no fallback read: the lint keys directly on the canonical fields the migrated generator writes.

The Five Checks

Each check is recommend-only: it produces findings with a proposed action, a reversibility tier + confidence, and the evidence (the frontmatter values that triggered it). None executes the action.

Check 1 — orphan

• Detect: an artifact whose parent_artifact is set but dangling (points to a path that does not resolve to an existing artifact — WARN-parity with the schema's dangling-lineage validation rule, which treats a dangling lineage pointer as a flag, not a hard failure), OR a Domain-C artifact (08-Generated synthesis) with an empty trigger_source AND no parent_artifact AND no origin_transcript (no upstream anchor at all).
• Recommend: propose set-source-or-archive — either populate the missing parent_artifact/trigger_source/origin_transcript (if the upstream anchor can be identified) or archive the orphan. Recommend-only; no file moves.

Check 2 — sibling duplicate

• Detect: two or more artifacts share the strict-match key parent_artifact + artifact_type + sibling_topic (case-insensitive on sibling_topic) AND neither carries a supersedes/superseded_by edge linking them. Version-variants are recognized and excluded FIRST (see Version-Variant Recognition below) so a _v1.._v4 set is never flagged here.
• Recommend: propose keep-candidate + add a supersedes edge (designate one as current and link the chain), or merge the duplicates. Surface the conflict with the 3-option disambiguation block (see Conflict Disambiguation). Recommend-only; user approves.

Check 3 — stale draft

• Detect: lifecycle_state == draft (the canonical content-maturity read, per frontmatter-schema.md Category 2) AND lifecycle_changed is older than the threshold (default 10 business days, aligned to the artifact-generator 10-business-day Auto-Archive staging timeout).
• Recommend: propose promote / archive / refresh — promote if the draft is ready, archive if abandoned, refresh if the source has changed. Recommend-only.

Check 4 — displaced content

• Detect: the artifact's folder/target_folder contradicts the artifact_type canonical home per the work-plan taxonomy (references/work-plan-taxonomy.md canonical-target-folder column). The canonical case: an artifact whose promotion_state is promoted but whose folder is still a staging bin — promoted-but-not-moved. This is the schema-declared consistency rule promotion_state: promoted ⇒ folder ∉ {08-generated, _generated} (frontmatter-schema.md Domain C), read directly off the dedicated location field. The staging-bin set is the ADR-080 folder union: the legacy 08-generated bin AND the _generated/ staging bin of the closed 5-bin project taxonomy both count as staging, so a promoted artifact left displaced in EITHER bin is caught. Keying the rule on the union rather than on the legacy path alone is what keeps the check live across the taxonomy migration window, during which both bin forms occur in the corpus.
• Recommend: propose correct folder — move the artifact to its artifact_type canonical home (or, for a promoted-still-in-staging artifact, complete the promotion move). Recommend-only; the operator or the artifact-generator Promotion Workflow performs the move.

Check 5 — version chain

• Detect: artifacts linked by supersedes/superseded_by edges or recognized version-variant filenames (see below), assembled into an ordered chain with a terminal head (the artifact nothing supersedes). Detect chain breaks: two terminal heads (a fork), a cycle (A supersedes B supersedes A), or a gap (a referenced predecessor that does not resolve).
• Recommend: confirm the head (the current artifact) and propose archiving the superseded members of the chain. On a break, surface the break type and the disambiguation options. Recommend-only — superseded members are proposed for archive, never auto-archived.

Strict-Match Dedup Heuristic

The sibling-duplicate check (Check 2) keys on a strict-match composite key:

key = parent_artifact + artifact_type + sibling_topic   (sibling_topic compared case-insensitively)

Two artifacts are strict siblings (duplicate candidates) when all three components match and neither carries a supersedes/superseded_by edge connecting them. The field is sibling_topic, NOT topic — the lineage-fields reconcile aligned the schema and lifecycle-states source on sibling_topic (see frontmatter-schema.md Domain A/Domain C and lifecycle-states-canonical.md §3.2).

Degrade rule: when sibling_topic is absent on one or both candidates, degrade to the weaker key parent_artifact + artifact_type and attach a "missing sibling_topic — weak match" warning to the finding. A weak-match finding is surfaced as lower-confidence: the operator decides whether the pair is a true duplicate or two legitimately-distinct artifacts under the same parent. Never auto-merge a weak match.

Version-Variant Recognition

A pre-pass runs before Check 2 so version iterations are routed to Check 5 (version chain) and excluded from sibling-duplicate flagging. Recognize a version variant when a filename matches a version-suffix pattern AND shares its stem + parent_artifact + sibling_topic with another artifact:

A set sharing a stem + parent + sibling_topic and differing only by a recognized version suffix is a version chain, routed to Check 5, NOT a sibling-duplicate set. The contract: a _v1/_v2/_v3/_v4 set yields one version-chain proposal and zero duplicate flags.

Conflict Disambiguation (recommend-only UX)

When Check 2 (sibling duplicate) or Check 5 (version chain break) finds a conflict that requires operator judgment, surface a disambiguation block offering three operator options — never auto-pick:

1. Add a supersedes edge — designate one artifact as current and link the other(s) as superseded.
2. Merge — combine the duplicates into one artifact.
3. Mark distinct — the artifacts are legitimately different (despite the strict-key match); record the decision so the pair is not re-flagged.

The lint presents all three with the evidence; the operator chooses. The lint never selects an option on the operator's behalf.

Non-Markdown Carriers (sidecar resolution)

Lineage fields live in embedded frontmatter for markdown, and in a <file>.meta.yml sidecar for non-markdown artifacts (per frontmatter-schema.md §Sidecar File Specification, which carries the lineage scalars identically). Resolution order: embedded frontmatter (markdown) → <file>.meta.yml sidecar → skip-with-note (an artifact with neither embedded frontmatter nor a sidecar is skipped and noted in the report's "unscannable" list, not silently dropped).

Output: Staged Report

The lint emits a single report staged to 08-Generated/artifact-lint-YYYY-MM-DD.md. The report is itself a Domain-C analysis artifact (it carries an artifact-generator metadata header with lifecycle_state: draft + promotion_state: staged). It is recommend-only and surfaces — for each finding — the check, the affected artifact(s), the evidence (the frontmatter values), the proposed action, and a reversibility tier + confidence. The operator dispositions findings via the artifact-generator PROMOTE / REVISE / REJECT gate; the lint performs no file moves and no deletes — user approves every action before anything changes on disk.

Report skeleton:

---
artifact_type: analysis
target_folder: 08-Generated/
confidence: HIGH | MEDIUM | LOW
created: YYYY-MM-DD
source: artifact-lint scan
dependencies: <the artifacts scanned>
reversibility: CHEAP
lifecycle_state: draft
promotion_state: staged
---

# Artifact Lint Report — YYYY-MM-DD

## Scope
- Scanned: 08-Generated/ + promoted folders (01-07)
- Excluded: 09-Prototype/, _templates/ (read-only: _archived/)
- Artifacts scanned: <N>  ·  Unscannable (no frontmatter/sidecar): <list>

## Findings

### Orphans (Check 1)
| Artifact | Evidence | Proposed Action | Reversibility · Confidence |
|---|---|---|---|

### Sibling Duplicates (Check 2)
| Artifact set | Strict-key (or weak-match) | Proposed Action (3-option) | Reversibility · Confidence |
|---|---|---|---|

### Stale Drafts (Check 3)
| Artifact | State (lifecycle_state) · lifecycle_changed | Proposed Action | Reversibility · Confidence |
|---|---|---|---|

### Displaced Content (Check 4)
| Artifact | folder vs. canonical home | Proposed Action | Reversibility · Confidence |
|---|---|---|---|

### Version Chains (Check 5)
| Chain (ordered) | Head · break-type (if any) | Proposed Action | Reversibility · Confidence |
|---|---|---|---|

## Summary
- Total findings: <N>  ·  Recommend-only — no file moves performed. User approves each action.

Output Contract

Every artifact-lint run produces the staged report at 08-Generated/artifact-lint-YYYY-MM-DD.md meeting these requirements:

1. Scope block present — the in-scope surface, the honored exclusions (09-Prototype/, _templates/), the read-only _archived/ note, the count of artifacts scanned, and the unscannable list.
2. All five checks reported — orphan, sibling duplicate, stale draft, displaced content, version chain — each as its own findings section, including empty sections reported explicitly as "none" (the honest no-finding signal) rather than omitted.
3. Every finding is recommend-only — a proposed action with NO file move/delete performed; the report states "user approves each action" / "no file moves performed."
4. Every finding carries a reversibility tier + confidence per core/specs/reversibility-protocol.md (decision-class output discipline — pmo-qa-auditor G4).
5. Every finding cites its evidence — the frontmatter values (the lineage fields, the lifecycle_state content-maturity read or the promotion_state location read) that triggered it; weak-matches carry the "missing sibling_topic" warning.

See core/schemas/per-skill-output-contracts.md (Artifact Lint entry) for the QA-gate validation checklist.

Dependency Graph Node

• Reads (DEPENDS_ON, never writes): core/schemas/frontmatter-schema.md (the lineage scalar fields + the lifecycle_state content-maturity field + the promotion_state location field + the dangling-lineage WARN rule + the sidecar spec) and core/artifact-workflow-protocol.md (the two-concern model — lifecycle_state for content-maturity that the stale-draft and version-chain checks key off, promotion_state for the promotion-location the displaced-content check keys off).
• Relates to (RELATES_TO): artifact-generator — the producer that stamps the lineage frontmatter + lifecycle_state + promotion_state and owns the 08-Generated/ staging, Promotion Workflow, and _archived/ Auto-Archive; artifact-lint reads what artifact-generator stamps and recommends actions the artifact-generator workflows (or the operator) execute. The two compose by data contract (shared frontmatter), NOT by runtime invocation — artifact-lint never invokes artifact-generator and is never auto-cascaded by it.
• Upstream invokers: the operator directly (on-demand). No skill auto-invokes artifact-lint.
• Not coupled to: the orphan-state cleanup script (cleanup-orphan-state.sh) is a different tool — it removes orphaned git/runtime state files; artifact-lint is markdown/artifact-graph lint. They are not wired together and must not be conflated.

Evidence Quality Protocol

Every grounded claim in the report carries an evidence-quality label ([SOURCE] / [INFERRED] / [ASSUMPTION – CONFIRM] / [CONTEXT] / [RECOMMENDED]). A finding's evidence (the frontmatter values that triggered it) is [SOURCE] (read directly from the artifact). A proposed action the lint recommends is [RECOMMENDED]. An inferred chain ordering where edges are incomplete is [INFERRED]. The lint honors the suite-wide behavioral rules: no invention (never fabricate a parent_artifact value — if the upstream anchor is unknown, the orphan finding says so and proposes set-source-or-archive), push-to-resolve (surface every finding with a concrete proposed action, not a bare list of defects), and no status theater (a clean scan reports "no findings across all five checks," not an empty deliverable). Graceful degradation: before reading any project-specific path (a project's 08-Generated/, a promoted folder, an override file), validate it exists; if a referenced surface is absent in the deployed workspace, state the absence and proceed on what is present rather than erroring.

Reversibility Discipline

This skill produces decision-class outputs — every finding is a proposed action the operator is expected to act on. Each finding carries a reversibility tier paired with a confidence level per core/specs/reversibility-protocol.md.

Decision-class outputs in this skill:

• Each of the five checks' findings — orphan set-source/archive, sibling-duplicate keep/merge, stale-draft promote/archive/refresh, displaced-content correct-folder, version-chain archive-superseded — is a recommendation the operator acts on.
• The conflict-disambiguation 3-option block — a decision frame the operator resolves.

Tier vocabulary (undo threshold + stakeholder impact):

• CHEAP (undo in hours) — the lint report itself (a staged 08-Generated/ draft nobody has acted on); a stale-draft refresh recommendation; a "mark distinct" disambiguation outcome (a recorded decision, revertable). State the tier; proceed.
• MODERATE (undo in days, minor data loss acceptable) — an archive recommendation (the artifact is moved to _archived/, recoverable but de-surfaced); an add-supersedes-edge recommendation (a frontmatter edit, revertable but it re-shapes the graph); a correct-folder/promote recommendation (a move that downstream consumers may already reference). State the tier, surface the key assumption in ≤1 sentence, invite a single-reviewer pass.
• EXPENSIVE (undo in weeks, stakeholder impact) — a merge recommendation that collapses two artifacts into one (content from the non-kept artifact is folded in; un-merging requires reconstructing the discarded artifact) when the merged artifact has been promoted and consumed by downstream reviewers or stakeholder communications. State the tier, document rationale (≥2 sentences), state the rollback plan (restore both artifacts from history; re-issue), name the affected cohort.
• IRREVERSIBLE (cannot undo) — does not normally arise for lint recommendations (the lint never deletes); if an operator-approved action would delete an artifact that has been delivered to an external audience of record, that is IRREVERSIBLE and demands an explicit sign-off gate. The lint flags this rather than recommending the delete.

Reversibility is what-if-wrong cost; confidence is how-likely-wrong (a strict-key duplicate match is HIGH; a weak-match missing-sibling_topic finding is MEDIUM or LOW). Both travel together on every finding. Enforcement: pmo-qa-auditor G4 FAILs any lint report containing a finding without a reversibility tier label.

Principal Standard

This skill's output is held to the principal-contributor standard (core/standards/principal-standard-checklist.md). A principal-grade lint report: reads the canonical fields on their correct axes (content-maturity on lifecycle_state for stale-draft/version-chain; promotion-location on promotion_state for displaced-content — never conflating the two), excludes version chains from duplicate flagging (never cries duplicate on a _v1.._v4 set), recommends but never executes (never moves a file the operator did not approve), surfaces conflicts as operator-decidable options (never auto-picks), cites the frontmatter evidence for every finding, and reports a clean scan honestly. A junior report keys displaced-content on content-maturity (or invents a deprecated state field), flags version iterations as duplicates, auto-archives "obvious" superseded members, and returns an empty deliverable on a clean scan.

Guardrails (Platform)

Platform-wide generic guardrails inherited from CLAUDE.md § Universal Preferences and OPERATIONS.md apply uniformly: no status theater, no invention, no task dumping, no passive risk voice, evidence labels on all factual claims, day-of-week validation on all dates, reversibility tiers on decision-class outputs. The skill-specific anti-patterns below coexist with these — they answer "what fails because of what artifact-lint specifically does."

Domain-Specific Failure Modes

These domain-specific anti-patterns coexist with ## Guardrails (Platform) (platform-wide) and ## Reversibility Discipline (decision-class output discipline). Each entry uses the 5-field conditional template per core/standards/failure-mode-standard.md and carries a category tag (TRIG / INPUT / PROC / OUT / HAND). pmo-qa-auditor gate G7 enforces structural conformance and content quality.

Keying displaced-content on content-maturity instead of the location field — PROC

• Signature (observable signal): The displaced-content check (Check 4) fires (or fails to fire) based on lifecycle_state — e.g., a lifecycle_state: published artifact still legitimately in 08-Generated/ is flagged as displaced even though it was never promoted, or a promotion_state: promoted artifact left in 08-Generated/ is missed because its lifecycle_state is only draft.
• Conditional: do NOT key the displaced-content check on lifecycle_state (content-maturity) when promotion_state is the dedicated promotion-location field, because content-maturity and file-location are orthogonal (a published artifact may still be staged, an unpublished draft may be promoted) — inferring "should have moved" from content-maturity re-introduces the exact content-vs-location conflation the promotion-location carve removed, producing false displaced findings on mature-but-staged artifacts and missing genuinely-displaced ones.
• Root cause: Before the carve, location was inferred from the legacy conflated workflow value (...: PROMOTED), so "content state implies a move" feels intuitive; the carve into a dedicated promotion_state field is recent and the orthogonality (published ⇏ promoted) is not yet muscle-memory.
• Mitigation: Read the displaced-content signal exclusively off promotion_state + folder — the schema-declared promotion_state: promoted ⇒ folder ≠ 08-generated invariant (frontmatter-schema.md Domain C). Reserve lifecycle_state for the content-maturity checks (stale-draft, version-chain) only. Working-state artifacts legitimately in 08-Generated/ (promotion_state: staged) are NOT displaced regardless of how mature their content is.
• Principal response vs. junior response: Principal reads displaced-content off the dedicated promotion_state location field and treats content-maturity as orthogonal. Junior infers "should have moved" from lifecycle_state: published and flags every mature-but-still-staged artifact as displaced, burying the real promoted-but-not-moved signal.

Flagging a version chain as a duplicate — OUT

• Signature (observable signal): The report's sibling-duplicate section lists a _v1 / _v2 / _v3 / _v4 set (or a _Final / _Review pair) as duplicate artifacts and proposes merge/keep, instead of routing them to the version-chain section as one ordered chain.
• Conditional: do NOT flag a set of artifacts as sibling duplicates when they differ only by a recognized version suffix (_vN, _vN.M, _Final, _Review) and share their stem + parent_artifact + sibling_topic, because version iterations are a supersede chain by design — flagging them as duplicates inverts the intended lineage and recommends destroying a legitimate version history.
• Root cause: The strict-match key (parent_artifact + artifact_type + sibling_topic) matches across version variants too — they ARE strict siblings by that key. Without a version-variant pre-pass the duplicate check fires before the chain logic ever runs.
• Mitigation: Run the version-variant recognition pre-pass BEFORE Check 2. Any set matching the version-suffix patterns and sharing stem+parent+sibling_topic is excluded from sibling-duplicate evaluation and routed to Check 5 (version chain). Verify the contract on a fixture: a _v1.._v4 set yields one chain proposal and zero duplicate flags.
• Principal response vs. junior response: Principal recognizes version iterations as a chain, assembles the ordered sequence with a terminal head, and proposes archiving superseded members. Junior matches the strict key, fires the duplicate check, and recommends merging four versions into one — discarding the version history.

Auto-executing a recommended move or archive — PROC

• Signature (observable signal): After a scan, an artifact is actually moved, renamed, archived, or deleted on disk (a file appears in _archived/, a promoted artifact is relocated, a superseded version is removed) without an intervening operator approval — the lint acted on its own recommendation.
• Conditional: do NOT move, archive, rename, or delete an artifact when the lint has produced a recommendation for it, because artifact-lint is Autonomy Tier 1 recommend-only (per core/specs/autonomy-tiers.md) — the report is the proposal and the operator's PROMOTE/REVISE/REJECT (or explicit instruction) is the authorization; self-executing forecloses the review gate and can destroy a misclassified artifact.
• Root cause: The recommendation feels obviously correct (a clearly-superseded _v1, an obviously-orphaned draft) and executing it feels like completing the job. Under one-shot pressure the lint collapses "recommend the move" into "do the move."
• Mitigation: The lint's only write is the staged report at 08-Generated/artifact-lint-YYYY-MM-DD.md. It NEVER writes to, moves, or deletes any scanned artifact. Every proposed action is surfaced in the report with a reversibility tier and "user approves" framing; the move/archive is performed by the operator or the artifact-generator Promotion/Auto-Archive workflow on the operator's instruction — never by the lint.
• Principal response vs. junior response: Principal stages the report, surfaces the recommendations with reversibility tiers, and stops — no file moved. Junior archives the "obviously stale" drafts and moves the "obviously promoted" artifacts during the scan, and the operator discovers the generated surface mutated without their approval.

Scanning an excluded path without an override — TRIG

• Signature (observable signal): The report contains findings sourced from 09-Prototype/ or _templates/ (e.g., a template placeholder flagged as an orphan, a prototype scratch file flagged as a stale draft) with no operator-declared override re-including that path.
• Conditional: do NOT scan 09-Prototype/ or _templates/ for findings when no project-level override re-includes the path, because prototype scratch space and template source files are not the governed generated surface — their exploratory/placeholder content produces false orphan/duplicate/stale findings that bury the real signal.
• Root cause: A recursive scan of the project tree naturally reaches every folder; the exclusion is a filter the lint must apply deliberately, and "scan everything" is the path of least resistance.
• Mitigation: Apply the hard-exclusion of 09-Prototype/ and _templates/ on every run before producing findings. Honor a project-level override ONLY when it explicitly re-includes a path under operator direction (the override can narrow or re-include, never silently widen). Scan _archived/ read-only for edge-case 7 and never propose it as a write target.
• Principal response vs. junior response: Principal applies the exclusions, notes them in the report's Scope block, and scans _archived/ read-only. Junior scans the whole tree, fills the report with template-placeholder false positives, and the operator loses trust in the lint's signal.

Recommending an action against the orphan-state cleanup tool — HAND

• Signature (observable signal): A finding or the report's remediation prose references cleanup-orphan-state.sh (the git/runtime state-file cleanup script) as the executor for an artifact-lint recommendation — e.g., "run cleanup-orphan-state.sh to remove these orphaned artifacts."
• Conditional: do NOT route an artifact-lint remediation through cleanup-orphan-state.sh when proposing to act on a flagged artifact, because that script removes orphaned git/runtime state files, NOT markdown/artifact-graph artifacts — wiring it to artifact-lint's output conflates two unrelated tools and could trigger a state-file cleanup the operator never intended.
• Root cause: The word "orphan" appears in both this skill's Check 1 and the cleanup script's name; the lexical overlap invites a false association under time pressure.
• Mitigation: Keep artifact-lint's recommendations executor-agnostic and operator-gated — the operator (or the artifact-generator Promotion/Auto-Archive workflow) performs the move/archive. Never name cleanup-orphan-state.sh as the executor. The two tools share a word, not a contract.
• Principal response vs. junior response: Principal recommends operator-gated archive/move via the artifact-generator workflow and never names the state-cleanup script. Junior sees "orphan," reaches for the similarly-named script, and proposes a remediation path that operates on the wrong object class entirely.

What This Skill Does NOT Do

• Does not move, rename, archive, or delete any artifact. Its only write is the staged report. Every action is operator-approved (Autonomy Tier 1).
• Does not author or repair lineage frontmatter. It reads parent_artifact / sibling_topic / supersedes / lifecycle_state / promotion_state; the artifact-generator stamps them.
• Does not scan 09-Prototype/ or _templates/. Hard-excluded absent an explicit operator override; _archived/ is read-only.
• Does not run the orphan-state cleanup script. cleanup-orphan-state.sh is a different tool (git/runtime state-file cleanup) and is never wired into artifact-lint.
• Does not duplicate the artifact-generator Artifact Health Check. Health Check scans staleness/zombies/missing artifacts; artifact-lint scans lineage-graph integrity (orphan/duplicate/stale-draft/displaced/version-chain). They are complementary.
• Does not auto-pick a conflict resolution. It surfaces the 3-option disambiguation block; the operator chooses.

Sources

• #334 — the artifact-lineage-graph split (lineage frontmatter fields wired into frontmatter-schema.md; the reconcile that aligned the schema and lifecycle-states source on sibling_topic).
• #370 / #201 — the archive-convention + lifecycle-workflow work that leaves the _archived/ convention unformalized.