debug-stale-classification
Diagnose why a necroflow RuleCall did or did not rerun using consumed hashes, invalidators, and forced invalidation.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- debug-stale-classification
- description
- Diagnose why a necroflow RuleCall did or did not rerun using consumed hashes, invalidators, and forced invalidation.
03 SKILL.md 正文
Debugging necroflow cache classification
Ask live tools first
necroflow explain job.toml
necroflow explain --node counts job.toml
necroflow explain --json job.toml
necroflow doctor job.toml
Explain reports RuleCalls in registration order with nested output Nodes. Reasons include output_missing, up_to_date, parent_will_run, consumed_hash_missing, consumed_hash_other_hasher, parent_content_changed, parent_hash_unchecked, parent_undecided, dependency_metadata_missing_or_invalid, dependency_metadata_mismatch, forced_invalidation, invalidator_changed, and compromised_prior_state.
Classification model
planning.py classifies canonical RuleCalls, not individual output Nodes.
- Request closure starts from selected Nodes, then follows owning calls and
parent_calls. - Any missing declared co-output makes complete call
MISSING. - Non-
up_to_datepersisted state, forced call key, or changed output invalidator makes callSTALE. - A parent scheduled for execution also marks active descendants for replay by default. Every child still waits until all parents settle successfully.
- For every parent Node, compare recorded
dependencies.toml: consumed_hashwith current bytes. - Missing or malformed consumed metadata is stale. Matching hashes preserve a cache when parents did not rerun, or when
reuse_unchanged=Trueexplicitly allows reuse after rebuilding them. - Existing inactive call workdirs are listed in
plan.orphans; they never run. - Verdicts and reasons are in
plan.verdicts/plan.reasonsfromplan_execution(dag), not on the RuleCall.
Current hashes trust .rip/{filename}.hash only while output mtime is no newer than hash-file mtime. Newer outputs are rehashed. External edits preserving or backdating mtime are unsupported.
Frequent causes
- Different identity: command, config, contracts, shell path, or parent lineage changed. New path is missing; old path may be orphan.
- Missing sibling: one absent co-output makes atomic call missing.
- Missing consumed hash: legacy or malformed dependency metadata forces safe replay.
- Parent rebuilt, child cached:
--reuse-unchangedwas enabled and output bytes were identical. - Parent rebuilt, child replayed: default cascading policy, changed output bytes, or another child cache check required replay.
- Bare external path string: fingerprint includes path text, not external bytes. Ingest with
symlink(Type, path), use an invalidator, or include content in config. - Leftover
.rip/state = running: compromised call reruns (a crash or kill; a failure elsewhere no longer leaves running siblings unrecorded). - Constraints and
repeat: execution policy, excluded from identity.
Force replay
necroflow run --invalidate LABEL job.toml
necroflow run --reap NAME job.toml
Python:
dag.run(forced_stale_call_keys={node.rule_call.relative_path})
Forced labels do not add requirements.
Inspect metadata
<workdir>/.rip/state
<workdir>/.rip/dependencies.toml
<workdir>/.rip/{filename}.hash
<workdir>/.rip/{filename}.invalidation
<workdir>/.rip/job.log
<workdir>/.rip/run.toml
<workdir>/.rip/graph.tgf
04 同仓库更多 Skills
use-necroflow
Write, inspect, run, and debug downstream Necroflow pipelines with typed artifacts, Python workflows, and job TOMLs. Use when creating or operating a Necroflow workflow; framework internals have separate contributor guidance.
write-a-scheduler
How to write a custom necroflow RuleCall scheduler using current three-argument protocol.
use-necroflow
暂无简介
necroflow-style
necroflow coding style for AI agents — invariants and anti-patterns derived from the git history. Load before writing or refactoring necroflow source code.
add-a-rule
How to declare a necroflow rule correctly — command decorators, built-in file rules, placeholders, typed outputs, and common mistakes.