Diagnose config fragment gate failure before retry

After an ownership or expected-bytes gate fails on an application-owned config fragment, run a read-only diagnostic pass to classify the root cause and choose full operation restart versus abort, without refreshing baseline mid-attempt or retrying rename.

Diagnose config fragment gate failure before retry

After an ownership or expected-bytes gate fails on an application-owned configuration fragment, run a read-only diagnostic pass to classify the root cause and choose full operation restart versus abort, without refreshing baseline mid-attempt or retrying rename.

When to use

Use this when a replace operation already failed closed at the ownership gate, expected-bytes gate, publish gate, or empty-baseline classification, and the attempt temporary has been removed without rename.

Reach for this before blindly retrying the same baseline, before treating every byte mismatch as stale input, and before escalating to an operator without evidence.

Adjacent guidance covers running the gates, descriptor binding, empty-baseline branches, publish-gate timing, temp publish, and post-publish verification. This skill covers only the post-failure diagnostic pass that decides what a safe retry requires.

Assumes

The caller already:

• Recorded the operation baseline at attempt start, including presence metadata when the contract requires it.
• Removed the attempt temporary after gate failure.
• Did not rename over the published fragment during the failed attempt.

The failure it prevents

Gate failures surface as generic mismatch or abort messages. Without classification, agents and operators choose wrong next steps:

1. Blind retry with the same baseline after a concurrent edit, guaranteeing repeated failure or an unsafe publish if timing shifts.
2. Mid-operation baseline refresh to make a failure pass, discarding the fixed baseline contract that gates depend on.
3. Mislabeling symlink substitution as concurrent edit, or the reverse, leading to wrong escalation and wasted restarts.
4. Immediate rename retry in the same attempt after publish-gate failure, overwriting content that changed legitimately between gates.
5. Misreading partial descriptor binding as pure concurrent edit, when path-based byte reads from the failed attempt cannot prove same-inode mutation even though descriptor-bound metadata checks passed.

Reasoned example (not an executed test): an agent fails the publish gate with expected-bytes mismatch. It refreshes the baseline from the newly observed bytes and retries rename in the same attempt, publishing over a hotfix an operator applied during temp preparation. The diagnostic pass was skipped, so nobody recorded that the observed bytes differed from the operation-start baseline because of concurrent edit rather than stale capture.

Diagnostic procedure

Run read-only. Do not write, rename, truncate, or chmod during this pass.

1. Open the managed directory as a directory descriptor when the contract allows. Open the fragment relative to that descriptor with no-follow semantics. If the final component is a symlink, record entry type as symlink and stop classifying as a regular-file concurrent edit.

1. Capture observation snapshot from the open descriptor:

• entry type (regular file, symlink, absent, directory, other)
• owner identity and mode
• byte length
• raw bytes or digest read through the same descriptor-bound open
• optional inode or generation token only if the application contract exposes one; do not invent generations

1. Compare snapshot to the operation-start baseline (not a freshly chosen baseline):

• ownership or mode drift versus contract
• presence transition (absent to present, present to absent)
• byte length change
• digest mismatch

1. Compare snapshot to the failure context recorded by the gate that aborted:

• whether failure was at ownership gate, expected-bytes gate, empty-baseline branch, or publish gate
• whether descriptor-bound fstat passed before bytes disagreed (same-inode mutation signal)
• whether separate path stat and path read were used (path-string split signal)
• whether metadata and bytes used different binding styles in the same attempt (partial descriptor binding signal)

1. Assign one primary category using the decision table and overlapping-signal tie-break below. Secondary notes are allowed but must not override the primary category for retry policy.

1. Choose next action from the category policy. Never rename during diagnosis.

Classification decision table

All rows are reasoned outcomes, not executed test results.

Overlapping gate-context signals

When gate context records both descriptor-bound fstat pass and separate path stat or path read for bytes in the same failed attempt, the concurrentedit and pathstringsplitsuspected rows can both appear applicable. This is partial descriptor binding: metadata checked through a directory-relative no-follow open while bytes were compared through a path string.

Apply this tie-break (reasoned only, not an executed test):

1. Always read diagnostic bytes descriptor-bound. Never reuse path-based byte observations from the failed attempt for primary classification.

1. Initial primary category when failed-attempt bytes were path-based: pathstringsplit_suspected, even if descriptor-bound fstat passed on metadata. Path-based byte evidence cannot prove same-inode mutation.

1. Reclassification after descriptor-bound diagnostic bytes: when diagnostic digest is not equal to operation-start baseline and equal to the gate failure observation, primary category becomes concurrent_edit. Record a secondary note that the failed attempt used path-based byte reads and restart must use descriptor-bound gates only.

1. Elapsed baseline age never overrides step 3. Do not classify stale_baseline when descriptor-bound diagnostic bytes confirm digest mismatch against the operation-start baseline.

1. When diagnostic digest matches operation-start baseline but gate failed on path-based bytes: keep primary category pathstringsplit_suspected; the failed attempt likely observed a different inode or stale path resolution.

Category policies

concurrentedit, stalebaseline, unexpectedemptypresent, pathstringsplit_suspected

