@ikon85/agent-workflow-kit 0.43.0 → 0.44.0

package/scripts/profile_globs.py

@@ -1,10 +1,12 @@
 #!/usr/bin/env python3
 """One repository-relative glob dialect for every consumer workflow profile.
 
-Workflow Advisories and Worktree Lifecycle both select repository-relative
-paths from consumer-owned profile globs. They share this single matcher so the
-same pattern can never select one set of paths for an advisory and a different
-set for a cleanup decision.
+Workflow Advisories selects repository-relative paths from consumer-owned
+profile globs, and this is the single matcher it uses, so a pattern can never
+select one set of paths on one advisory surface and a different set on another.
+No Worktree Lifecycle decision reads a glob at all: deletion policy has exactly
+one configuration surface, the ignore mechanism, so no consumer pattern here
+carries deletion authority.
 
 Dialect
 -------
@@ -24,9 +26,9 @@ Run this module to review an installed profile before trusting it:
     python3 scripts/profile_globs.py [docs/agents/workflow-capabilities.json]
 
 It names every pattern whose match set narrows or widens against the legacy
-matcher of its own capability, marks the keys that carry deletion authority,
-and never edits the profile. Exit code 0 means nothing changed meaning, 1 means
-at least one pattern needs review, 2 means the profile could not be read.
+matcher and never edits the profile. Exit code 0 means nothing changed meaning,
+1 means at least one pattern needs review, 2 means the profile could not be
+read.
 """
 
 from __future__ import annotations
@@ -94,7 +96,6 @@ class PatternMigration:
 class ProfileGlobFinding:
     location: str
     pattern: str
-    deletion_authority: bool
     migration: PatternMigration
 
 
@@ -232,52 +233,34 @@ def _surface_globs(advisories: dict, section: str) -> list[tuple[str, str]]:
     ]
 
 
-def _profile_globs(document: object) -> list[tuple[str, str, bool]]:
+def _profile_globs(document: object) -> list[tuple[str, str]]:
     """List every shipped consumer-profile glob call site's configured patterns."""
     if not isinstance(document, dict):
         return []
-    globs: list[tuple[str, str, bool]] = []
-    for index, pattern in _string_entries(
-        document.get("worktreeLifecycle"), "scratchPatterns",
-    ):
-        globs.append((f"worktreeLifecycle.scratchPatterns[{index}]", pattern, True))
-    for index, pattern in _string_entries(
-        document.get("wrapup"), "landingGeneratedArtifactPatterns",
-    ):
-        globs.append(
-            (f"wrapup.landingGeneratedArtifactPatterns[{index}]", pattern, True),
-        )
     advisories = document.get("workflowAdvisories")
-    if isinstance(advisories, dict):
-        for index, pattern in _string_entries(advisories.get("baseline"), "sourceGlobs"):
-            globs.append(
-                (f"workflowAdvisories.baseline.sourceGlobs[{index}]", pattern, False),
-            )
-        for section in ("preRefactor", "stopChecks"):
-            globs.extend(
-                (location, pattern, False)
-                for location, pattern in _surface_globs(advisories, section)
-            )
+    if not isinstance(advisories, dict):
+        return []
+    globs: list[tuple[str, str]] = [
+        (f"workflowAdvisories.baseline.sourceGlobs[{index}]", pattern)
+        for index, pattern in _string_entries(advisories.get("baseline"), "sourceGlobs")
+    ]
+    for section in ("preRefactor", "stopChecks"):
+        globs.extend(_surface_globs(advisories, section))
     return globs
 
 
 def scan_profile(document: object) -> tuple[ProfileGlobFinding, ...]:
     """Classify every consumer-profile glob against its own legacy matcher.
 
-    Worktree Lifecycle globs were always matched case-sensitively, while
-    Workflow Advisories globs went through the case-normalizing `fnmatch`, so
-    only the advisory keys can narrow on a case-insensitive host.
+    Every remaining glob key is a Workflow Advisories key, and those went
+    through the case-normalizing `fnmatch`, so all of them can narrow on a
+    case-insensitive host.
     """
     return tuple(
         ProfileGlobFinding(
-            location,
-            pattern,
-            deletion_authority,
-            classify_pattern(
-                pattern, case_insensitive_legacy=not deletion_authority,
-            ),
+            location, pattern, classify_pattern(pattern, case_insensitive_legacy=True),
         )
-        for location, pattern, deletion_authority in _profile_globs(document)
+        for location, pattern in _profile_globs(document)
     )
 
 
