@ikon85/agent-workflow-kit 0.42.1 → 0.43.0

package/README.md

@@ -469,6 +469,25 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.43.0
+
+- removed: `docs/agents/domain.md`
+- removed: `docs/agents/issue-tracker.md`
+- removed: `docs/agents/skills/local-ci.md`
+- removed: `docs/agents/skills/orchestrate-wave.md`
+- removed: `docs/agents/skills/spec-self-critique.md`
+- removed: `docs/agents/triage-labels.md`
+- removed: `docs/conventions/spec-completeness.md`
+- changed: `package.json`
+- changed: `scripts/build-kit.test.mjs`
+- changed: `scripts/codex-exec-scenarios/fake-codex.mjs`
+- changed: `scripts/codex-exec.test.mjs`
+- changed: `scripts/release-delta-guard.mjs`
+- changed: `scripts/release-delta-guard.test.mjs`
+- changed: `scripts/test_worktree_wrapup_contract.py`
+- changed: `scripts/worktree-lifecycle/README.md`
+- changed: `scripts/worktree-lifecycle/core.py`
+
 ### 0.42.1
 
 - changed: `docs/agents/skills/orchestrate-wave.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.42.1",
+  "kitVersion": "0.43.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -2699,7 +2699,7 @@
       "path": "scripts/release-delta-guard.mjs",
       "kind": "script",
       "installRole": "maintainer",
-      "sha256": "566d7bae5526af2f8863d7a06dfa3016c9383b241b616cd43757eb7b46555895",
+      "sha256": "41d9fd9c86324f1428a3de04f2bfcb630e868525d88a8864d7bdfc2954e00414",
       "mode": 420,
       "origin": "kit"
     },
@@ -2811,7 +2811,7 @@
       "path": "scripts/worktree-lifecycle/core.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "50c60de1e0238fa1f5cd627f67e57ca4f378275136691411487f36d7fda580dd",
+      "sha256": "2c89528a7beb629eb8b61ced26dd68cd8cd19fe2d37a4934badf74cede51e832",
       "mode": 420,
       "origin": "kit"
     },
@@ -2843,7 +2843,7 @@
       "path": "scripts/worktree-lifecycle/README.md",
       "kind": "doc",
       "installRole": "consumer",
-      "sha256": "0dbba4a87d41171f3fce22a4842eecd2a989ea6a5ddf44832d7b2aed9feb4226",
+      "sha256": "a5e89b57eeb817075214af30e6504f4077434b9f90fb08a19aea028144073448",
       "mode": 420,
       "origin": "kit"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.42.1",
+  "version": "0.43.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {
@@ -24,6 +24,16 @@
     "assets/",
     "scripts/",
     "docs/",
+    "!docs/agents/issue-tracker.md",
+    "!docs/agents/triage-labels.md",
+    "!docs/agents/domain.md",
+    "!docs/agents/skills/spec-self-critique.md",
+    "!docs/agents/skills/orchestrate-wave.md",
+    "!docs/agents/skills/local-ci.md",
+    "!docs/agents/skills/git-worktree-recover.md",
+    "!docs/agents/skills/audit-skills.md",
+    "!docs/agents/skills/security-audit.md",
+    "!docs/conventions/spec-completeness.md",
     "src/",
     "agent-workflow-kit.package.json",
     "LICENSE",

package/scripts/build-kit.test.mjs

@@ -8,7 +8,7 @@ import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { buildKit } from './build-kit.mjs';
 import { init } from '../src/commands/init.mjs';
-import { HELPER_FILES } from '../src/lib/bundle.mjs';
+import { HELPER_FILES, STUB_TARGETS } from '../src/lib/bundle.mjs';
 import { CONSUMER_MANIFEST_NAME, readManifest } from '../src/lib/manifest.mjs';
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -155,6 +155,9 @@ test('npm pack keeps product files but excludes runtime residue', async () => {
     for (const path of PUBLIC_CENSUS_UNIT) {
       assert.ok(files.includes(path), `pack missing ${path}`);
     }
+    for (const path of STUB_TARGETS) {
+      assert.ok(!files.includes(path), `pack must exclude init stub target ${path}`);
+    }
     const packedByPath = new Map(JSON.parse(output)[0].files.map((file) => [file.path, file]));
     assert.deepEqual(
       WAVE_152_HELPERS.map(({ path, mode }) => ({ path, mode: packedByPath.get(path)?.mode })),

package/scripts/codex-exec-scenarios/fake-codex.mjs

@@ -52,6 +52,16 @@ const verdict = () => emit({
   item: { id: 'fake-item', type: 'agent_message', text: 'fake verdict' },
 });
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const waitForSignal = () => new Promise((resolve) => {
+  const keepAlive = setInterval(() => {}, 2_147_483_647);
+  const done = () => {
+    clearInterval(keepAlive);
+    resolve();
+  };
+  process.once('SIGTERM', done);
+  process.once('SIGINT', done);
+  process.once('SIGHUP', done);
+});
 
 switch (scenario) {
   case 'silent':
@@ -129,7 +139,10 @@ switch (scenario) {
     if (process.env.FAKE_CODEX_CHILD_PID) {
       writeFileSync(process.env.FAKE_CODEX_CHILD_PID, String(child.pid));
     }
-    await sleep(pause);
+    if (process.env.FAKE_CODEX_GROUP_HANG_READY) {
+      writeFileSync(process.env.FAKE_CODEX_GROUP_HANG_READY, 'ready\n');
+    }
+    await waitForSignal();
     break;
   }
   case 'orphan-group': {

package/scripts/codex-exec.test.mjs

@@ -369,15 +369,17 @@ test('automatic stale cleanup is bounded and never removes retained or active st
 
 test('invalid stale cleanup limits fail before launch and preserve an active run', async () => {
   const fx = fixture();
+  const ready = join(fx.dir, 'group-hang.ready');
   const running = spawn(helper, launchArgs('build'), {
     cwd: root, encoding: 'utf8', env: {
       ...process.env, CODEX_EXEC_STATE_ROOT: fx.stateRoot,
-      FAKE_CODEX_SCENARIO: 'group-hang', FAKE_CODEX_PAUSE_MS: '5000',
+      FAKE_CODEX_SCENARIO: 'group-hang', FAKE_CODEX_GROUP_HANG_READY: ready,
       FAKE_CODEX_LAUNCH_LOG: fx.launchLog,
     },
   });
   running.stdout.on('data', () => {});
   try {
+    assert.ok(await waitFor(() => exists(ready)));
     const stateName = await waitFor(() => exists(fx.stateRoot) && readdirSync(fx.stateRoot)
       .find((name) => readJson(join(fx.stateRoot, name, 'runtime.json'))?.phase === 'running'));
     assert.ok(stateName);
@@ -452,7 +454,6 @@ test('stale cleanup cannot delete a run whose resume acquired the shared lease',
         ...process.env,
         CODEX_EXEC_STATE_ROOT: fx.stateRoot,
         FAKE_CODEX_SCENARIO: 'group-hang',
-        FAKE_CODEX_PAUSE_MS: '5000',
         FAKE_CODEX_LAUNCH_LOG: fx.launchLog,
       },
     });
@@ -577,7 +578,7 @@ test('timeout kills only the owned group and leaves a decoy sibling alive', () =
   try {
     const args = launchArgs().map((value, index, all) => all[index - 1] === '--timeout' ? '0.35' : value);
     const result = invoke(fx, args, {
-      FAKE_CODEX_SCENARIO: 'group-hang', FAKE_CODEX_PAUSE_MS: '2000', FAKE_CODEX_CHILD_PID: childPid,
+      FAKE_CODEX_SCENARIO: 'group-hang', FAKE_CODEX_CHILD_PID: childPid,
     });
     assert.equal(result.output.status, 'TIMEOUT');
     assert.equal(exists(result.output.stateDir), true);
@@ -598,7 +599,7 @@ test('a concurrent resume and finalize cannot steal an owned round lease', async
   ], {
     cwd: root, encoding: 'utf8', env: {
       ...process.env, CODEX_EXEC_STATE_ROOT: fx.stateRoot,
-      FAKE_CODEX_SCENARIO: 'group-hang', FAKE_CODEX_PAUSE_MS: '5000',
+      FAKE_CODEX_SCENARIO: 'group-hang',
       FAKE_CODEX_LAUNCH_LOG: fx.launchLog,
     },
   });
@@ -655,7 +656,6 @@ test('a runtime publication failure reaps the owned child before releasing its l
     CODEX_EXEC_TEST_CHILD_PID_FILE: childPid,
     CODEX_EXEC_TEST_RUNTIME_WRITE_FAIL: '1',
     FAKE_CODEX_SCENARIO: 'group-hang',
-    FAKE_CODEX_PAUSE_MS: '5000',
   });
   assert.notEqual(result.status, 0);
   assert.equal(result.output.error, 'ROUND_SUPERVISOR_FAILED');
@@ -795,7 +795,7 @@ test('abort cancels an active run, deletes its state, and spares a decoy', async
   const running = spawn(helper, launchArgs('build'), {
     cwd: root, encoding: 'utf8', env: {
       ...process.env, CODEX_EXEC_STATE_ROOT: fx.stateRoot, FAKE_CODEX_SCENARIO: 'group-hang',
-      FAKE_CODEX_PAUSE_MS: '5000', FAKE_CODEX_LAUNCH_LOG: fx.launchLog,
+      FAKE_CODEX_LAUNCH_LOG: fx.launchLog,
     },
   });
   let stdout = '';
@@ -823,7 +823,7 @@ test('handle-failure selects one of two simultaneous live runs and leaves the ot
   const start = () => spawn(helper, launchArgs('build'), {
     cwd: root, encoding: 'utf8', env: {
       ...process.env, CODEX_EXEC_STATE_ROOT: fx.stateRoot,
-      FAKE_CODEX_SCENARIO: 'group-hang', FAKE_CODEX_PAUSE_MS: '5000',
+      FAKE_CODEX_SCENARIO: 'group-hang',
       FAKE_CODEX_LAUNCH_LOG: fx.launchLog,
     },
   });

package/scripts/release-delta-guard.mjs

@@ -4,6 +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 { sha256 } from '../src/lib/hash.mjs';
 import { buildKit } from './build-kit.mjs';
 
@@ -30,9 +31,10 @@ function mergeDeltas(...deltas) {
   ]));
 }
 
-export function recommendBump(delta) {
-  if (delta.removed.length) return 'major';
-  if (delta.added.length) return 'minor';
+export function recommendBump(delta, { minorRemovals = [] } = {}) {
+  const minorRemovalSet = new Set(minorRemovals);
+  if (delta.removed.some((path) => !minorRemovalSet.has(path))) return 'major';
+  if (delta.added.length || delta.removed.length) return 'minor';
   return delta.changed.length ? 'patch' : null;
 }
 
@@ -79,7 +81,13 @@ export function assessRelease(input) {
       + `tag and publish it before preparing ${input.currentVersion}`,
     );
   }
-  const recommendedBump = recommendBump(delta);
+  // 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),
+  );
+  const recommendedBump = recommendBump(delta, { minorRemovals: seedOnlyPackageRemovals });
   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/release-delta-guard.test.mjs

@@ -58,6 +58,29 @@ test('an npm runtime change outside the Consumer manifest still requires a relea
   assert.match(result.errors.join('\n'), /version remains 1\.2\.3/);
 });
 
+test('removing accidentally packed seed-only project stubs is a minor change', () => {
+  const consumer = { kitVersion: '1.3.0', files: [file('skill.md', 'same')] };
+  const result = assessRelease({
+    baseVersion: '1.2.3',
+    currentVersion: '1.3.0',
+    baseManifest: { ...consumer, kitVersion: '1.2.3' },
+    builtManifest: consumer,
+    checkedManifest: consumer,
+    payloadManifest: consumer,
+    basePackagePayload: {
+      files: [
+        file('src/cli.mjs', 'same'),
+        file('docs/agents/issue-tracker.md', 'filled-project-layer'),
+      ],
+    },
+    currentPackagePayload: { files: [file('src/cli.mjs', 'same')] },
+  });
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(result.delta.removed, ['docs/agents/issue-tracker.md']);
+  assert.equal(result.recommendedBump, 'minor');
+});
+
 test('dead checked-manifest entries are rejected', () => {
   const result = assessRelease({
     baseVersion: '1.2.3', currentVersion: '1.3.0',

package/scripts/test_worktree_wrapup_contract.py

@@ -51,7 +51,7 @@ def create_merged_worktree(
     command(["git", "config", "user.name", "Test"], main)
     command(["git", "config", "user.email", "test@example.invalid"], main)
     (main / ".gitignore").write_text(
-        ".worktrees/\ndist-kit/\n__pycache__/\n.claude/logs/\nconsumer/\n",
+        ".worktrees/\ndist-kit/\n__pycache__/\n.claude/logs/\nconsumer/\nnode_modules/\n",
         encoding="utf-8",
     )
     profile = main / "docs/agents/workflow-capabilities.json"
@@ -773,6 +773,35 @@ class WorktreeCleanupContract(unittest.TestCase):
             self.assertFalse(worktree.exists())
             self.assertTrue(second["merged"])
 
+    def test_pnpm_symlink_farm_reaches_guarded_land_idempotently(self):
+        wrapup = load_wrapup()
+        with tempfile.TemporaryDirectory() as tmp:
+            main, worktree = create_merged_worktree(
+                Path(tmp), scratch_patterns=["node_modules/**"]
+            )
+            wrapup.landing_start_artifact_inventory(str(worktree), str(main))
+            wrapup.freeze_landing_artifact_evidence(
+                str(worktree), str(main), push_succeeded=True
+            )
+            package = (
+                worktree
+                / "node_modules/.pnpm/example@1.0.0/node_modules/example"
+            )
+            package.mkdir(parents=True)
+            (package / "index.js").write_text(
+                "export default 1;\n", encoding="utf-8"
+            )
+            (worktree / "node_modules/example").symlink_to(
+                ".pnpm/example@1.0.0/node_modules/example"
+            )
+
+            first = run_land(wrapup, main, land_args())
+            second = run_land(wrapup, main, land_args())
+
+            self.assertEqual(first["worktree_removed"], str(worktree))
+            self.assertFalse(worktree.exists())
+            self.assertTrue(second["merged"])
+
     def test_append_after_profile_log_assessment_is_preserved_and_stops(self):
         wrapup = load_wrapup()
         with tempfile.TemporaryDirectory() as tmp:
@@ -934,6 +963,66 @@ class WorktreeCleanupContract(unittest.TestCase):
             self.assertTrue(generated.exists())
             self.assertTrue(late.exists())
 
+    def test_late_profile_scratch_symlink_stops_before_assessed_links_are_removed(self):
+        wrapup = load_wrapup()
+        with tempfile.TemporaryDirectory() as tmp:
+            main, worktree = create_merged_worktree(
+                Path(tmp), scratch_patterns=["node_modules/**"]
+            )
+            wrapup.landing_start_artifact_inventory(str(worktree), str(main))
+            packages = worktree / "node_modules/.pnpm"
+            first_target = packages / "first@1.0.0/node_modules/first"
+            first_target.mkdir(parents=True)
+            first = worktree / "node_modules/first"
+            first.symlink_to(".pnpm/first@1.0.0/node_modules/first")
+            assessment = wrapup.ensure_worktree_removable(
+                str(worktree), str(main)
+            )
+            late_target = packages / "late@1.0.0/node_modules/late"
+            late_target.mkdir(parents=True)
+            late = worktree / "node_modules/late"
+            late.symlink_to(".pnpm/late@1.0.0/node_modules/late")
+
+            with self.assertRaises(wrapup.Stop) as stopped:
+                wrapup.remove_verified_worktree_scratch(
+                    str(worktree), str(main), assessment
+                )
+
+            self.assertIn(
+                "inventory no longer matches preview", stopped.exception.reason
+            )
+            self.assertTrue(first.is_symlink())
+            self.assertTrue(late.is_symlink())
+
+    def test_changed_internal_symlink_target_identity_stops_cleanup(self):
+        wrapup = load_wrapup()
+        with tempfile.TemporaryDirectory() as tmp:
+            main, worktree = create_merged_worktree(
+                Path(tmp), scratch_patterns=["PLAN.md"]
+            )
+            wrapup.landing_start_artifact_inventory(str(worktree), str(main))
+            link = worktree / "PLAN.md"
+            link.symlink_to("change.txt")
+            assessment = wrapup.ensure_worktree_removable(
+                str(worktree), str(main)
+            )
+            tracked_target = worktree / "change.txt"
+            original = tracked_target.read_text(encoding="utf-8")
+            replacement = worktree / "replacement.tmp"
+            replacement.write_text(original, encoding="utf-8")
+            os.replace(replacement, tracked_target)
+
+            with self.assertRaises(wrapup.Stop) as stopped:
+                wrapup.remove_verified_worktree_scratch(
+                    str(worktree), str(main), assessment
+                )
+
+            self.assertIn(
+                "inventory no longer matches preview", stopped.exception.reason
+            )
+            self.assertTrue(link.is_symlink())
+            self.assertEqual(tracked_target.read_text(encoding="utf-8"), original)
+
     def test_same_path_generated_replacement_is_preserved_by_frozen_evidence(self):
         wrapup = load_wrapup()
         with tempfile.TemporaryDirectory() as tmp:

package/scripts/worktree-lifecycle/README.md

@@ -86,9 +86,14 @@ scratch is named in the report but does not block removal. The assessment reads
 processes or removing the worktree.
 
 Explicit removal re-collects facts immediately before mutation, requires the
-same removable inventory, deletes only the exact contained regular scratch
-files from that inventory, and uses ordinary `git worktree remove`. It never
-bypasses Git's final concurrent-change check with force removal.
+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
@@ -129,9 +134,10 @@ 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, symlinks, and writes
-after the landing evidence snapshot remain cleanup stops; deletion still uses
-the same descriptor-bound regular-file primitive and a second inventory check.
+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

package/scripts/worktree-lifecycle/core.py

@@ -1220,17 +1220,28 @@ def remove_authorized_scratch(
             raise LifecycleError(
                 f"landing-generated scratch evidence is missing: {relative}"
             )
+        if generated and expected.get("kind") == "symlink":
+            raise LifecycleError(
+                f"landing-generated scratch path is not a regular file: {relative}"
+            )
         if profile_authorized and expected is None:
             raise LifecycleError(f"profile scratch evidence is missing: {relative}")
         if not profile_authorized and expected is None:
             raise LifecycleError(f"verified scratch evidence is missing: {relative}")
     for relative in scratch_files:
         expected = evidence_by_path[relative]
-        remove_contained_regular(
-            root_descriptor,
-            relative,
-            expected_identity=expected,
-        )
+        if expected.get("kind") == "symlink":
+            remove_contained_untracked(
+                root_descriptor,
+                expected,
+                require_contained_symlink_target=True,
+            )
+        else:
+            remove_contained_regular(
+                root_descriptor,
+                relative,
+                expected_identity=expected,
+            )
 
 
 def bind_cleanup_scratch_evidence(
@@ -1292,7 +1303,7 @@ def bind_cleanup_scratch_evidence(
         assessment.root_inode,
     ) as descriptor:
         for relative in profile_only:
-            evidence_by_path[relative] = contained_regular_identity(
+            evidence_by_path[relative] = contained_profile_scratch_identity(
                 descriptor, relative
             )
     return replace(
@@ -1366,6 +1377,8 @@ def contained_regular_identity(root_descriptor: int, relative: str) -> dict[str,
 def contained_untracked_identity(
     root_descriptor: int,
     relative: str,
+    *,
+    require_contained_symlink_target: bool = False,
 ) -> dict[str, Any]:
     """Read exact regular/symlink identity without following any symlink."""
     path = PurePosixPath(relative)
@@ -1393,10 +1406,26 @@ def contained_untracked_identity(
             "size": metadata.st_size,
         }
         if stat.S_ISLNK(metadata.st_mode):
-            target = os.readlink(path.name, dir_fd=current).encode(
+            target_text = os.readlink(path.name, dir_fd=current)
+            target = target_text.encode(
                 "utf-8", errors="surrogateescape"
             )
-            return {**common, "kind": "symlink", "sha256": sha256(target).hexdigest()}
+            identity = {
+                **common,
+                "kind": "symlink",
+                "sha256": sha256(target).hexdigest(),
+            }
+            if require_contained_symlink_target:
+                target_metadata = contained_symlink_target_identity(
+                    root_descriptor,
+                    relative,
+                    target_text,
+                )
+                identity.update({
+                    "targetDevice": target_metadata.st_dev,
+                    "targetInode": target_metadata.st_ino,
+                })
+            return identity
         if not stat.S_ISREG(metadata.st_mode):
             raise LifecycleError(f"unsupported recovery path type: {relative}")
         file_descriptor = os.open(
@@ -1427,15 +1456,126 @@ def contained_untracked_identity(
             os.close(descriptor)
 
 
+def contained_profile_scratch_identity(
+    root_descriptor: int,
+    relative: str,
+) -> dict[str, Any]:
+    """Freeze regular scratch unchanged, or one contained symlink and its target."""
+    identity = contained_untracked_identity(
+        root_descriptor,
+        relative,
+        require_contained_symlink_target=True,
+    )
+    if identity["kind"] == "regular":
+        return {
+            key: value
+            for key, value in identity.items()
+            if key != "kind"
+        }
+    return identity
+
+
+def _relative_target_parts(
+    base_parts: list[str],
+    target: str,
+    relative: str,
+) -> list[str]:
+    target_path = PurePosixPath(target)
+    if target_path.is_absolute():
+        raise LifecycleError(f"scratch symlink target is absolute: {relative}")
+    resolved = list(base_parts)
+    for component in target_path.parts:
+        if component in {"", "."}:
+            continue
+        if component == "..":
+            if not resolved:
+                raise LifecycleError(
+                    f"scratch symlink target escapes worktree: {relative}"
+                )
+            resolved.pop()
+            continue
+        resolved.append(component)
+    return resolved
+
+
+def contained_symlink_target_identity(
+    root_descriptor: int,
+    relative: str,
+    target: str,
+) -> os.stat_result:
+    """Resolve one symlink target beneath the open root, rejecting every escape."""
+    link = PurePosixPath(relative)
+    pending = _relative_target_parts(list(link.parts[:-1]), target, relative)
+    resolved: list[str] = []
+    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    no_follow = getattr(os, "O_NOFOLLOW", 0)
+    symlink_count = 0
+    try:
+        if not pending:
+            return os.fstat(root_descriptor)
+        while pending:
+            component = pending.pop(0)
+            descriptors = []
+            try:
+                parent = root_descriptor
+                for ancestor in resolved:
+                    parent = os.open(
+                        ancestor,
+                        directory_flags | no_follow,
+                        dir_fd=parent,
+                    )
+                    descriptors.append(parent)
+                metadata = os.stat(
+                    component,
+                    dir_fd=parent,
+                    follow_symlinks=False,
+                )
+                if stat.S_ISLNK(metadata.st_mode):
+                    symlink_count += 1
+                    if symlink_count > 40:
+                        raise OSError("too many symbolic links")
+                    nested_target = os.readlink(component, dir_fd=parent)
+                    pending = _relative_target_parts(
+                        resolved,
+                        nested_target,
+                        relative,
+                    ) + pending
+                    resolved = []
+                    if not pending:
+                        return os.fstat(root_descriptor)
+                    continue
+                if pending and not stat.S_ISDIR(metadata.st_mode):
+                    raise OSError("symlink target parent is not a directory")
+                resolved.append(component)
+                if not pending:
+                    return metadata
+            finally:
+                for descriptor in reversed(descriptors):
+                    os.close(descriptor)
+    except LifecycleError:
+        raise
+    except OSError as error:
+        raise LifecycleError(
+            f"scratch symlink target is dangling or changed: {relative}"
+        ) from error
+    raise LifecycleError(f"scratch symlink target is dangling or changed: {relative}")
+
+
 def remove_contained_untracked(
     root_descriptor: int,
     expected_identity: dict[str, Any],
+    *,
+    require_contained_symlink_target: bool = False,
 ) -> None:
     """Unlink one frozen regular file or symlink if its identity still matches."""
     relative = expected_identity.get("path")
     if not isinstance(relative, str):
         raise LifecycleError("recovery path evidence is incoherent")
-    current = contained_untracked_identity(root_descriptor, relative)
+    current = contained_untracked_identity(
+        root_descriptor,
+        relative,
+        require_contained_symlink_target=require_contained_symlink_target,
+    )
     if current != expected_identity:
         raise LifecycleError(f"recovery path identity changed: {relative}")
     path = PurePosixPath(relative)

package/docs/agents/domain.md

@@ -1,7 +0,0 @@
-<!-- setup-workflow: state=filled -->
-# Domain docs
-
-This is a single-context repository. Before design work, read root `CONTEXT.md` when present and the relevant decisions under `docs/adr/`. Their absence is non-blocking: `grill-with-docs` creates them when the product language or a durable decision first needs recording.
-
-Use glossary terms consistently in issues, tests, and skill text. Surface conflicts with an existing ADR instead of silently replacing its decision.
-

package/docs/agents/issue-tracker.md

@@ -1,23 +0,0 @@
-<!-- setup-workflow: state=filled -->
-# Issue tracker: GitHub
-
-Issues and PRDs for this repo live in `iKon85/agent-workflow-kit` as GitHub issues.
-
-## Conventions
-
-- Use `gh` for issue reads and comments; infer the repository from the remote.
-- Write multi-line issue and PR bodies through a temporary file and `--body-file`.
-- Route board writes, status/wave/cluster field edits, dependencies, and sub-issue links through `scripts/board-sync.py`, not bare `gh project` commands.
-- Board state is authoritative for workflow status; GitHub issues remain the durable content source.
-
-## Pickup claim
-
-Used by `/implement`, `/diagnose`, and `/orchestrate-wave` before the first
-edit. Board status `In Progress` is the human-facing signal; the claim below is
-the machine-readable one, and it is the only one that names the branch and
-worktree a colliding session would have to find.
-
-- **Check**: `gh issue view <n> --json assignees,comments --jq '{assignees: [.assignees[].login], claims: [.comments[].body | select(contains("<!-- agent-claim:"))]}'` — a foreign assignee or a marker this session did not plant is a foreign claim: stop, report the claimed branch/worktree, and leave it alone.
-- **Claim**: `gh issue edit <n> --add-assignee @me`, then `gh issue comment <n> --body '<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->'`. Board status stays a `scripts/board-sync.py` write, never a bare `gh project` call.
-- **Release**: the slice PR (`closes #<n>` / `Part of #<anchor>`) supersedes the claim, so `/wrapup` needs no extra step. On abandon: `gh issue edit <n> --remove-assignee @me` plus a `claim released` comment.
-

