@ikon85/agent-workflow-kit 0.43.0 → 0.44.0

package/src/consumer-migrations.json

@@ -1,19 +1,4 @@
 {
   "schemaVersion": 1,
-  "migrations": [
-    {
-      "id": "wrapup-landing-artifact-policy",
-      "requiredFrom": "0.38.0",
-      "title": "Explicit landing-artifact policy",
-      "workflow": "setup-workflow",
-      "decision": "wrapup.landingGeneratedArtifactPatterns",
-      "detect": {
-        "type": "json-key",
-        "path": "docs/agents/workflow-capabilities.json",
-        "key": ["wrapup", "landingGeneratedArtifactPatterns"]
-      },
-      "consequence": "wrapup-land fails closed before landing until the decision is committed.",
-      "remediation": "Run setup-workflow, review the wrapup.landingGeneratedArtifactPatterns decision it writes into docs/agents/workflow-capabilities.json, and commit that profile change. kit-update never chooses cleanup patterns for you."
-    }
-  ]
+  "migrations": []
 }

package/src/lib/bundle.mjs

@@ -144,7 +144,7 @@ export const HELPER_FILES = [
   { path: 'scripts/worktree-lifecycle/profile.py', kind: 'script', mode: 0o644 },
   { path: 'scripts/worktree-lifecycle/setup.py', kind: 'script', mode: 0o755 },
   { path: 'scripts/worktree-lifecycle/cleanup.py', kind: 'script', mode: 0o755 },
-  { path: 'scripts/worktree-lifecycle/session.py', kind: 'script', mode: 0o755 },
+  { path: 'scripts/worktree-lifecycle/classify.py', kind: 'script', mode: 0o644 },
   { path: 'scripts/worktree-lifecycle/capabilities.json', kind: 'doc', mode: 0o644 },
   { path: 'scripts/worktree-lifecycle/README.md', kind: 'doc', mode: 0o644 },
   // Offered planning-artifact ignore rules for /setup-workflow Section A11.
@@ -232,6 +232,36 @@ export const STUB_TARGETS = [
   'docs/conventions/spec-completeness.md',
 ];
 
+/**
+ * Source paths `package.json:"files"` deliberately keeps out of the npm payload:
+ * test sources, the build-time tooling that materializes `dist-kit/`, and this
+ * repository's own maintainer documentation and project layer. None of them is
+ * an install-manifest entry and nothing resolves them from an installed kit, so
+ * a removal here narrows the publish scope rather than breaking a consumer —
+ * the release guard classifies it accordingly. Kept in sync with that `"files"`
+ * field, and asserted against the real tarball by the publish-scope audit.
+ */
+export const PUBLISH_EXCLUDED_FILES = [
+  'scripts/build-kit.mjs',
+  'scripts/check-kit-staleness.mjs',
+  'scripts/grill-census-wiring-guard.mjs',
+  'scripts/portability_profile_scan.py',
+  'docs/agents/board-sync.md',
+  'docs/agents/code-review.md',
+  'docs/agents/workflow-capabilities.json',
+];
+
+const PUBLISH_EXCLUDED_PATTERNS = [
+  /\.test\.mjs$/,
+  /(^|\/)test_[^/]+\.py$/,
+  /^scripts\/codex-exec-scenarios\//,
+  /^scripts\/lib\//,
+  /^docs\/(adr|research)\//,
+];
+
+export const isPublishExcluded = (path) => PUBLISH_EXCLUDED_FILES.includes(path)
+  || PUBLISH_EXCLUDED_PATTERNS.some((pattern) => pattern.test(path));
+
 const SURFACE_DIR = { claude: '.claude/skills', codex: '.agents/skills' };
 
 /** Skills with publish:true, each with the surfaces it installs into. */

package/docs/adr/0001-consumer-divergence-policy.md

@@ -1,53 +0,0 @@
-# Consumer divergence policy: clean shipped files, owned exceptions, upstream route as a question
-
-Status: accepted (2026-07-18, issue #130)
-
-Partially superseded by ADR-0003: consumer ownership remains valid for genuine
-project files, but no longer applies to Kit Core or to mixed core/extension
-registries.
-
-Since the consumer-source cutover the kit is SSOT for shipped files, but
-consumers keep learning: edits made directly on a shipped file in a consumer
-silently fork it, and every subsequent `kit-update` reports a permanent
-conflict (observed: 6 recurring conflicts in testreporter on 0.27.1).
-
-We decided on a three-part policy:
-
-1. **Clean shipped files.** A kit-shipped file in a consumer carries no
-   project-specific content — including no project issue references in
-   comments. Generic improvements are ported upstream (reference-free,
-   English) and return via `kit-update`; project-specific needs live in
-   consumer-native files or consumer-owned paths.
-2. **Consumer-owned paths as the marked exception.** A consumer may claim a
-   genuinely forking file via `own <path>` (manifest `origin: 'consumer'`).
-   The reconciler then skips it entirely: no overwrite, no conflict report, no
-   deletion prompt. The cost — forgoing all future kit improvements to that
-   file — is deliberate and made visible on demand via `diff --owned`, never
-   as warning noise in normal updates.
-3. **Upstream route as a question.** When a shipped file is about to be
-   edited in a consumer (retro finding or direct edit), the shipped rule asks
-   the user whether the change should go upstream as a kit issue
-   (`gh issue create --repo iKon85/agent-workflow-kit`, lightweight: title +
-   short body). It never assumes the user is the kit maintainer and never
-   files automatically.
-
-## Considered options
-
-- **`own` for mixed scripts too** (e.g. `scripts/board-sync.py` with both
-  generic timeout fixes and project issue-reference comments): rejected —
-  owning the kit's most active script means no upstream fix ever reaches it
-  again.
-- **Accepting perpetual conflicts**: rejected — that is exactly the noise
-  this policy removes; conflict reports must stay meaningful.
-- **Routing rule in the maintainer's global config or a standalone
-  convention doc**: rejected — the rule must ship with the kit (retro skill,
-  kit-update skill, enforcement hook) so it reaches every consumer,
-  versioned, including consumers not run by the maintainer.
-
-## Consequences
-
-- Consumers lose the habit of annotating shipped scripts with their own
-  issue numbers; provenance for shipped files lives in the kit's history.
-- The reconciler gains an `own`/`disown` surface and a `consumerOwned`
-  report bucket; owned files fall permanently behind the kit unless
-  explicitly disowned after a peek.

package/docs/adr/0002-capability-gated-orchestration.md

@@ -1,70 +0,0 @@
-# Capability-gated orchestration: scripted-workflow / native-subagents / direct, fail-closed, no emulation
-
-Status: accepted (2026-07-22, issue #167)
-
-`orchestrate-wave` fans out recon and building across agents. The mechanic that
-performs that fan-out is not the same on every host: one host exposes a scripted
-workflow runtime, another exposes native subagent spawn/wait primitives, a third
-exposes neither. The skill ships from one body for both surfaces, so the mechanic
-cannot be baked into the prose — and a wrong guess is expensive, because a wave
-that half-dispatches leaves worktrees and branches behind.
-
-We decided to select the mechanic from **proven, host-supplied capability
-evidence**, never from a surface name and never from the model's own belief
-about what it can call.
-
-1. **A capability matrix over normalized tool entries.** The host supplies an
-   inventory; `capabilityAdapter.claude` / `.codex` only normalize what was
-   handed to them and perform no ambient discovery. Each entry carries
-   `callable`, `permitted`, a schema, and `capabilities: string[] | "unknown"`.
-   `classifyCapabilities` returns exactly one of three paths, and
-   `selectOrchestrationReference` returns one discriminated target: a reference
-   path for A and B, the inline marker for C.
-2. **Fail closed, A → B → C.** Missing or `unknown` evidence never proves a
-   capability. Path A additionally requires the *literal* tool name plus every
-   named primitive individually proven; Path B requires proven spawn, wait, and
-   aggregate plus effective concurrency and thread capacity ≥2. Anything short
-   of that degrades to Path C — direct, serial, in the main thread — which is
-   always available.
-3. **Never emulate a missing primitive.** A host without a scripted workflow
-   runtime does not get a hand-rolled imitation of one. The degraded path is a
-   different, simpler recipe, not the same recipe with the primitive faked.
-4. **The report contract is path-independent.** Every path produces the same
-   schema-valid recon and builder reports (`src/lib/reportValidator.mjs`, mirrored
-   in `references/report-contracts.md`), and every path crosses the same
-   main-thread boundary: schema validation, then `reconcileReconReports`, then
-   `semanticVerify` on builder reports. A subagent's own PASS is a hypothesis.
-5. **Progressive disclosure.** `SKILL.md` carries only the selector, the
-   invariants, Path C, and pointers; each path's recipe lives in `references/`
-   and is loaded only when selected.
-
-## Considered options
-
-- **Route by surface name** (Claude → workflow, Codex → subagents): rejected —
-  it is a claim, not evidence. A verify spike against codex-cli 0.144.6 found
-  native spawn and wait callable and concurrency ≥2, yet the host exposed tool
-  entries with only a name and a description: no schema, no callable/permitted
-  flags, no thread capacity. Name-based routing would have selected Path B on a
-  host that cannot prove it.
-- **Emulate the missing primitive** (hand-rolled fan-out where no workflow
-  runtime exists): rejected — it reproduces the failure modes the runtime exists
-  to prevent (run identity, resume-exactly-once, runtime output validation)
-  without any of its guarantees, and it fails at the worst moment, mid-wave.
-- **Fail open on unknown evidence** (assume a capability when the host is
-  silent): rejected — the cost asymmetry is severe. A false Path C is slower; a
-  false Path A or B strands a partially dispatched wave.
-- **One monolithic SKILL.md carrying all three recipes**: rejected — every
-  session would pay for two recipes it will never run.
-
-## Consequences
-
-- The current Codex host selects Path C. `references/dispatch-subagents.md` is
-  written and tested but **dormant** until a host supplies the complete
-  normalized inventory; that dormancy is pinned from both sides by tests.
-- Adding a path means adding evidence requirements and a reference, not
-  branching the skill body.
-- Hosts that improve their inventory reporting gain a faster path with no skill
-  change — the selector picks it up as soon as the evidence arrives.
-- The B1 fan-out shape (`spawn_agents_on_csv` plus a host-enforced per-agent
-  `output_schema`) stays out of scope until its own version-pinned verify spike
-  returns a positive verdict.

package/docs/adr/0003-kit-core-and-project-extension-lifecycle.md

@@ -1,63 +0,0 @@
-# Kit Core and project extensions have separate identities
-
-Status: accepted (2026-07-22, issues #190, #194, #196, #197)
-
-The original divergence policy allowed any shipped path to become
-consumer-owned. That is safe for a genuinely project-specific file, but not for
-a protocol authority such as the skill/readiness registry: once a consumer
-owns that mixed file, new Kit declarations stop arriving while local additions
-and stale Kit declarations remain indistinguishable. A real consumer exhibited
-exactly this state: the installed readiness harness was current while its owned
-registry had no readiness capabilities or declarations.
-
-We decided to model four explicit lifecycle states instead of treating every
-local difference as file ownership:
-
-1. **Kit Core** remains upstream-owned under the Kit's canonical identity. A
-   consumer cannot permanently own it under that same identity.
-2. **Project extensions** live on separate consumer-owned surfaces. Every
-   shipped skill may load its optional `docs/agents/skills/<skill>.md`; local
-   skill identities live in a separate local registry. Neither surface changes
-   the corresponding Kit Core.
-3. A **Contribution bridge** may temporarily retain a registered local Core
-   experiment. It must resolve into a project extension, a generalized upstream
-   contribution that returns in a release, or an explicit fork.
-4. An **Explicit fork** has its own identity, version, and update line. Semantic
-   divergence cannot masquerade indefinitely as the canonical Kit skill.
-
-An update composes and validates the complete protocol group in an isolated,
-manifest-derived staged candidate. It never infers an ownership decision from
-`--yes`: an unclassified collision blocks unchanged until a user classifies it.
-Existing mixed states migrate semantically, preserving local identities and
-project metadata on their new surfaces; an ambiguous semantic change blocks
-instead of being overwritten or frozen silently.
-
-The upstream route is capability-based, not maintainer-specific. At the moment
-of contribution, repository permissions and an optional machine-local upstream
-checkout determine whether the approved route can use a direct pull request, a
-fork, or an issue. No consumer asks who the user is, and no telemetry reports
-local edits automatically.
-
-## Considered options
-
-- **Keep arbitrary consumer-owned shipped paths:** rejected because a protocol
-  authority then stops receiving schema and behavior evolution under the same
-  identity.
-- **Add more merge rules to the mixed registry:** rejected because local skills,
-  project annotations, readiness declarations, and upstream skill definitions
-  have different ownership and lifecycle semantics.
-- **Overwrite Core and discard local changes:** rejected because it loses valid
-  project behavior and can destroy unregistered work.
-- **Special-case the maintainer:** rejected because identity is irrelevant; the
-  portable distinction is whether the user has an approved route and the
-  required repository capabilities.
-
-## Consequences
-
-- ADR-0001 remains valid for genuine consumer-owned files but is narrowed for
-  Kit Core and mixed registries.
-- Core updates can advance without erasing project-specific behavior.
-- Consumers gain explicit extension, contribution, and fork lifecycles instead
-  of permanent accidental divergence.
-- Migration requires a one-time semantic classification of existing mixed
-  states and must fail closed when that classification is ambiguous.

package/docs/adr/0004-release-intent-is-a-version-tag.md

@@ -1,64 +0,0 @@
-# Release intent is an explicit version tag
-
-Status: accepted (2026-07-22, issue #204)
-
-Clarified 2026-07-25 by issue #239: an explicit AFK end-to-end mandate may
-authorize deterministic reversible release preparation, but never the
-publication tag itself.
-
-Amended 2026-07-25 by issue #257: the confirmed Semver authorizes the whole
-release, through tag and publish. The separation of integration and publication
-below is unchanged — merging still cannot publish, and only an annotated tag
-records release intent — but that intent no longer waits for a second human
-confirmation. The maintainer chooses the version once; the agent then merges,
-tags, and monitors to `released`. The second gate had proven worse than no gate:
-it left prepared versions sitting in `awaiting-tag` until someone returned,
-which is how 0.34.2 was skipped and buried under 0.34.3 (#243). Safety stays in
-the gates that run regardless of who is watching — guard, staleness, suite,
-pack, and the workflow's own tag/version/ancestry validation.
-
-The release workflow currently publishes whenever a merge to `main` changes
-`package.json`. That keeps the canonical branch and npm close together, but it
-also makes an ordinary merge an irreversible public action whose consequence is
-not visible in the merge affordance. A failed post-publish readback can further
-make the run red after npm has already accepted the version.
-
-We decided that integration and publication are separate transitions:
-
-1. Merging a prepared version into `main` integrates it but does not publish it.
-2. A matching annotated `v<version>` tag on that `main` commit records Release
-   intent and starts the normal publish workflow.
-3. The workflow validates tag, package version, canonical-branch ancestry,
-   artifact integrity, and tests before publishing.
-4. A manual dispatch is a recovery/reconciliation route for one explicit tag,
-   never the ordinary release trigger.
-5. Publication completes only when npm and the GitHub release are both visible
-   and match the local version, manifest, and tarball. Eventual-consistency
-   readbacks use bounded retry and preserve an externally reconstructable state.
-
-## Considered options
-
-- **Merge-triggered publishing:** rejected because merge acceptance and
-  irreversible publication remain one implicit action.
-- **Manual dispatch as the normal route:** rejected because the release identity
-  is easier to forget and less durable than a version tag.
-- **PR label or commit marker:** rejected because it introduces hidden release
-  semantics without giving the publication a first-class Git identity.
-- **Environment approval on the merge-triggered workflow:** rejected as the
-  primary contract because it adds a UI gate but still does not represent the
-  approved version as a durable release object.
-
-## Consequences
-
-- A prepared version exists on `main` in an `awaiting-tag` state only for as
-  long as the agent needs to tag it — not until a human returns (amended by
-  #257).
-- The authorizing act is the confirmed Semver. An explicit AFK Wave/Program
-  mandate that names release preparation carries the same weight, and either
-  route reaches through tag and publish for that one target. A narrower
-  build-only or single-action request never becomes this authority.
-- A single-Wave mandate does not authorize the next Program Wave. A later
-  explicit whole-Program mandate does authorize all planned Waves and remains in
-  force across their boundaries.
-- Reruns reconcile the same tag and never infer that a red workflow means
-  nothing was published.

package/docs/adr/0005-to-issues-is-the-planning-facade.md

@@ -1,42 +0,0 @@
-# to-issues is the single planning facade
-
-Status: accepted (2026-07-22, issue #197)
-
-The planning workflow exposes two mechanisms after `to-prd`: Feature PRDs are
-decomposed by `to-issues`, while Program PRDs are unfolded by a separately
-invoked `to-waves` skill which later calls `to-issues` for each wave. This makes
-the user identify an internal planning altitude even though the PRD already
-carries an explicit, durable identity that can select the correct mechanism.
-
-We decided that `to-issues` is the single user-facing Planning facade:
-
-1. A Feature PRD selects the existing atomic/promote mechanism.
-2. A Program PRD selects the existing program-graph engine currently owned by
-   `to-waves`, including its complete preview, validation, publication,
-   per-wave maturation, and execute-ready audits.
-3. Dispatch uses only explicit PRD identity (`prd: program` or its canonical
-   program type), never size heuristics or model judgment.
-4. The selected mode is reported visibly before mutation. Program mode retains
-   its full preview approval gate.
-5. `to-waves` remains an independently testable internal mechanism and may keep
-   a compatibility entrypoint, but routers and normal documentation always send
-   the user from `to-prd` to `to-issues`.
-
-## Considered options
-
-- **Keep two public next commands:** rejected because it leaks internal
-  decomposition mechanics and makes users repeat an altitude decision already
-  encoded in the PRD.
-- **Infer the mode from plan size or prose:** rejected because hidden heuristics
-  make the same command unpredictable and can publish the wrong board shape.
-- **Merge all program code physically into `to-issues`:** rejected because the
-  program graph is a coherent deep module with valuable separate tests; only
-  its public routing belongs behind the facade.
-
-## Consequences
-
-- The normal user path is always `grill → to-prd → to-issues`.
-- Feature and Program behavior remain distinguishable in audit output without
-  requiring the user to select their implementation skill.
-- Router, overview, skill prose, mirrors, and contract tests must agree on the
-  one-entry contract.

package/docs/adr/0006-routing-knowledge-access-and-policy-are-separate.md

@@ -1,95 +0,0 @@
-# Routing knowledge, access, and policy are separate
-
-Status: accepted (2026-07-22, Program #197) — the optimization-dial clause is
-superseded by
-[ADR-0010](./0010-model-roster-replaces-the-optimization-dial.md)
-(items 3 and the "Model preferences and optimization overrides" sentence below;
-everything else stands)
-
-Planning cannot safely persist a concrete recommended model. Provider catalogs
-change, model names age, effort behavior differs by model, agent surfaces expose
-different controls, and a surface may reach another provider through a plugin
-or CLI transport. A recommendation that is correct in one session can therefore
-be nonexistent, unreachable, or unenforceable in the session that implements
-the work.
-
-We decided to keep three identities separate:
-
-1. The Kit-maintained **Evidence catalog** contains all known provider models
-   and observations, whether or not the active surface can use them. Each
-   decision-grade observation retains the complete configuration identity:
-   model, effort, harness, workload, source, benchmark version, uncertainty,
-   freshness, and cost.
-2. The user-local **Access graph** records the native and cross-provider paths
-   available from each agent surface. Claude Code and Codex attest only their
-   own runtime capabilities. A detected transport is not automatically approved,
-   and neither surface claims another surface's unverified capabilities.
-3. The user-local **Routing policy** records allowed surfaces and transports,
-   switching autonomy, optimization goals, and optional advanced overrides.
-   Personal choices do not alter catalog facts.
-
-Durable plans and issues contain only a provider-neutral **Routing intent**.
-At execution time a resolver compares all evidence-backed candidates, filters
-them through the Access graph and Routing policy, and produces a one-execution
-**Route decision**. It reports the best overall route separately from the best
-currently executable route. An unreachable preference follows the user's
-explicit handoff, fallback, or block policy.
-
-Every surface adapter declares how independently it can control model and
-effort: per spawn, through a named agent definition, through a session default,
-or not at all. Environment precedence is part of the capability proof. An AFK
-subagent requires enforced model and effort selection and emits a **Dispatch
-receipt** containing the requested and applied route, enforcement method, and
-policy/evidence revisions. Silent inheritance and unverified degradation are
-not valid AFK routes.
-
-Setup keeps the technical model behind a simple user decision. It presents a
-registry-driven list of familiar agent surfaces, preselects detected entries,
-and asks whether the Kit may switch automatically, ask before switching, or use
-only the current surface. Adapters establish providers, transports, model
-selectors, and effort controls. Model preferences and optimization overrides
-remain optional advanced settings.
-
-An existing installation without a routing profile receives this choice once
-through setup or the first compatible Kit update. Later updates perform a
-read-only preflight and ask again only when the profile is missing, invalid,
-materially stale, references a removed route, or a newly detected surface makes
-a meaningful choice available. Installing Kit mechanics and changing personal
-policy are separate transactions; unattended update never invents a decision.
-
-BenchLM may populate discovery, catalog, pricing, freshness, coverage, and
-corroboration signals. Its aggregate scores are not decision-grade routing
-observations because effort and harness identity may be collapsed and missing
-evidence may be estimated. DeepSWE, Artificial Analysis, OpenHands, Arena, and
-other benchmark-owner artifacts remain authoritative for the claims they
-actually measure. Local experience may calibrate policy but does not rewrite
-public evidence.
-
-## Considered options
-
-- **Persist a concrete model and effort in every issue:** rejected because the
-  recommendation ages and may not be executable on the implementing surface.
-- **Maintain separate Claude and Codex routing tables:** rejected because it
-  duplicates evidence, hides cross-provider routes, and lets the two surfaces
-  drift.
-- **Filter the shared table during setup:** rejected because current access is
-  a user/runtime fact, not a limit on routing knowledge.
-- **Ask users to describe transports and enforcement capabilities:** rejected
-  because these are adapter facts most users cannot answer reliably.
-- **Route directly from a composite leaderboard:** rejected because benchmark,
-  harness, effort, uncertainty, and workload boundaries would be lost.
-- **Re-run the routing interview on every Kit update:** rejected because a valid
-  user-owned profile should remain stable until a material choice changes.
-
-## Consequences
-
-- Model/provider churn updates the catalog and resolver without rewriting
-  durable issues.
-- Both Claude Code and Codex read one local policy while proving their own
-  execution capabilities independently.
-- Cross-provider dispatch is expressible without pretending that every surface
-  can reach every model.
-- The Kit must maintain source adapters, schema migration, capability probes,
-  last-known-good evidence, and dispatch receipts.
-- Different machines do not share personal routing state unless the user later
-  chooses an explicit export or private synchronization mechanism.

package/docs/adr/0007-session-teardown-requires-provenance-bound-ownership.md

@@ -1,88 +0,0 @@
-# Session teardown requires provenance-bound ownership
-
-Status: superseded by [ADR-0009](./0009-teardown-authority-is-stateless-repository-classification.md) (2026-07-27, #320)
-
-Long agent sessions create branches, linked worktrees, setup outputs, and
-landing-time build artifacts. The desired end state is that every
-provenance-captured target created by that session can be removed, including
-branches whose changes reached
-canonical `main` through patch-equivalent commits rather than ancestry.
-
-Repository state alone cannot identify that ownership safely. A foreign branch
-can have the same name or patch, a user file can match a generated-artifact
-pattern, and a path can be replaced between assessment and deletion. Retrying
-after a crash adds a time dimension: a fresh snapshot cannot distinguish an
-earlier generator output from a file created by the user between attempts.
-
-We decided that teardown authority must come from **Teardown provenance**, not
-from present-day similarity:
-
-1. A session records intent before creation, but receives cleanup authority only
-   through an atomic **Ownership proof**. Branch and proof ref are acquired in
-   one Git transaction bound to the active wave claim.
-2. Setup, session work, and landing are separate provenance boundaries. Setup
-   and session cleanup use the worktree-creation baseline; landing cleanup uses
-   a persisted landing-attempt boundary and freezes the exact outputs of its
-   generator-capable step.
-3. Paths and patterns select candidates but never prove identity. Cleanup binds
-   regular files and worktree roots to no-follow object evidence and revalidates
-   that evidence immediately before mutation.
-4. The **Lifecycle receipt** is a durably replaced state-transition journal.
-   Prepared Git ref transactions close the worktree-removal race, and committed
-   intermediate states make known outcomes resumable. An external SIGKILL may
-   still leave Git's own lock files requiring operator recovery.
-5. Lost evidence is not reconstructed from coincidence. An interrupted landing
-   attempt without frozen outputs can be archived without claiming or deleting
-   its files, after which the ambiguous files must be classified before a new
-   attempt proceeds.
-
-## Considered options
-
-- **Delete branches merged by ancestry:** rejected because squash,
-  cherry-pick, and patch-equivalent integration leave session-owned branch refs
-  outside ancestry.
-- **Treat a receipt row as ownership:** rejected because another process can
-  create the named branch or worktree after the absence check but before the
-  attempted creation.
-- **Authorize files by ignored path or generator pattern:** rejected because a
-  consumer file can occupy the same path before landing or replace an assessed
-  output afterward.
-- **Take a fresh landing snapshot on every retry:** rejected because it protects
-  prior generator outputs as if they predated landing, while a persistent start
-  snapshot alone incorrectly claims every later matching user file.
-- **Force-remove apparently clean targets:** rejected because force bypasses the
-  repository and filesystem evidence that distinguishes owned work from foreign
-  work.
-- **Guess ownership after an unjournaled crash window:** rejected because safe
-  cleanup and guaranteed automatic liveness cannot both be recovered after the
-  distinguishing evidence is lost.
-
-## Consequences
-
-- A completed session can remove its exact worktrees, branches, proof refs, and
-  provenance-captured generated artifacts without hiding history or sweeping
-  unrelated repository state.
-- Foreign branches, worktrees, replacement symlinks, replacements, late writes,
-  and pre-landing consumer files are hard stops or remain outside cleanup
-  authority. Setup recovery may remove only a symlink whose exact no-follow
-  identity it captured as setup-created.
-- Exact unchanged frozen evidence is deterministically resumable. Started or
-  drifted frozen attempts can be explicitly relinquished by archiving only the
-  receipt; every current file then remains protected and must be classified
-  before another attempt.
-- Provenance-less legacy worktrees receive only a conservative baseline after
-  exact registration, no-follow root, attached branch, and clean tracked/index
-  checks. Setup reuse defers backfill while tracked work or current
-  landing-generated blockers remain. Landing classifies those blockers before
-  writing evidence; after they are moved, all remaining current ignored and
-  untracked files become protected. Corrupt evidence and active attempts are
-  never backfilled.
-- Before merge, a committed worktree policy may nominate only exact,
-  identity-bound cleanup candidates; it authorizes no deletion. After merge,
-  the profile is reloaded directly from canonical `origin/main` and must match
-  both the candidate and attempt-bound policy digest before any mutation.
-  Generator evidence is also reauthorized path-by-path against that canonical
-  policy. Missing policy, an unmerged widening, or branch/canonical drift
-  preserves every file.
-- The lifecycle implementation is necessarily a small transaction protocol,
-  with more states and race tests than a path-based cleanup script.

package/docs/adr/0008-planning-ignore-rules-are-offered-never-installed.md

@@ -1,84 +0,0 @@
-# Planning ignore rules are offered, never installed
-
-Status: accepted (2026-07-26, #255)
-
-The shipped planning skills write `PLAN.md`, `PLAN-REVIEW-LOG.md`, and
-`ANNAHMEN.md` into a session worktree, and several of them told the agent those
-files were gitignored and lived on disk only. In a consumer repository that was
-simply untrue: `init` and `update` never touch `.gitignore`, and no installed
-file adds the rules. The consequence mirrors what this repository fixed for
-itself in #254 — every planning worktree reports a permanently dirty tree, the
-shipped Worktree Lifecycle cleanup refuses to remove it, genuinely unlanded work
-becomes indistinguishable from plan scratch, and a consumer who never notices
-can commit a plan doc into their history that the prose implied could not be
-committed.
-
-The constraint is the consumer contract. Consumer-owned files are written once
-and never overwritten by ordinary reconciliation, and `.gitignore` is stronger
-still: the kit does not own it at all and has no manifest entry, no baseline
-hash, and no three-way reconcile for it. A file the kit cannot reconcile is a
-file the kit must not write uninvited.
-
-We decided to close the gap from both ends:
-
-1. **`/setup-workflow` offers the rules as an explicit, previewed, approved
-   step.** Section A11 previews with
-   `python3 scripts/worktree-lifecycle/ignore_seed.py preview`, shows the exact
-   lines verbatim, asks, and only an approval runs `apply`. The write is
-   append-only inside one idempotent marker block. It never rewrites, reorders,
-   or removes an existing line; a re-run is a byte-identical no-op; a decline
-   changes nothing; a repository that already ignores the artefacts reports
-   `nothing to do`; and a marker block the consumer has since edited is
-   `blocked`, never repaired. Nothing in `init` or `update` can reach the
-   seeder.
-2. **Shipped skill prose states the assumption instead of asserting the fact.**
-   A skill now says these artefacts are *expected* to be ignored and names
-   `/setup-workflow` as the thing that can make it true, rather than claiming
-   the kit already did. The claim is pinned by a census lint over both skill
-   trees, so the assertion cannot silently return.
-
-This is the same shape the kit shipped for the GitHub-Projects board in 0.39.0
-(#24): offer, preview, obtain an explicit yes, never write an outward or
-consumer-owned artefact silently.
-
-Which artefacts the offer covers is a kit-owned fact — the kit knows which files
-its own skills write — declared once in
-`scripts/worktree-lifecycle/plan-artifacts.json`. That is deliberately not the
-consumer's `worktreeLifecycle.scratchPatterns`, which is derived *from* the
-consumer's ignored planning artefacts and would otherwise be circular: before
-this decision there was nothing ignored for it to be derived from.
-
-## Considered options
-
-- **Append-only seed at `init`:** rejected. It respects append-only mechanics
-  but still writes a file the kit does not own, uninvited, on first install —
-  the one action the consumer contract exists to prevent.
-- **Readiness capability only:** rejected. Reporting the gap and letting the
-  affected skills degrade honestly leaves the friction in place and fixes
-  nothing for the consumer who wants the promise to hold.
-- **Prose-only fix:** rejected as insufficient on its own. It removes the false
-  claim but leaves every consumer with dirty planning worktrees and a cleanup
-  that refuses to run. It is kept as one half of the decision, not the whole.
-- **Deriving the rules from `worktreeLifecycle.scratchPatterns`:** rejected as
-  circular, and because that array is consumer-owned deletion-adjacent policy
-  that Core never supplies defaults for.
-- **Untracking an already-committed artefact:** rejected. An ignore rule cannot
-  untrack a tracked file, and running `git rm` on consumer history is far past
-  what a setup step may do. The seeder reports the tracked artefact and stops.
-
-## Consequences
-
-- A consumer who runs `/setup-workflow` and approves gets the guarantee the
-  skills describe; a consumer who declines keeps a byte-identical `.gitignore`
-  and loses nothing but the convenience.
-- The never-overwrite contract is untouched: the only write is an append behind
-  an explicit yes, and `update` reconciliation still never touches
-  `.gitignore`.
-- The offer reaches only consumers who run setup again. That is accepted: it is
-  the price of not writing an unowned file, and re-running `/setup-workflow` is
-  already the documented way to pick up a new project-layer capability.
-- After an approval, `scratchPatterns` derivation finally has real ignored
-  planning artefacts to read, so the Worktree Lifecycle scratch classification
-  stops being vacuous in a fresh consumer repository.
-- A consumer who edits or deletes the marker block owns the outcome; the kit
-  reports and stops rather than restoring its own block.