@@ -290,9 +273,8 @@ def render_report(findings: tuple[ProfileGlobFinding, ...], source: str) -> str:
         f"{len(changed)} change meaning.",
     ]
     for finding in changed:
-        authority = " [deletion authority]" if finding.deletion_authority else ""
         lines.append("")
-        lines.append(f"{finding.location}{authority}: {finding.pattern}")
+        lines.append(f"{finding.location}: {finding.pattern}")
         for effect in finding.migration.effects:
             witness = finding.migration.witnesses[effect]
             verb = "now also matches" if effect == WIDENS else "no longer matches"
@@ -301,8 +283,8 @@ def render_report(findings: tuple[ProfileGlobFinding, ...], source: str) -> str:
         lines.append("")
         lines.append(
             "Review each line above and rewrite the pattern yourself. A widened "
-            "deletion-authority pattern expands what cleanup may remove; this "
-            "check never edits the profile and never migrates a pattern for you.",
+            "pattern expands the surface an advisory selects; this check never "
+            "edits the profile and never migrates a pattern for you.",
         )
     return "\n".join(lines) + "\n"
 
@@ -331,7 +313,6 @@ def main(argv: list[str]) -> int:
                 {
                     "location": finding.location,
                     "pattern": finding.pattern,
-                    "deletionAuthority": finding.deletion_authority,
                     "effects": list(finding.migration.effects),
                     "witnesses": finding.migration.witnesses,
                 }

package/scripts/release-delta-guard.mjs

@@ -4,7 +4,7 @@ import { mkdir, mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { STUB_TARGETS } from '../src/lib/bundle.mjs';
+import { STUB_TARGETS, isPublishExcluded } from '../src/lib/bundle.mjs';
 import { sha256 } from '../src/lib/hash.mjs';
 import { buildKit } from './build-kit.mjs';
 
@@ -31,9 +31,20 @@ function mergeDeltas(...deltas) {
   ]));
 }
 
-export function recommendBump(delta, { minorRemovals = [] } = {}) {
+/**
+ * Recommend the smallest bump the delta justifies.
+ *
+ * `initialDevelopment` is Semver's major-version-zero rule: while the package
+ * is still `0.y.z` there is no stable public contract to break, so a removal
+ * that would demand a major on a released package demands a minor here. The
+ * protection that matters at 0.x survives either way — a removal can never be
+ * a patch. Callers pass the BASE version's major, so the recommendation cannot
+ * be softened by choosing the target version.
+ */
+export function recommendBump(delta, { minorRemovals = [], initialDevelopment = false } = {}) {
   const minorRemovalSet = new Set(minorRemovals);
-  if (delta.removed.some((path) => !minorRemovalSet.has(path))) return 'major';
+  const breaking = delta.removed.some((path) => !minorRemovalSet.has(path));
+  if (breaking) return initialDevelopment ? 'minor' : 'major';
   if (delta.added.length || delta.removed.length) return 'minor';
   return delta.changed.length ? 'patch' : null;
 }
@@ -81,13 +92,19 @@ export function assessRelease(input) {
       + `tag and publish it before preparing ${input.currentVersion}`,
     );
   }