package/docs/agents/skills/local-ci.md

@@ -1,90 +0,0 @@
-<!-- setup-workflow: state=filled -->
-<!-- agent-workflow-kit: project-extension/v1; skill=local-ci -->
-# Project layer — local-ci
-
-This repo is a Node + stdlib-Python repo with no database, no dev server and no
-typecheck step, so the two generic profiles map onto a short command set. Run the
-two commands below; do not infer others.
-
-Prerequisite once per clone (worktrees inherit it):
-
-```sh
-git config core.hooksPath .githooks
-```
-
-## Fast static guards
-
-The skill/manifest lints, ~3s, no network, no DB. This is exactly what
-`.githooks/pre-commit` runs, so a normal commit already covers it:
-
-```sh
-python3 -m unittest discover -s scripts -p 'test_skill_*.py' -q
-```
-
-## Full gate
-
-Mirrors the `test` job in `.github/workflows/ci.yml` step for step. Run it from
-the branch's worktree root before opening a PR:
-
-```sh
-npm test
-npm run kit:staleness
-npm run release:guard -- --base "$(git merge-base origin/main HEAD)"
-npm pack --dry-run
-```
-
-Notes on the individual steps:
-
-- `npm test` is `test:node` (`node --test`) plus `test:python`
-  (`python3 -m unittest discover -s scripts -p 'test_*.py'`). Several negative-path
-  tests print `[FAIL] …` lines by design; only the runner's own summary and exit
-  code decide red or green.
-- CI runs `npm install --ignore-scripts` first. Locally that is only needed after
-  a dependency change.
-- `release:guard` runs in CI on `pull_request` only, against
-  `github.event.pull_request.base.sha`. `git merge-base origin/main HEAD` is the
-  local equivalent; `git fetch origin main` first if `origin/main` is stale.
-- `npm pack --dry-run` catches packaging drift (a file added outside the
-  published set) without publishing anything.
-
-## Enforcement
-
-Since #220 the host **does** enforce: the `main protection` ruleset makes the CI
-job `test` a required status check on `main`, with no bypass actor. So the
-generic skill's "When the host CAN enforce" branch applies to this repo — the
-local gate is a pre-flight that shortens the feedback loop, not the only thing
-standing between a red branch and `main`.
-
-Layered, from cheapest to strongest:
-
-| Layer | Runs | Scope |
-| --- | --- | --- |
-| `pre-commit` | automatic, every commit | fast skill/manifest lints |
-| `pre-push` | automatic, every push | full `npm test` |
-| this full gate | explicit, before a PR | `npm test` + staleness + release guard + pack |
-| CI `test` | automatic, on the PR | the same set, machine-enforced at merge |
-
-Never bypass a hook with `--no-verify`.
-
-**Drift rule.** The full gate above and `.github/workflows/ci.yml` are two copies
-of one list. Change one, change the other in the same PR — otherwise the local
-gate goes green on a set the required check does not accept.
-
-## Contention
-
-Not applicable here. This repo has no dev server and the suites are process-level
-(`node --test`, `unittest`), so the generic boot-contention false-red guidance has
-no target. A red is a real red until an isolated re-run of that one test proves
-otherwise.
-
-## On a red
-
-1. Read the failing assertion — the guards print the exact drift (`file:line`,
-   the offending token, the missing manifest key).
-2. Fix the source. A guard that legitimately cannot be satisfied yet gets a
-   documented allowlist entry with a reason; never widen a guard silently.
-3. Re-run the single failing suite, then the full gate for sign-off.
-
-`kit:staleness` red almost always means the generated kit artefacts lag the
-skill sources — run `npm run kit:build` and commit the result rather than
-editing the generated output by hand.

