# Plan Source Artifact Audit Implementation Handoff

## Status

- Date: 2026-05-18
- Source type: discussion-to-implementation-doc
- Status: ready for planning
- Intended next step: create and execute a cross-repo implementation plan for
  `agent-kit` and `nils-cli`.
- Recommended plan:
  `docs/plans/plan-source-artifact-audit/plan-source-artifact-audit-plan.md`
- Recommended execution state:
  `docs/plans/plan-source-artifact-audit/plan-source-artifact-audit-execution-state.md`

## Purpose

Reduce repeated manual judgment in plan and durable-artifact lifecycle work
without turning cleanup into blind deletion. The implementation should make
plan-source bundles machine-checkable through `plan-tooling validate`, and add
a deterministic audit primitive that can classify durable coordination
artifacts as `delete`, `keep`, `rehome`, or `manual-review`.

## Source Inputs

- [U1] The user requested a plan for two follow-ups: a deterministic audit
  helper for repeated `durable-artifact-cleanup` decisions, and
  `plan-tooling validate` checks for source doc, plan, and execution-state
  linkage.
- [U2] The user explicitly said the audit helper is not urgent to implement as a
  script right now.
- [U3] The user asked to evaluate the `nils-cli` implementation directly in
  the cross-repo plan.
- [F1] `skills/workflows/plan/durable-artifact-cleanup/SKILL.md` currently owns
  the audit and policy workflow for obsolete source docs, plans,
  execution-state docs, handoff prompts, and related implementation artifacts.
- [F2] `skills/workflows/plan/docs-plan-cleanup/SKILL.md` currently owns the
  deterministic broad `docs/plans/` cleanup executor once keep/delete intent is
  known.
- [F3] `skills/workflows/plan/execute-from-plan/SKILL.md` allows direct
  source-doc execution only for bounded single-step work, or with an explicit
  direct-execution waiver recorded in execution state.
- [F4] `nils-cli` already ships `crates/plan-tooling` with `to-json`,
  `validate`, `batches`, `split-prs`, `scaffold`, and `completion`.
- [F5] `crates/plan-tooling/src/validate.rs` already validates the `Read First`
  primary source, source type, open questions, sprint metadata, and task shape.

## Confirmed Facts

- `durable-artifact-cleanup` is intentionally judgment-heavy today. It tells an
  agent what to inspect and how to decide, but it has no reusable deterministic
  classifier for repeated candidate sets.
- `docs-plan-cleanup` already has a deterministic shell executor and report
  format, but it assumes keep/delete intent is already known.
- Plan-created source docs under `docs/plans/<slug>/` are coordination
  artifacts, not automatically retained canonical docs.
- `execute-from-plan` now treats a sibling plan as the preferred execution
  source when a plan-created discussion or review source doc exists.
- `plan-tooling validate` is the right place to add bundle checks because it
  already parses plan markdown and resolves repo-relative primary source paths.
- The durable-artifact audit helper should be no-side-effect by default. It may
  classify and explain, but deletion should remain owned by the cleanup skill or
  `docs-plan-cleanup` executor.

## Decisions

- Treat bundle validation and cleanup classification as related but separate
  capabilities.
- Implement plan-source bundle validation inside `nils-cli` `plan-tooling`
  rather than in agent-kit shell or Python glue.
- Use `plan-tooling validate` for hard bundle consistency checks after normal
  plan validation. Initial checks should focus on sibling
  `docs/plans/<slug>/` bundles so existing non-bundle plans are not forced into
  an execution-state convention before execution starts.
- Use `plan-tooling artifact-audit` as the initial nils-cli home for the
  deterministic audit helper because it can reuse plan parsing, repo-root
  resolution, and CLI validation patterns. If later usage expands beyond
  planning and coordination artifacts, split shared scanning into `nils-common`
  or move the command into `agent-workflow-primitives`.
- Normalize audit result classes to `delete`, `keep`, `rehome`, and
  `manual-review`. Agent-kit wording should stop using
  `archive-or-rehome` as the canonical class name.
- Keep deletion as an explicit follow-up action. The helper emits an audit
  report; it does not remove files.

## Scope

- Extend `plan-tooling validate` so a plan-source bundle can verify:
  - the plan `Read First` primary source points at the expected source doc;
  - the source doc points back to the plan as the recommended next artifact;
  - the source doc names the recommended execution-state path when it is meant
    to drive long-running implementation;
  - an existing execution-state document points to the plan as its source
    document, or records a direct source-doc execution waiver when it points to
    a source doc directly;
  - dangling sibling links are reported as validation errors.
- Add a nils-cli deterministic audit command for durable coordination artifacts:
  - classify candidates as `delete`, `keep`, `rehome`, or `manual-review`;
  - emit stable text and JSON output;
  - explain the evidence behind each classification;
  - avoid deleting or moving files.
- Update agent-kit plan workflow skills and tests to use the helper when
  available while preserving the current manual audit workflow as fallback.

## Non-Scope

- Do not implement the helper or CLI changes during the planning step.
- Do not delete any durable artifacts as part of this plan creation.
- Do not add a new agent-kit cleanup script if `nils-cli` can own the
  deterministic primitive.
- Do not make `docs-plan-cleanup` decide ambiguous policy questions. It remains
  the batch executor after audit intent is known.
- Do not require every plan to have an execution-state document before work has
  started.
- Do not release `nils-cli` or update Homebrew adoption until implementation and
  validation are complete.

## Implementation Boundaries

### Bundle Validation