• Require a full operation restart: new attempt identity, new exclusive temp name, new baseline capture at restart start, then rerun all gates including publish gate.
• Do not refresh baseline inside the failed attempt.
• Do not retry rename in the failed attempt.

symlinksubstitution, ownershipdrift, baselinepresentnowabsent, concurrentwipe

• Abort and escalate. Read-only diagnosis may be attached to the report.
• Do not restart until the contract owner or operator resolves the integrity condition.

gateimplementationmismatch

• Stop automated retry loops. Preserve observation snapshot and gate context for maintainer review.

Worked example: publish gate mismatch misread as stale baseline

Reasoned example (not an executed test).

Setup. Baseline captured non-empty bytes at operation start. Agent writes temp, runs publish gate immediately before rename. Publish gate observes different non-empty bytes. Agent aborts and removes temp.

Diagnostic pass. Reopen with no-follow semantics. Observation snapshot shows regular file, matching ownership, digest equal to publish-gate observation, digest not equal to operation-start baseline.

Classification. concurrent_edit (baseline fixed at start; target changed during temp preparation).

Wrong action avoided. Refreshing baseline to the publish-gate bytes and retrying rename in the same attempt would publish over the intervening edit without a new operator decision.

Correct action. Full operation restart; operator decides whether the replacement intent still applies against the new on-disk bytes.

Worked example: partial descriptor binding with overlapping signals

Reasoned example (not an executed test).

Setup. Baseline captured non-empty bytes at operation start. Expected-bytes gate runs with descriptor-bound fstat on a directory-relative no-follow open for ownership and metadata, but compares bytes via a separate path-based read. Gate fails with digest mismatch. Gate context records both descriptor-bound fstat pass and separate path stat and path read. Agent aborts and removes temp.

Diagnostic pass. Reopen managed directory and fragment with no-follow semantics. Read bytes through the same descriptor-bound open. Observation snapshot shows regular file, matching ownership, digest not equal to operation-start baseline, digest equal to the gate failure observation.

Initial classification. pathstringsplit_suspected (failed-attempt bytes were path-based; metadata fstat pass alone is insufficient).

Reclassification. concurrent_edit after descriptor-bound diagnostic bytes confirm the on-disk fragment changed since operation start and match the gate observation.

Secondary note. Failed attempt used path-based byte reads; full restart must use descriptor-bound gates for both metadata and bytes.

Wrong action avoided. Classifying concurrentedit immediately from fstat pass alone would trust path-based byte mismatch as same-inode mutation evidence. Classifying stalebaseline from elapsed time would ignore confirmed descriptor-bound digest drift.

Correct action. Full operation restart with descriptor-bound gates only; operator decides whether replacement intent still applies against current on-disk bytes.

What this does not provide

• Not a substitute for running gates. Diagnosis follows failure; it does not replace ownership, expected-byte, publish, or post-publish verification steps.
• Not post-publish mismatch recovery. When rename already occurred and verification failed, use post-publish verification failure policy and operator escalation; do not use this skill to invent rollback.
• Not writer serialization. Diagnosis does not acquire locks or leases.
• Not empty-baseline branch definition. Presence branches remain in empty-baseline guidance; this skill consumes their classified categories when present.
• Not descriptor-bound gate implementation. How to bind gates belongs in adjacent guidance; this skill only classifies failures when binding was partial.

Failure policy

• Never mutate the fragment or managed directory during diagnosis.
• Never refresh the operation-start baseline mid-attempt to force a retry.
• Never retry rename in the same attempt after a publish-gate failure.
• Never classify concurrent_edit when entry type is symlink unless the contract explicitly treats symlinks as regular-file equivalents.
• Never classify concurrent_edit from failed-attempt path-based byte reads alone; require descriptor-bound diagnostic bytes or gate context showing descriptor-bound byte comparison.
• Never treat diagnostic read bytes as authorization to publish; restart gates are still required.

Claims and evidence

The diagnostic sequence and decision table follow from maintenance conversation thrdih-OceC1FecAn1tkspWtg sequence 1 (descriptor gate improvement B) and thrZbdD3NWrGMZZxxE2KWI-XQ sequence 1 (post-failure restart checklist deferred by empty-baseline guidance). The overlapping-signal tie-break and partial-binding worked example follow from maintenance conversation thr_XSQsZb5V-NEZ3ha-EyEI9w sequences 1 and 2. All examples are reasoned timelines only; no filesystem or concurrency tests were executed for this skill.

Supporting basis and limitations

Reasoning from maintenance conversations thrdih-OceC1FecAn1tkspWtg sequence 1, thrZbdD3NWrGMZZxxE2KWI-XQ sequence 1, and thrXSQsZb5V-NEZ3ha-EyEI9w sequences 1 and 2. Existing skills sklhSntu1DnYGIquRwDtEOlrQ and skl_yvd7HMkctp4N31hL8i6niQ explicitly defer post-failure recovery to separate guidance. No filesystem or concurrency tests were executed; all timelines and branch outcomes are reasoned examples only.

Change and rationale

Update adds tie-break rules and a worked example for partial descriptor binding when concurrentedit and pathstringsplitsuspected signals overlap. Closes ambiguity identified in thr_XSQsZb5V-NEZ3ha-EyEI9w without duplicating gate execution or post-publish verification procedures.