package/docs/agents/skills/orchestrate-wave.md

@@ -1,166 +0,0 @@
-<!-- setup-workflow: state=filled -->
-<!-- agent-workflow-kit: project-extension/v1; skill=orchestrate-wave -->
-# Project layer — orchestrate-wave
-
-Filled 2026-07-27 after Welle 18 (#289) ran the whole loop end-to-end — recon,
-build, integrate, verify, land, tag, publish — and proved the recipe below. The
-sections were deliberately empty until then; the generic fallback carried that
-run and cost it a `degraded` start plus a hand-derivation of every command here.
-
-This repo has **no database, no dev server, no typecheck step and no browser
-surface**, so several generic phases collapse to very little. Where that is the
-case the section says so rather than inventing a command.
-
-## §Setup
-
-Nothing to start. No DB, no tunnel, no service, no dev server — Phase 0's
-"start what live-verify needs" is a no-op here.
-
-Two things that are *not* no-ops:
-
-- `git config core.hooksPath .githooks` once per clone (worktrees inherit it).
-- `npm install` in the wave worktree after fast-forwarding to `origin/main` —
-  the lockfile is untracked, so dependencies do not travel with the branch.
-
-## §Builder Commands
-
-Per-slice gate, run by the implementer before reporting back:
-
-```sh
-npm test                  # test:node (node --test) + test:python (unittest)
-```
-
-The fast pre-commit lints run automatically via `.githooks/pre-commit`
-(~3 s, skill/manifest lints). A slice is not "green" on the fast lints alone.
-
-## §Builder Hard Rules
-
-- **Never `--no-verify`.** pre-commit and pre-push are the backstop, not an
-  obstacle.
-- **English-first prose** in every published skill; the language census in the
-  maintainer suite enforces it.
-- **No hardcoded board values** — labels, headings, field IDs and status names
-  come from `docs/agents/board-sync.md`; the portability lint blocks literals.
-- **Dual-surface mirror in the same PR.** A changed `.claude/skills/<s>/SKILL.md`
-  needs its `.agents/skills/<s>/SKILL.md` mirror via `codex-adapter-sync` in the
-  same PR, never after merge.
-- **Shipped-file changes must preserve the manifest/reconcile contract.**
-
-## §Integration Suites
-
-Both frameworks, every time — `npm test` runs both and a red in either is a red:
-
-```sh
-npm test
-```
-
-- `test:node` — `node --test` (665 tests as of 0.42.0)
-- `test:python` — `python3 -m unittest discover -s scripts -p 'test_*.py'`
-  (522 tests as of 0.42.0)
-
-There is no typecheck step in this repo; do not look for one. Several
-negative-path tests print `[FAIL] …` lines **by design** — only the runner's own
-summary and exit code decide red or green.
-
-## §Verify Recipe
-
-Central verify is the `/local-ci` full gate, run from the wave worktree root.
-It mirrors the CI `test` job step for step:
-
-```sh
-git fetch origin main
-npm test
-npm run kit:staleness
-npm run release:guard -- --base "$(git merge-base origin/main HEAD)"
-npm pack --dry-run
-```
-
-- **No branch-name-derived guard exists here**, so the generic skill's warning
-  about an integrated verify branch blocking with no baseline does not apply.
-  No skip or override is needed.
-- **No browser, no headless login, no screenshots, no console check, no DB
-  compare, no design/brand check.** This repo ships text; "assert the AC as a
-  user-visible outcome" means reading the artefact the slice produced (an ADR,
-  a skill body, a script's output) and the tests that pin it.
-- **`release:guard` red with "shipped delta has no version bump" is not a
-  failure of the wave** — it means the wave touched the shipped consumer set and
-  the release metadata is missing. See §Landing.
-- **A flaky red is possible.** `scripts/codex-exec.test.mjs` contains
-  timing-sensitive tests that fail under CPU contention (#345). Re-run the single
-  test in isolation before treating it as a real red; a test that is green in
-  isolation and red under load is contention, not the wave.
-
-## §Headless Login
-
-Not applicable. No application, no browser surface, no authenticated session.
-Never invent a login recipe for this repo.
-
-## §Landing
-
-**One PR for the whole wave**, base `main`. `main` is protected by the
-`main protection` ruleset: a PR is required, the CI job **`test`** (job name, not
-the workflow name `CI`) must be green with the branch up to date, and there are
-no bypass actors — `gh pr merge --admin` does not help.
-
-- `Closes #<n>` on its own line per leaf; `Part of #<anchor>` for the anchor,
-  never `closes`.
-- Body via temp file + `--body-file`, and **run `gh` from the repo** (it resolves
-  the target repo from the cwd).
-
-**Anchor reconcile, on PR create and on merge:**
-
-```sh
-python3 scripts/board-sync.py anchor-sync <anchor#> --dry-run   # review first
-python3 scripts/board-sync.py anchor-sync <anchor#>
-```
-
-`anchor-sync` only works on a **promoted** anchor whose body carries a slice
-table between `<!-- slice-table:start -->` and `<!-- slice-table:end -->`. A
-stub-shaped anchor (a bullet list of slices, `wave-stub` label) makes it a no-op
-that exits 1 with "no slice table found — nothing to sync". That is a promotion
-gap, not a sync failure: install the table with the columns
-`| # | Status | Slice | Sub-Issue | Gate | closes/refs |`, drop the `wave-stub`
-label, then re-run. Do not hand-maintain the Status cells afterwards — they are
-regenerated from the board.
-
-**Completion, after merge:**
-
-```sh
-python3 scripts/board-sync.py add --issue <anchor#> --status-role done
-gh issue close <anchor#> --reason completed --comment "…"
-python3 scripts/board-sync.py item-of --issue <anchor#>   # re-read: status must be Done
-python3 scripts/board-sync.py parent-of <anchor#>         # Program-PRD?
-python3 scripts/board-sync.py program-sync <prd#>         # after the anchor is Done
-```
-
-Closing the issue does **not** move the board field — set the field, then re-read
-both.
-
-**New issues** go through `python3 scripts/board-sync.py create --title … --body-file …`,
-never a bare `gh issue create`.
-
-### Release lockstep
-
-There is no deploy and no migration, but there **is** a publication gate, and a
-wave that touches the shipped consumer set (anything in the kit manifest —
-including `docs/adr/*` and `docs/research/*`) drags it along.
-
-1. `npm run release:prepare -- --base origin/main` reports the delta and a
-   `recommendedBump` without writing anything.
-2. **The confirmed Semver is the one human gate.** Ask, unless an explicit
-   end-to-end mandate covers release preparation. That confirmed version then
-   authorizes metadata, merge, tag *and* publish — do not ask again after merge.
-3. `npm run release:prepare -- --version <x.y.z>`, commit the bump.
-4. Merge the PR. Merging **integrates only**; it cannot publish.
-5. Verify on canonical `main`: tip == merge commit, `package.json` version
-   matches, no existing tag. Then `git tag -a v<x.y.z> <main-tip> -m "…"` and
-   push. The annotated tag on the `main` tip is the sole publication intent.
-6. **A red release run does not prove nothing was published.** Read
-   `npm view @ikon85/agent-workflow-kit version` and `gh release view v<x.y.z>`
-   directly, plus `npm run release:status` (cache-bypassing), before reacting.
-7. **Recovery is `gh workflow run release.yml -f tag=v<x.y.z>` on the existing
-   tag** — the reconciler is idempotent. **Never recover by bumping the version.**
-
-The release workflow runs the full suite *after* the tag is pushed, so a flaky
-test strands an already-published tag. That is the recovery path above, not a
-reason to re-tag.

package/docs/agents/skills/spec-self-critique.md

@@ -1,18 +0,0 @@
-<!-- setup-workflow: state=filled -->
-<!-- agent-workflow-kit: project-extension/v1; skill=spec-self-critique -->
-# Project layer — spec-self-critique
-
-The generic checklist owns the checks; `/retro` appends project-specific incidents below these stable anchors.
-
-## Point 1
-## Point 2
-## Point 3
-## Point 4
-## Point 5
-## Point 6
-## Point 7
-## Point 8
-## Point 9
-## Point 10
-## Point 11
-## Point 12

package/docs/agents/triage-labels.md

@@ -1,10 +0,0 @@
-<!-- setup-workflow: state=filled -->
-# Triage labels
-
-| Canonical role | Label in this repository | Meaning |
-|---|---|---|
-| `needs-info` | `needs-info` | Waiting for information from the reporter |
-| `ready-for-agent` | `ready-for-agent` | Fully specified and safe for an AFK agent |
-
-The board Status field owns `Idea`, `Triaged`, `Spec`, `In Progress`, `Review`, and `Done`. Close rejected work instead of adding a separate `wontfix` workflow label.
-

package/docs/conventions/spec-completeness.md

@@ -1,23 +0,0 @@
-<!-- setup-workflow: state=filled -->
-# Convention — Spec completeness before implementation
-
-## Self-Critique-Check
-
-**Trigger:** A spec states a concrete count, quantity, or `N of M` claim.
-
-**Check:** Is each number freshly derived from the source rather than estimated or recalled?
-
-**Korrektur:** Recount from code and replace the claim, or mark it explicitly as an implementation-time assumption.
-
-## Vertical-slice completeness
-
-Every user-facing slice is an outcome tracer, carries at least one acceptance criterion, names its estimated blast radius, and identifies seam ownership. Every prep slice names the omitted half and the later slice that closes it. `to-issues` must re-derive this readiness rather than trusting a pre-cut table.
-
-## Self-Critique-Check
-
-**Trigger:** A spec contains a wave/slice table or decomposes into multiple issues.
-
-**Check:** Are rows outcomes rather than layer names, and do enablers name the outcome wave that closes them?
-
-**Korrektur:** Reword or split layer-only rows and make every deferred half explicit.
-