-  // Project-layer stubs are seed inputs, never installed Consumer files.
-  // Removing an accidentally packed copy is additive hygiene, unless the same
-  // path also disappeared from the actual Consumer bundle.
-  const seedOnlyPackageRemovals = packageDelta.removed.filter(
-    (path) => STUB_TARGETS.includes(path) && !bundleDelta.removed.includes(path),
+  // Project-layer stubs are seed inputs, never installed Consumer files, and
+  // publish-excluded sources (tests, build tooling, maintainer docs) are never
+  // installed either. Removing an accidentally packed copy of either is
+  // additive hygiene, unless the same path also disappeared from the actual
+  // Consumer bundle.
+  const payloadOnlyRemovals = packageDelta.removed.filter(
+    (path) => (STUB_TARGETS.includes(path) || isPublishExcluded(path))
+      && !bundleDelta.removed.includes(path),
   );
-  const recommendedBump = recommendBump(delta, { minorRemovals: seedOnlyPackageRemovals });
+  const recommendedBump = recommendBump(delta, {
+    minorRemovals: payloadOnlyRemovals,
+    initialDevelopment: Number(input.baseVersion.split('.')[0]) === 0,
+  });
   const actual = bumpKind(input.baseVersion, input.currentVersion);
   const rank = { patch: 1, minor: 2, major: 3 };
   if (hasDelta(delta) && input.currentVersion !== input.baseVersion && !actual) {

package/scripts/worktree-lifecycle/README.md

@@ -13,35 +13,32 @@ they do not carry a second branch regex, worktree traversal, or failure policy.
 - `enabled`: explicit activation gate.
 - `worktreeRoot`, `branchTemplate`, `pathTemplate`, and `branchRegex`: consumer
   naming and location policy.
+- `contentBranchTemplate` (default `{type}/{slug}`): the issue-less branch a
+  session cuts when its output is durable content. It renders `{type}` and
+  `{slug}` only — a durable-content session has no issue number — and refuses
+  an `{issue}` placeholder instead of inventing one.
 - `mainBranches` and `protectedBranches`: branches guarded in the main checkout.
 - `setupEntry` and ordered `setupSteps`: the portable setup command and project
   setup sequence.
 - `riskyCommandPatterns`: commands that must target the active linked worktree.
-- `scratchPatterns`: consumer-owned glob patterns for untracked disposable
-  planning artefacts. No filename is assumed by Core.
-- `wrapup.landingGeneratedArtifactPatterns`: an explicitly reviewed
-  consumer-owned allowlist for outputs created by the landing commands. It is
-  deletion authority, so setup never derives it from `.gitignore` alone and
-  update never installs a universal default.
-
-Profile globs use one repository-relative POSIX dialect, implemented once in
-`scripts/profile_globs.py` and loaded by this core and by
-`scripts/workflow-advisories/core.py`. `*` and `?` stay inside one path
-segment; `[seq]`/`[!seq]` are per-segment character classes; `**` as a whole
-segment matches zero or more segments, so a leading `**/` also matches the
-repository root and `dir/**` also matches `dir` itself; matching is always
-case-sensitive on every host filesystem; and a pattern must match the whole
-path. For example, `**/__pycache__/**` matches both root and nested caches,
-while `dist-kit/*` does not match `dist-kit/a/b`.
-
-Because both capabilities load the same matcher, a pattern can never select one
-set of paths for an advisory and a different set for a deletion decision. Run
+
+The profile carries **structural facts only**. It declares no pattern list,
+because deletion policy has exactly one configuration surface: the ignore
+mechanism. Making a file deletable at teardown means ignoring it.
+Keys this loader does not know are ignored in silence, so a profile written for
+an older kit keeps working without warning noise.
+
+Profile globs elsewhere in the kit (Workflow Advisories) use one
+repository-relative POSIX dialect, implemented once in
+`scripts/profile_globs.py`. `*` and `?` stay inside one path segment;
+`[seq]`/`[!seq]` are per-segment character classes; `**` as a whole segment
+matches zero or more segments, so a leading `**/` also matches the repository
+root and `dir/**` also matches `dir` itself; matching is always case-sensitive
+on every host filesystem; and a pattern must match the whole path. Run
 `python3 scripts/profile_globs.py <profile.json>` to review an installed
-profile: it names every pattern whose match set narrows or widens against that
-key's legacy matcher, prints the witness path proving it, marks the keys that
-carry deletion authority, and exits 1 when anything needs review. It reads the
-profile and never rewrites a pattern, so a migration cannot silently expand
-cleanup authority.
+profile. No Worktree Lifecycle decision reads a glob: the ignore mechanism is
+the single deletion-policy surface, so a pattern can no longer widen cleanup
+authority at all.
 
 Unknown or malformed events fail open without changing repository state.
 Security-sensitive, profile-matched edits and commands fail closed only when
@@ -66,157 +63,57 @@ shipped skills write (`PLAN.md`, `PLAN-REVIEW-LOG.md`, `ANNAHMEN.md`).
 `preview` reports what an approval would append and writes nothing, and `apply`
 appends exactly one marker block. `.gitignore` is a consumer file the kit does
 not own, so only an explicit approved `/setup-workflow` step may run `apply`;
-`init` and `update` reconciliation never reach it (ADR 0008).
+`init` and `update` reconciliation never reach it.
 
 The append never rewrites, reorders, or removes an existing line. A repository
 that already ignores every artefact reports `nothing-to-do`, a re-run after an
 approval is a byte-identical no-op, and a marker block the consumer has since
 edited reports `blocked` rather than being repaired. An artefact already tracked
 in git is named separately — an ignore rule cannot untrack it, and the helper
-never runs `git rm`. Only after such an approval does the `scratchPatterns`
-derivation have real ignored planning artefacts to read.
+never runs `git rm`. Approving that offer is also what makes the artefacts
+deletable at teardown: `.gitignore` is the one deletion-policy surface.
 
 ## Cleanup
 
-`cleanup.py` previews by default. Removal refuses protected, tracked-dirty,
-non-scratch-dirty, open-PR, or unmerged worktrees. Profile-declared untracked
-scratch is named in the report but does not block removal. The assessment reads
-`ANNAHMEN.md` before removal and returns its contents for propagation.
-`wrapup-land.py` invokes this same assessment after a merge and before killing
-processes or removing the worktree.
-
-Explicit removal re-collects facts immediately before mutation, requires the
-same removable inventory, deletes only the exact contained scratch entries
-from that inventory, and uses ordinary `git worktree remove`. Regular-file
-identity stays byte-bound. A profile-authorized symlink is eligible only when
-its relative target resolves to an existing entry inside the assessed
-worktree; cleanup freezes both the link and resolved target identities, then
-unlinks the link without following it. Absolute, escaping, dangling, changed,
-unmatched, or late symlinks stop cleanup. It never bypasses Git's final
-concurrent-change check with force removal.
-
-The generic setup route atomically records its ignored and complete
-untracked-file inventories in the linked worktree's Git metadata after its
-configured setup steps. The record is bound to the worktree path, branch, root
-device/inode, and setup HEAD, and carries a canonical digest. Existing
-worktrees can receive a conservative baseline only when they are the exact
-registered no-follow directory on an attached branch with a clean tracked
-worktree and index. Setup reuse defers that backfill, without blocking the
-existing worktree, while tracked work is dirty or landing-generated blockers
-are present. Landing classifies those blockers before writing any baseline;
-after they are moved, every remaining current ignored and untracked path is
-recorded as pre-existing and therefore protected. A corrupt baseline or an
-active landing attempt is never overwritten. The claim-bound session route
-below captures its stricter baseline before project setup so a failed setup has
-an exact recovery boundary.
-
-Before merge, the committed worktree profile may only nominate exact,
-identity-bound landing candidates; it authorizes no deletion. After merge and
-`fetch origin/main`, cleanup reloads the profile directly from canonical
-`origin/main`, requires its scratch and generator policies to equal the
-worktree candidate and the policy digest frozen at attempt start, and only then
-authorizes mutation. Every supplied generator-evidence path is independently
-checked against that canonical generator policy. A missing policy is distinct
-from an explicit empty policy. An unmerged or transient branch policy therefore
-cannot grant itself broader cleanup authority.
-
-Canonical policy that drifts between attempt start and post-merge cleanup keeps
-that refusal, and the refusal names its supported recovery. Recovery re-derives
-authority from the merged canonical policy alone: it never consults the stale
-worktree candidate, never re-scans for new candidates, requires the branch to
-already be an ancestor of canonical main, and requires each frozen identity to
-be both named by canonical policy and unchanged on disk. Evidence outside
-canonical policy, a changed identity, and pre-existing or foreign state stop the
-recovery instead of being deleted, and a repeated run after a completed teardown
-is a no-op.
-
-The landing adapter may carry exact scratch evidence only for current ignored
-files that match the consumer-owned
-`wrapup.landingGeneratedArtifactPatterns` profile and were absent from that
-creation baseline. Missing, changed, or incoherent provenance stops landing
-cleanup. Initial/profile-matched files, unmatched files, landing-generated
-symlinks, and writes after the landing evidence snapshot remain cleanup stops;
-generator evidence and regular-file removal stay descriptor-bound and require
-a second inventory check.
-Mutable session logs belong in explicit `scratchPatterns`, not in the landing
-generator allowlist: their identity is frozen at final cleanup assessment, so
-normal logging before teardown remains live while a later append or replacement
-still stops deletion.
-Landing-start blockers are classified before a journal is written, so moving a
-protected blocker permits a clean next attempt. An explicit relinquish archives
-either a started or frozen attempt, including drifted evidence, without
-deleting or claiming any file; the next preflight treats every current file as
-pre-existing. Exact unchanged frozen evidence remains directly resumable. The
-attempt journal name is classified without following a symlink, so a symlinked
-or dangling journal entry stops instead of being read or replaced, and each
-archived receipt is filed under a contract-version-neutral stem plus its own
-recorded contract version. A journal written under a superseded contract is
-classified as legacy rather than corrupt when it still satisfies its own
-recorded contract; that refusal names the archive route explicitly, while a
-journal that fails its own contract is still reported as incoherent evidence.
+`classify.py` is the teardown authority. It reads the worktree's current state
+at the moment of action and nothing else: a tracked change or an unmerged path
+blocks, an untracked non-ignored file blocks with a bounded report (count plus
+top directories, never a path dump), and an ignored entry is Scratch and
+deletable. The single hardcoded exception is `.env*` by basename glob, which is
+deletable only when it is byte-identical to its counterpart at the same
+relative path in the main checkout, both opened no-follow. An ignored symlink
+is deletable only when its target resolves inside the assessed worktree; the
+link itself is unlinked and never followed.
+
+`cleanup.py` previews by default. Removal additionally refuses an unregistered
+path, a detached branch, a protected branch or the main checkout, an open PR,
+and an unmerged branch. The assessment reads `ANNAHMEN.md` before removal and
+returns its contents for propagation.
+
+Explicit removal re-collects facts immediately before mutation and requires the
+same removable inventory. The deletion walk re-opens the assessed root
+no-follow, re-checks its device/inode, and re-checks every entry's kind — and a
+symlink's target — immediately before unlinking it. It uses ordinary `git
+worktree remove` and never bypasses Git's final concurrent-change check with
+force removal.
+
+`wrapup-land.py` runs the same assessment after a merge: quiesce the worktree's
+own declared `.dev-ports` listeners, classify, delete the Scratch, remove the
+worktree. Teardown always runs — a direct `/wrapup` invocation is its
+authorization, including for a worktree an external tool created under a
+foreign name and path. There is no persisted attempt state and no recovery
+flag: an interrupted landing is resumed by re-running it, because every step
+verifies present state and skips what is already done.
+
+Two residual risks are accepted deliberately — between assessment and deletion
+a file could in principle be replaced, and a valuable file a consumer keeps
+gitignored outside `.env*` is deletable at teardown.
 
 `cleanup.py sweep` is the read-only inventory entrypoint. It accounts once for
 every linked worktree and local branch, reports issue/PR/merge/age/removal
 facts, and counts merged remote branches separately. It never removes a
 worktree or branch.
 
-## Session-owned teardown
-
-`session.py` is the narrower orchestration route. It binds one receipt in the
-Git common directory to the active `wave-active/<anchor>` annotated claim:
-
-```sh
-python3 scripts/worktree-lifecycle/session.py begin --anchor <n> --owner <run> --base <wave-head>
-python3 scripts/worktree-lifecycle/session.py create --anchor <n> --owner <run> --base <current-wave-head> <issue> <slug> <type>
-python3 scripts/worktree-lifecycle/session.py recover --anchor <n> --owner <run> --branch <exact-branch>
-python3 scripts/worktree-lifecycle/session.py seal --anchor <n> --owner <run>
-python3 scripts/worktree-lifecycle/session.py inspect --anchor <n> --owner <run> --main origin/main
-python3 scripts/worktree-lifecycle/session.py teardown --anchor <n> --owner <run> --main origin/main
-```
-
-Only `create` can add an inventory row, and it refuses any branch or path that
-already existed. It journals a provisional exact row before `git worktree add`,
-then captures the shared artifact baseline before project setup and promotes
-the row only after setup succeeds. Session inspection
-therefore accepts generated scratch only when the exact path matches the
-profile and is absent from the creation baseline; missing, changed, or
-incoherent provenance stops. `seal` records the final exact branch OIDs.
-Inspection reports ancestry, one-to-one stable patch equivalence, unique
-content, and ambiguity separately. Empty commits, non-ancestry merge commits,
-duplicate patch IDs, open or unreadable PR evidence, dirt, protected names,
-stale registrations, recreated removed targets, and identity drift stop the
-whole teardown before mutation.
-
-If setup fails, the provisional row becomes `recovery-pending`. Automatic and
-explicit `recover` use the same bounded route: active claim and receipt,
-protected name, PR state, exact ref OID, registration/root identity, and the
-creation baseline are revalidated. A branch-only remainder is compare-deleted
-only at its provisional OID. A registered worktree whose add succeeded before
-root journaling is adopted only when its Git registration/backlink, branch,
-OID, and exact-clean inventory all match.
-
-For failed project setup, exact index/worktree diff hashes and paths are frozen
-without storing diff content. Exact regular-file or no-follow symlink identity
-is frozen for every setup-created untracked path. Recovery revalidates that
-evidence, restores only the frozen tracked paths to the creation OID, and
-unlinks only matching untracked identities; later foreign files,
-modifications, or replacements stop without losing receipt ownership. If
-identity capture cannot finish, the receipt retains only a bounded failure
-class and can retry from the unchanged inventory or an exact-clean worktree.
-Raw command, exception, stdout, and stderr text is never retained or archived.
-Recovery uses ordinary worktree removal and compare-deletes the exact ref.
-
-Teardown re-runs that complete assessment, archives every recovery OID in the
-receipt before its first mutation, and revalidates canonical main, the active
-claim and receipt, profile protection, PR state, branch OID, worktree
-registration/root identity, dirt, and the exact scratch inventory immediately
-before each target mutation. After ordinary worktree removal it rechecks the
-ref-side gates, then compare-deletes only the recorded local refs with
-`git update-ref -d <ref> <expected-oid>`. A concurrent ref move therefore
-survives, while a partial run keeps its recovery OIDs and can resume. Generic
-cleanup and sweep never consume this ownership route and never infer authority
-over a foreign branch.
-
 Claude hook wiring and any Codex adaptation consume this same profile and core.
 An adapter may change only the surface event envelope; it must preserve the
 core verdict and message.

package/scripts/worktree-lifecycle/capabilities.json

@@ -39,13 +39,12 @@
     {
       "historicalPath": "scripts/cleanup-worktrees.sh",
       "artifact": "scripts/worktree-lifecycle/cleanup.py",
-      "supportingArtifacts": ["scripts/worktree-lifecycle/session.py"],
+      "supportingArtifacts": ["scripts/worktree-lifecycle/classify.py"],
       "primitives": [
         "profile",
         "git-facts",
         "cleanup-safety",
-        "claim-bound-session-receipt",
-        "patch-equivalence",
+        "stateless-classification",
         "compare-and-delete"
       ]
     }