The validation should operate after existing `validate` checks succeed. It
should use conservative sibling-bundle heuristics under `docs/plans/<slug>/`:
`<slug>-discussion-source.md`, `<slug>-review-source.md`,
`<slug>-plan.md`, and `<slug>-execution-state.md`.

An execution state that points directly to a source doc is valid only when it
contains an explicit direct source-doc execution waiver. The exact field can be
a stable line such as:

```md
- Direct source-doc execution waiver: <reason or "not applicable">
```

If the execution state points to the plan, no direct waiver is required.

### Deterministic Audit Helper

The audit helper should inspect candidate paths, status markers, sibling bundle
state, references, and retained-evidence locations. It should not attempt to
interpret raw evidence contents or prove historical business decisions. When
completion, ownership, or retention policy is unclear, the correct output is
`manual-review`.

Suggested initial output shape:

```json
{
  "schema_version": "plan-tooling.artifact-audit.v1",
  "ok": true,
  "root": ".",
  "items": [
    {
      "path": "docs/plans/example/example-plan.md",
      "classification": "delete",
      "reason": "completed sibling bundle with no maintained references",
      "evidence": ["execution-state status complete", "no external references"]
    }
  ]
}
```

### Agent-Kit Adoption

Agent-kit skills should treat nils-cli output as an audit aid, not as final
authority. `durable-artifact-cleanup` remains responsible for user-facing
policy, deletion approval, and final reporting. `docs-plan-cleanup` remains
responsible for broad `docs/plans/` execution once classification is known.

## Requirements

- `plan-tooling validate` detects broken links among a source doc, plan, and
  execution state in a plan-created bundle.
- Direct source-doc execution has a deterministic validation rule: if an
  execution-state document points to a source doc instead of a plan, a waiver
  line must exist.
- The audit helper provides stable classifications and reasons without making
  filesystem changes.
- Agent-kit cleanup guidance explains when to trust the helper, when to fall
  back to manual review, and when to hand execution to `docs-plan-cleanup`.
- Both repositories have focused tests and docs updates for the new contracts.

## Acceptance Criteria

- A nils-cli implementation can fail `plan-tooling validate` for:
  - missing source doc referenced by `Read First`;
  - source doc recommending a different plan;
  - execution state pointing to a source doc without a direct-execution waiver;
  - execution state pointing to a plan that does not match the bundle plan.
- A nils-cli implementation can pass `plan-tooling validate` for:
  - a not-yet-started bundle with source doc and plan but no execution state;
  - an in-progress bundle where execution state points to the plan;
  - a bounded direct source-doc execution with an explicit waiver.
- A nils-cli audit command can emit text and JSON reports with only
  `delete`, `keep`, `rehome`, and `manual-review` classifications.
- Agent-kit docs and tests describe the normalized classification names and the
  helper/fallback boundary.

## Validation Plan

Recommended nils-cli commands:

```bash
cargo test -p nils-plan-tooling validate
cargo test -p nils-plan-tooling artifact_audit
zsh -f tests/zsh/completion.test.zsh
zsh -n completions/zsh/_plan-tooling
bash -n completions/bash/plan-tooling
NILS_CLI_TEST_RUNNER=nextest bash scripts/ci/nils-cli-checks-entrypoint.sh
```

Recommended agent-kit commands:

```bash
scripts/check.sh --docs
scripts/check.sh --markdown
scripts/check.sh --tests -- -k 'plan_workflow or durable_artifact_cleanup or docs_plan_cleanup'
scripts/check.sh --all
```

## Risks And Guardrails

- Do not turn the helper into an auto-delete tool. The risk is removing the only
  durable acceptance or decision record.
- Do not force execution-state creation before execution starts. Validate
  existing state when present, and validate the recommended path in source docs.
- Do not let agent-kit duplicate nils-cli parsing logic. Agent-kit should call
  the helper or keep human-readable fallback guidance.
- Do not let `manual-review` become a failure. It is the expected conservative
  classification for ambiguous policy or incomplete evidence.
- Do not overload `docs-plan-cleanup` with policy classification.

## Execution

- Recommended next artifact:
  `docs/plans/plan-source-artifact-audit/plan-source-artifact-audit-plan.md`
- Recommended execution-state path:
  `docs/plans/plan-source-artifact-audit/plan-source-artifact-audit-execution-state.md`
- Current execution status: planning only.

## Retention Intent

This document is temporary implementation source material. After the cross-repo
implementation lands, promote durable contract text into agent-kit skills,
`crates/plan-tooling` docs, tests, and release notes. Then this plan-source
bundle can be audited by the normal cleanup flow.

## Open Questions

- Should `artifact-audit` remain a `plan-tooling` subcommand after the first
  implementation, or should broader usage move it into
  `agent-workflow-primitives`?
- Should bundle validation expose a future `--bundle` flag, or remain part of
  default `validate` with conservative activation?
- Should the direct source-doc execution waiver line be added to the
  `execute-from-plan` execution-state template immediately, or only when direct
  execution is used?

## Read-First References

- `skills/workflows/plan/durable-artifact-cleanup/SKILL.md`
- `skills/workflows/plan/docs-plan-cleanup/SKILL.md`
- `skills/workflows/plan/execute-from-plan/SKILL.md`
- `skills/workflows/plan/create-plan/SKILL.md`
- `skills/workflows/plan/README.md`
- `../../Project/sympoies/nils-cli/crates/plan-tooling/src/validate.rs`
- `../../Project/sympoies/nils-cli/crates/plan-tooling/README.md`
- `../../Project/sympoies/nils-cli/crates/agent-workflow-primitives/README.md`

## Recommended Next Artifact

Use `create-plan` on this source document before implementation starts.
