Artifact Tracking

Artifact Tracking Skill

Token-efficient tracking artifacts for AI agent orchestration.

Quick Operations (CLI First)

Scripts location: .claude/skills/artifact-tracking/scripts/

IntentTree SDLC sync (optional)

Mirror plans + .claude/progress/** into the shared IntentTree instance as a typed Feature → Phase → Task tree (markdown stays canonical; nodes are a derived projection). When INTENTTREE_SDLC_SYNC=1 and INTENTTREE_TREE are set, status writes auto-sync (best-effort, non-fatal) via intenttree_sync.push_to_intenttree. Full guide + repo→tree map: intenttree-sync.md.

Script Inventory

Completion Gate (§4.4 of delivery-quality spec)

update-status.py -s completed rejects unless at least one of:

1. Both --started <ISO-8601> and --completed <ISO-8601> are supplied, OR
2. At least one --evidence item is provided.

Use --force to override; a WARNING is printed to stderr. This gate prevents batch-flip completions with null timing signals (failure class: Batch-flip completion).

# Correct — with timing
python scripts/update-status.py -f FILE -t T7-003 -s completed \
    --started 2026-04-22T10:00Z --completed 2026-04-22T17:00Z \
    --evidence "commit:abc123" --verified-by P16-003

# Force override (log WARNING, use sparingly)
python scripts/update-status.py -f FILE -t T7-003 -s completed --force

New flags:

Phase Exit Gate

Run before marking any phase completed. Fails nonzero if any completed task is missing started, completed, verified_by, or evidence.

# Human report
python scripts/validate-phase-completion.py -f .claude/progress/prd/phase-7-progress.md

# JSON (for scripting)
python scripts/validate-phase-completion.py -f FILE --json

AC Coverage Matrix

Verify every AC in the implementation plan is referenced by at least one verification task, and every verification task cites at least one AC.

# Full matrix (phase exit)
python scripts/ac-coverage-report.py \
    --plan docs/project_plans/implementation_plans/my-plan.md \
    --progress .claude/progress/prd/phase-13-progress.md \
    --progress .claude/progress/prd/phase-16-progress.md

# Plan approval gate: reject vague ACs without target_surfaces
python scripts/ac-coverage-report.py --plan PLAN --dry

# JSON output
python scripts/ac-coverage-report.py --plan PLAN --progress P --json

AC format in implementation plans (structured block after heading):

#### AC R3.4: Status Distribution filter narrows planning surfaces
- target_surfaces:
  - components/Planning/PlanningSummaryPanel.tsx
  - components/Planning/PlanningGraphPanel.tsx
- verified_by: [P16-003, P16-012-smoke]

Plan Status Management

Use for: PRDs, implementation plans, phase plans, SPIKEs, quick-feature plans, design-specs, meta-plans, and reports. design-spec, meta-plan, and report are supported types in --type alongside the original five.

manage-plan-status.py accepts the canonical 15 NodeStatus values and the legacy alias spellings (draft, complete, pending, in-progress, review, accepted, …), but it normalizes an alias to its NodeStatus on write via the shared _status_aliases.py map. The CCDash-era approved / superseded spellings are no longer accepted — use ready / archived.

Canonical Status Enforcement

validate-plan-frontmatter.py is the linter that enforces the ratified cross-app status value space — the 15-value IntentTree NodeStatus enum (docs/agentic-operator/contracts/frontmatter-schema.md §4). It derives its MUST/SHOULD/MAY field sets by parsing the machine-readable block in .claude/skills/planning/references/plan-frontmatter-schema.md (falling back to a hardcoded mirror).

# Check the corpus (report only; never writes). Exit 0 = clean, 2 = violation(s).
python scripts/validate-plan-frontmatter.py docs/project_plans

# Machine-readable summary (per-value would-change counts, violations, changes)
python scripts/validate-plan-frontmatter.py docs/project_plans --json

# Additive, format-preserving autofix (rewrites ONLY the status value token + inserts
# planning_maturity where implied). Review a dry-run diff before applying corpus-wide.
python scripts/validate-plan-frontmatter.py docs/project_plans --apply

• Exit codes: 0 clean (all statuses are a NodeStatus or a losslessly-resolvable alias), 2 one or more violations (hand-review / invalid / unresolvable), 1 usage error.
• Advisory (v1): it reports; the caller decides. The exit code distinguishes clean vs violations so a gate can consume it, but the linter does not itself block a commit.
• The alias map is the ratified + claude-decided rule (Shipped Work Ledger M1). Edit it in one place: scripts/_status_aliases.py.

Authoring-Time Gate (M4 L1, FR-12)

check-plan-authoring.py is the gate FR-12 asks for: a check that runs the moment a plan is authored, not only later against the whole corpus. It checks one file (or a directory, for the corpus-wide measurement) for exactly two things:

# Check one newly-authored file (report only; never writes). Exit 0 = clean, 2 = violation(s).
python scripts/check-plan-authoring.py docs/project_plans/PRDs/my-new-feature-v1.md

# Corpus-wide measurement (aggregate summary, same script, a directory instead of a file)
python scripts/check-plan-authoring.py docs/project_plans --json

• Exit codes: 0 clean (warnings may still print), 2 one or more violations (each naming the file + field + bad/missing value), 1 usage error.
• Advisory (D-M4-1): "fails the gate" means this non-zero exit + named violation — it is not a blocking git hook or CI check, and none is added. The caller (the planning workflow below, or a human) decides what to do with the result.
• Missing feature_slug is a violation because it is the join key the Shipped Work Ledger program exists to establish. Missing itt_node_id/intenttree_tree is only a warning — a plan is legitimately authored before its tree exists; stamp-plan-binding.py back-fills those later. Do not flip this: making the node/tree binding a violation would fail every plan at the moment it is authored, which is exactly when it cannot yet be satisfied.

Node-Side feature_slug Stamping (M2, FR-6/FR-7)

stamp-node-slug.py writes meta.feature_slug (+meta.plan_ref when known) onto the IntentTree nodes a plan file's frontmatter — or the sync-bindings table alone — resolves to. It is the NODE-side half of the Shipped Work Ledger M2 join; the FILE-side writeback (itt sync import --stamp-frontmatter) already shipped upstream in ../intenttree and is a dependency, not reimplemented here.

# Dry-run (default; never writes). Exit 0 = clean, 2 = one or more conflicts.
python scripts/stamp-node-slug.py --tree $INTENTTREE_TREE

# Machine-readable summary (resolution-path breakdown, would-stamp list, conflicts)
python scripts/stamp-node-slug.py --tree $INTENTTREE_TREE --json

# Commit the stamps
python scripts/stamp-node-slug.py --tree $INTENTTREE_TREE --apply

Resolution order, most-authoritative first: (a) direct — a plan file's own itt_node_id + feature_slug; (b) source_artifact — a plan file's source_artifact_id resolved through the sync-bindings table to a node set; (c) retroactive_binding — the bindings table's own source_task_id: "feature:<slug>" entry, no plan file required. A node already carrying a different feature_slug is never overwritten — it is reported as a conflict and the run exits non-zero (FR-7). Every write is a read-merge-write against the node's live meta (itt node update --meta replaces the whole dict server-side — a naive write would destroy plan_ref/fingerprint/etc.), so pre-existing meta keys always survive.

verify-slug-roundtrip.py is the M2 acceptance-criteria checker: for a tree (optionally one --slug), it verifies every stamped node's feature_slug → plan_ref → plan file → feature_slug round trip is self-consistent, reporting PASS/FAIL per feature with a reason on failure. It is read-only (no --apply — there is nothing for it to write).

python scripts/verify-slug-roundtrip.py --tree $INTENTTREE_TREE
python scripts/verify-slug-roundtrip.py --tree $INTENTTREE_TREE --slug shipped-work-ledger --json

Both scripts talk to IntentTree only through the injectable _itt_client.IttClient seam, so their tests fake every itt response and run offline (no live server, no network).

File Locations

Policy: .claude/specs/doc-policy-spec.md

YAML Quick Reference (v2)

---
type: progress
schema_version: 2
doc_type: progress
prd: "prd-name"
feature_slug: "prd-name"
phase: 2
status: in_progress
created: 2026-02-19
updated: 2026-02-19
prd_ref: null
plan_ref: null
commit_refs: []
pr_refs: []

owners: ["agent-name"]
contributors: []

tasks:
  - id: "TASK-2.1"
    status: "pending"
    assigned_to: ["agent-name"]
    dependencies: []

parallelization:
  batch_1: ["TASK-2.1"]
---

Schema Inventory

Field-level guidance: .claude/skills/artifact-tracking/schemas/field-reference.md

Post-Implementation Updates

After committing or opening a PR, update traceability fields:

python scripts/update-field.py -f FILE --append "commit_refs=<SHA>"
python scripts/update-field.py -f FILE --append "pr_refs=#123"

Use commit_refs and pr_refs on PRDs, plans, phase docs, and progress files so CCDash can correlate planning docs with delivery artifacts.

When NOT To Use

• Product/source code changes — this skill tracks planning + progress artifacts, not code.
• IntentTree node mutations — the markdown is canonical; nodes are a derived projection. Use the intenttree / intenttree-cli skills (or the sync scripts here) to project, never to author node state directly.
• Non-plan documents — READMEs, human guides, and vault pages are out of scope; the linter only enforces status on plan-class frontmatter and skips files with no top-level status.
• Choosing/defining the status vocabulary — the enum is ratified upstream (docs/agentic-operator/contracts/frontmatter-schema.md §4). This skill implements it; it does not relitigate it. To change the alias map, edit scripts/_status_aliases.py and land the same-PR contract diff the governance gate requires.
• CCDash / MeatyWiki schemas — those apps own their own envelopes; do not enforce them here.

Do Not Say

• Do not claim validate-plan-frontmatter.py or check-plan-authoring.py block commits or CI — both are advisory in v1 (they report; the caller decides). A blocking gate is a v2 decision. Do not add a pre-commit hook or CI step that consumes their exit code.
• Do not treat a missing itt_node_id/intenttree_tree as a check-plan-authoring.py violation — it is a warning only. A plan is legitimately authored before its tree exists.
• Do not auto-map a hand-review status value (reconciled-for-planning, handoff-for-planning, the active | paused | blocked placeholder, or any unknown value). Report it; a human resolves it.
• Do not describe the autofix as a full re-serialize — it edits only the status: value token in place and inserts planning_maturity additively; unrelated frontmatter is untouched.
• Do not tell a user to run the corpus-wide --apply without a reviewed dry-run diff first.
• Do not present approved / superseded as valid statuses — they are dropped; use ready / archived.
• Do not claim stamp-node-slug.py reimplements the file-side frontmatter writeback — that is itt sync import --stamp-frontmatter in ../intenttree; this tool only writes the node side.
• Do not claim stamp-node-slug.py overwrites a conflicting feature_slug — FR-7 forbids it; a conflict is reported and the run exits non-zero, a human resolves it.
• Do not describe itt node update --meta as a merge — it REPLACES the whole meta dict server-side; stamp-node-slug.py only stays additive because it reads-merges-writes in Python before calling it.
• Do not claim what-shipped.py shows everything that shipped. It shows what is joinable: a completed node must carry meta.feature_slug, and evidence must exist in a plan file's own frontmatter. Measured 2026-07-31 in agentic_meta_dev: 34 completed · 8 joinable · 26 unjoinable, 6 with evidence. The unjoinable nodes are hand-created with no join key — reported, never hidden.
• Do not claim the node-scoped POST /api/v1/nodes/{id}/validations route exists. It 404s on the running server (verified 2026-07-31); record_validation falls back to CompletionEvidence(kind=validation). The typed ValidationRun row is forward-compatibility only.
• Do not claim validation_commands drives anything today — it appears in 0 of 219 plan files. Test evidence attached by these tools is CCDash-summary-shaped, not per-command rows.
• Do not match an external link on the request's system field when reading — the server returns source_system. Matching on system alone silently never matches, which makes the FR-11 pre-read re-write every link on every run (this was a real, live-only defect; the offline fake echoed system and the test passed).

Detailed References

• Creating files: ./creating-artifacts.md
• Updating tasks: ./updating-artifacts.md
• Querying data: ./querying-artifacts.md
• Validating: ./validating-artifacts.md
• Orchestration: ./orchestration-reference.md
• Best practices: ./best-practices.md
• Common patterns: ./common-patterns.md
• Format spec: ./format-specification.md
• Templates: ./templates/
• Schemas: ./schemas/