okstra 0.186.7 → 0.187.0

package/dist/lib/python-command.mjs

@@ -0,0 +1,52 @@
+import { runInstalledScript, runPythonModule } from "./python-helper.mjs";
+import { resolvePaths } from "./paths.mjs";
+// 이 명령이 스스로 정하는 플래그. 사용자가 같은 플래그를 주면 주입값과
+// 충돌하므로 파이썬에 닿기 전에 exit 2 로 끊는다.
+function ownedFlags(spec) {
+    const fromPrefix = (spec.prefix ?? []).filter((token) => token.startsWith("--"));
+    const fromInject = (spec.inject ?? []).map((name) => `--${name}`);
+    return [...fromInject, ...fromPrefix];
+}
+function findForbidden(args, owned) {
+    return args.find((arg) => owned.some((flag) => arg === flag || arg.startsWith(`${flag}=`)));
+}
+// 레지스트리 한 줄을 실행 가능한 러너로 바꾼다. 명령마다 있던 포워더 파일이
+// 하던 일 — 인자 앞에 고정 argv 를 붙이고 python 을 띄우는 것 — 이 전부다.
+// `--help` 는 파이썬 argparse 에 그대로 도달한다: 도움말의 저자는 파이썬이다.
+export function makePythonRunner(name, spec) {
+    const owned = ownedFlags(spec);
+    return async (args) => {
+        const forbidden = findForbidden(args, owned);
+        if (forbidden !== undefined) {
+            process.stderr.write(`error: ${forbidden} is set by 'okstra ${name}' itself — remove it from your args\n`);
+            return 2;
+        }
+        const injected = [];
+        if (spec.inject?.length) {
+            const paths = await resolvePaths();
+            for (const which of spec.inject) {
+                injected.push(`--${which}`, which === "okstra-bin" ? paths.bin : paths.workspace);
+            }
+        }
+        injected.push(...(spec.prefix ?? []));
+        const argv = [...injected, ...args];
+        const target = spec.target;
+        if ("module" in target) {
+            const result = await runPythonModule({
+                module: target.module,
+                args: argv,
+                stdio: "inherit-stdout",
+            });
+            // runPythonModule 은 spawn 자체가 실패하면 -1 을 준다. 그대로 반환하면
+            // process.exit(-1) 이 255 로 나가므로, 설치된 스크립트를 띄우는 쪽과
+            // 같은 모양(에러 한 줄 + exit 1)으로 맞춘다.
+            if (result.code === -1) {
+                process.stderr.write(`error: failed to spawn python3: ${result.stderr}\n`);
+                return 1;
+            }
+            return result.code;
+        }
+        return await runInstalledScript({ scriptName: target.script, args: argv });
+    };
+}
+//# sourceMappingURL=python-command.mjs.map

package/dist/lib/python-command.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-command.mjs","sourceRoot":"","sources":["../../src/lib/python-command.mts"],"names":[],"mappings":"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"}

package/dist/lib/python-helper.d.mts

@@ -1,8 +1,5 @@
-import type { InstalledScriptOptions, InstalledValidatorOptions, JsonErrorOptions, ProcessResult, PythonModuleOptions, PythonSnippetOptions, RuntimePaths } from "./types.mjs";
+import type { InstalledScriptOptions, JsonErrorOptions, ProcessResult, PythonModuleOptions, RuntimePaths } from "./types.mjs";
 export declare function resolveInstalledScript(paths: RuntimePaths, scriptName: string): string | null;
-export declare function resolveInstalledValidator(paths: RuntimePaths, validatorName: string): string | null;
-export declare function runInstalledScript({ scriptName, args, usage, emptyArgsCode }: InstalledScriptOptions): Promise<number>;
-export declare function runInstalledValidator({ validatorName, args }: InstalledValidatorOptions): Promise<number>;
-export declare function runPythonSnippet({ script, args, extraEnv }: PythonSnippetOptions): Promise<ProcessResult>;
+export declare function runInstalledScript({ scriptName, args }: InstalledScriptOptions): Promise<number>;
 export declare function runPythonModule({ module, args, extraEnv, stdio }: PythonModuleOptions): Promise<ProcessResult>;
 export declare function emitJsonError({ stage, reason, extra }: JsonErrorOptions): void;

package/dist/lib/python-helper.mjs

@@ -14,16 +14,6 @@ export function resolveInstalledScript(paths, scriptName) {
     const dev = resolvePath(repoRoot, "scripts", scriptName);
     return existsSync(dev) ? dev : null;
 }
-export function resolveInstalledValidator(paths, validatorName) {
-    // `okstra install` lands the validators tree at ~/.okstra/lib/validators;
-    // a checkout that has not been installed still has the in-repo source.
-    const installed = join(paths.home, "lib", "validators", validatorName);
-    if (existsSync(installed))
-        return installed;
-    const repoRoot = fileURLToPath(new URL("../..", import.meta.url));
-    const dev = resolvePath(repoRoot, "validators", validatorName);
-    return existsSync(dev) ? dev : null;
-}
 async function spawnPythonEntry(entry, args, paths) {
     return await new Promise((resolve) => {
         const child = spawn("python3", [entry, ...args], {
@@ -42,18 +32,9 @@ async function spawnPythonEntry(entry, args, paths) {
 // and installed/dev resolution in one place so skills call `okstra <cmd>`
 // instead of emitting `python3 "$HOME/..."` (which breaks `Bash(okstra:*)`
 // permission matching and prompts on every call).
-export async function runInstalledScript({ scriptName, args, usage, emptyArgsCode = 2 }) {
-    if (args.length === 0) {
-        process.stdout.write(usage);
-        return emptyArgsCode;
-    }
-    // Only a bare `--help` / `-h` prints the wrapper usage. A `--help` that
-    // follows a subcommand (e.g. `error-log append-observed --help`) must reach
-    // the python helper so its own per-subcommand help shows through.
-    if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
-        process.stdout.write(usage);
-        return 0;
-    }
+//
+// `--help` 는 가로채지 않는다 — 도움말의 저자는 헬퍼 스크립트의 argparse 다.
+export async function runInstalledScript({ scriptName, args }) {
     const paths = await resolvePaths();
     const entry = resolveInstalledScript(paths, scriptName);
     if (!entry) {
@@ -62,36 +43,6 @@ export async function runInstalledScript({ scriptName, args, usage, emptyArgsCod
     }
     return await spawnPythonEntry(entry, args, paths);
 }
-export async function runInstalledValidator({ validatorName, args }) {
-    const paths = await resolvePaths();
-    const entry = resolveInstalledValidator(paths, validatorName);
-    if (!entry) {
-        process.stderr.write(`error: ${validatorName} not found — run 'okstra install' (or 'okstra ensure-installed') first\n`);
-        return 1;
-    }
-    return await spawnPythonEntry(entry, args, paths);
-}
-export async function runPythonSnippet({ script, args = [], extraEnv = {} }) {
-    const paths = await resolvePaths();
-    return new Promise((resolve) => {
-        const child = spawn("python3", ["-c", script, ...args], {
-            stdio: ["ignore", "pipe", "pipe"],
-            env: { ...process.env, PYTHONPATH: buildPythonpath(paths), ...extraEnv },
-        });
-        // Collect chunks and join once: repeated `s += chunk` is O(n^2) for the
-        // large rendered prompts some capture-mode callers stream through here.
-        const outChunks = [];
-        const errChunks = [];
-        child.stdout?.on("data", (b) => outChunks.push(b));
-        child.stderr?.on("data", (b) => errChunks.push(b));
-        child.on("error", (err) => resolve({ code: -1, stdout: Buffer.concat(outChunks).toString(), stderr: err.message }));
-        child.on("close", (code) => resolve({
-            code: typeof code === "number" ? code : 1,
-            stdout: Buffer.concat(outChunks).toString(),
-            stderr: Buffer.concat(errChunks).toString(),
-        }));
-    });
-}
 export async function runPythonModule({ module, args = [], extraEnv = {}, stdio = "inherit-stdout" }) {
     const paths = await resolvePaths();
     return new Promise((resolve) => {

package/dist/lib/python-helper.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"python-helper.mjs","sourceRoot":"","sources":["../../src/lib/python-helper.mts"],"names":[],"mappings":"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"}
+{"version":3,"file":"python-helper.mjs","sourceRoot":"","sources":["../../src/lib/python-helper.mts"],"names":[],"mappings":"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"}

package/dist/lib/runtime-payload.d.mts

@@ -0,0 +1,23 @@
+export interface RuntimeBinFile {
+    /** repo 기준 경로. `scripts/` 하위 파일 이름과 같아야 한다. */
+    readonly name: string;
+    /**
+     * `okstra <cmd>` 가 runInstalledScript() 로 앞세우는 파이썬 헬퍼인가.
+     * preflight 가 이 표시가 붙은 것들이 ~/.okstra/bin 에서 해석되는지 검사한다.
+     * tests-js 의 계약 테스트가 이 표시를 실제 `scriptName:` 리터럴과 맞춘다.
+     */
+    readonly helper?: boolean;
+}
+/** `scripts/` 아래에서 `runtime/bin/` 으로 그대로 배포되는 실행 파일들. */
+export declare const RUNTIME_BIN_FILES: readonly RuntimeBinFile[];
+/** `scripts/` 아래에서 `runtime/python/` 으로 배포되는 파이썬 패키지들. */
+export declare const RUNTIME_PYTHON_PACKAGES: readonly string[];
+/**
+ * repo 디렉터리 → runtime 디렉터리. bin/lib 는 okstra.sh 가
+ * `$SCRIPT_DIR/lib/okstra/*.sh` 로 source 하므로 python/ 이 아니라 bin/ 아래여야 한다.
+ */
+export declare const RUNTIME_DIR_SYNCS: readonly (readonly [string, string])[];
+/** `okstra install` 이 dev-link 모드에서 개별 심링크로 거는 이름들. */
+export declare const BIN_ENTRYPOINT_NAMES: readonly string[];
+/** preflight 가 ~/.okstra/bin 에서 해석되는지 확인하는 파이썬 헬퍼들. */
+export declare const HELPER_SCRIPT_NAMES: readonly string[];

package/dist/lib/runtime-payload.mjs

@@ -0,0 +1,57 @@
+// 배포 payload 의 단일 기준점.
+//
+// 예전에는 같은 이름 목록이 세 곳에 손으로 복사돼 있었다 —
+// tools/build.mjs 의 SYNCS, install.mts 의 BIN_ENTRYPOINTS,
+// helper-scripts.mts 의 HELPER_SCRIPT_NAMES. 셋이 어긋나도 아무것도 잡지 못했고,
+// 실제로 어긋나 있었다(예: report-translate·incremental-* 는 SYNCS 로 배포되지만
+// BIN_ENTRYPOINTS 에는 없어 dev-link 설치에서 심링크되지 않았다).
+//
+// 이제 목록은 여기 하나이고 나머지 셋은 여기서 파생된다.
+/** `scripts/` 아래에서 `runtime/bin/` 으로 그대로 배포되는 실행 파일들. */
+export const RUNTIME_BIN_FILES = Object.freeze([
+    { name: "okstra.sh" },
+    { name: "okstra-codex-exec.sh" },
+    { name: "okstra-claude-exec.sh" },
+    { name: "okstra-antigravity-exec.sh" },
+    { name: "okstra-grok-exec.sh" },
+    { name: "okstra-kimi-exec.sh" },
+    { name: "okstra-provider-exec.py" },
+    // 진입 스크립트들이 import 하는 경로 부트스트랩. 이들과 같은
+    // 디렉터리에 있어야 `sys.path` 를 고치기 전에 import 된다.
+    { name: "okstra_bootstrap.py" },
+    { name: "okstra-import-check.py" },
+    { name: "okstra-compact-reminder.sh" },
+    { name: "okstra-wrapper-status.py" },
+    { name: "okstra-error-log.py", helper: true },
+    { name: "okstra-inject-report-index.py", helper: true },
+    { name: "okstra-render-final-report.py", helper: true },
+    { name: "okstra-render-report-views.py", helper: true },
+    { name: "okstra-report-translate.py", helper: true },
+    { name: "okstra-spawn-followups.py", helper: true },
+    { name: "okstra-token-usage.py", helper: true },
+]);
+/** `scripts/` 아래에서 `runtime/python/` 으로 배포되는 파이썬 패키지들. */
+export const RUNTIME_PYTHON_PACKAGES = Object.freeze([
+    "okstra_project",
+    "okstra_ctl",
+    "okstra_token_usage",
+    "okstra_vendor",
+]);
+/**
+ * repo 디렉터리 → runtime 디렉터리. bin/lib 는 okstra.sh 가
+ * `$SCRIPT_DIR/lib/okstra/*.sh` 로 source 하므로 python/ 이 아니라 bin/ 아래여야 한다.
+ */
+export const RUNTIME_DIR_SYNCS = Object.freeze([
+    ["scripts/lib/okstra", "bin/lib/okstra"],
+    ["agents", "agents"],
+    ["prompts", "prompts"],
+    ["schemas", "schemas"],
+    ["templates", "templates"],
+    ["validators", "validators"],
+    ["skills", "skills"],
+]);
+/** `okstra install` 이 dev-link 모드에서 개별 심링크로 거는 이름들. */
+export const BIN_ENTRYPOINT_NAMES = Object.freeze(RUNTIME_BIN_FILES.map((entry) => entry.name));
+/** preflight 가 ~/.okstra/bin 에서 해석되는지 확인하는 파이썬 헬퍼들. */
+export const HELPER_SCRIPT_NAMES = Object.freeze(RUNTIME_BIN_FILES.filter((entry) => entry.helper).map((entry) => entry.name));
+//# sourceMappingURL=runtime-payload.mjs.map

package/dist/lib/runtime-payload.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-payload.mjs","sourceRoot":"","sources":["../../src/lib/runtime-payload.mts"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,EAAE;AACF,oCAAoC;AACpC,0DAA0D;AAC1D,iEAAiE;AACjE,gEAAgE;AAChE,kDAAkD;AAClD,EAAE;AACF,kCAAkC;AAalC,yDAAyD;AACzD,MAAM,CAAC,MAAM,iBAAiB,GAA8B,MAAM,CAAC,MAAM,CAAC;IACxE,EAAE,IAAI,EAAE,WAAW,EAAE;IACrB,EAAE,IAAI,EAAE,sBAAsB,EAAE;IAChC,EAAE,IAAI,EAAE,uBAAuB,EAAE;IACjC,EAAE,IAAI,EAAE,4BAA4B,EAAE;IACtC,EAAE,IAAI,EAAE,qBAAqB,EAAE;IAC/B,EAAE,IAAI,EAAE,qBAAqB,EAAE;IAC/B,EAAE,IAAI,EAAE,yBAAyB,EAAE;IACnC,uCAAuC;IACvC,2CAA2C;IAC3C,EAAE,IAAI,EAAE,qBAAqB,EAAE;IAC/B,EAAE,IAAI,EAAE,wBAAwB,EAAE;IAClC,EAAE,IAAI,EAAE,4BAA4B,EAAE;IACtC,EAAE,IAAI,EAAE,0BAA0B,EAAE;IACpC,EAAE,IAAI,EAAE,qBAAqB,EAAE,MAAM,EAAE,IAAI,EAAE;IAC7C,EAAE,IAAI,EAAE,+BAA+B,EAAE,MAAM,EAAE,IAAI,EAAE;IACvD,EAAE,IAAI,EAAE,+BAA+B,EAAE,MAAM,EAAE,IAAI,EAAE;IACvD,EAAE,IAAI,EAAE,+BAA+B,EAAE,MAAM,EAAE,IAAI,EAAE;IACvD,EAAE,IAAI,EAAE,4BAA4B,EAAE,MAAM,EAAE,IAAI,EAAE;IACpD,EAAE,IAAI,EAAE,2BAA2B,EAAE,MAAM,EAAE,IAAI,EAAE;IACnD,EAAE,IAAI,EAAE,uBAAuB,EAAE,MAAM,EAAE,IAAI,EAAE;CAChD,CAAC,CAAC;AAEH,0DAA0D;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACtE,gBAAgB;IAChB,YAAY;IACZ,oBAAoB;IACpB,eAAe;CAChB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA2C,MAAM,CAAC,MAAM,CAAC;IACrF,CAAC,oBAAoB,EAAE,gBAAgB,CAAC;IACxC,CAAC,QAAQ,EAAE,QAAQ,CAAC;IACpB,CAAC,SAAS,EAAE,SAAS,CAAC;IACtB,CAAC,SAAS,EAAE,SAAS,CAAC;IACtB,CAAC,WAAW,EAAE,WAAW,CAAC;IAC1B,CAAC,YAAY,EAAE,YAAY,CAAC;IAC5B,CAAC,QAAQ,EAAE,QAAQ,CAAC;CACZ,CAAC,CAAC;AAEZ,uDAAuD;AACvD,MAAM,CAAC,MAAM,oBAAoB,GAAsB,MAAM,CAAC,MAAM,CAClE,iBAAiB,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAC7C,CAAC;AAEF,uDAAuD;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAsB,MAAM,CAAC,MAAM,CACjE,iBAAiB,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAC7E,CAAC"}

package/dist/lib/types.d.mts

@@ -3,7 +3,6 @@ export type CommandRunner = (args: CliArgs) => Promise<number>;
 export type CommandCategory = "admin" | "introspection";
 export interface HostCapabilities {
     readonly claudeSkillHandoff?: boolean;
-    readonly tmuxAvailable?: boolean;
 }
 export interface RuntimeEnvironment {
     readonly OKSTRA_RUNTIME_HOST?: string;
@@ -49,13 +48,31 @@ export interface HostResolveOptions {
     readonly env?: RuntimeEnvironment;
     readonly capabilities?: HostCapabilities;
 }
-export interface CommandDefinition {
+export type PythonTarget = {
+    readonly module: string;
+} | {
+    readonly script: string;
+};
+export type PythonInjectedPath = "workspace-root" | "okstra-bin";
+export interface PythonCommandSpec {
+    readonly target: PythonTarget;
+    readonly prefix?: readonly string[];
+    readonly inject?: readonly PythonInjectedPath[];
+}
+export interface NodeCommandDefinition {
     readonly name: string;
     readonly module: string;
     readonly export: string;
     readonly category: CommandCategory;
     readonly summary: readonly string[];
 }
+export interface PythonCommandDefinition {
+    readonly name: string;
+    readonly python: PythonCommandSpec;
+    readonly category: CommandCategory;
+    readonly summary: readonly string[];
+}
+export type CommandDefinition = NodeCommandDefinition | PythonCommandDefinition;
 export interface RuntimePaths {
     readonly agents: string;
     readonly workspace: string;
@@ -78,20 +95,9 @@ export interface PythonModuleOptions {
     readonly extraEnv?: Readonly<Record<string, string | undefined>>;
     readonly stdio?: "capture" | "inherit-stdout";
 }
-export interface PythonSnippetOptions {
-    readonly script: string;
-    readonly args?: CliArgs;
-    readonly extraEnv?: Readonly<Record<string, string | undefined>>;
-}
 export interface InstalledScriptOptions {
     readonly scriptName: string;
     readonly args: CliArgs;
-    readonly usage: string;
-    readonly emptyArgsCode?: number;
-}
-export interface InstalledValidatorOptions {
-    readonly validatorName: string;
-    readonly args: CliArgs;
 }
 export interface JsonErrorOptions {
     readonly stage: string;
@@ -119,6 +125,11 @@ export interface InstalledAssets {
     readonly schemas: boolean;
     readonly validators: boolean;
 }
+export interface SkillTarget {
+    readonly provider: string;
+    readonly root: string;
+    readonly skills: readonly string[];
+}
 export interface RuntimeManifest {
     readonly schemaVersion: number;
     readonly installedAt: string;

package/docs/architecture/storage-model.md

@@ -21,7 +21,6 @@ The task manifest, task index, instruction set, runs, and history are collected
     - `clarification-response.md`, the user's carried-in clarification answers, when the run has any
     - `selected-direction.json`, the validated implementation direction snapshot for a new `implementation-planning` run
     - `final-report-schema.json`, `final-report-template.md`
-    - canonical `lead-execution-prompt.md` plus the `claude-execution-prompt.md` compatibility alias
   - `runs/<task-type>/`
     - `manifests/run-manifest-<task-type>-<seq>.json`
     - `state/team-state-<task-type>-<seq>.json`
@@ -57,7 +56,7 @@ The representative files below are all relative to the resolved run directory (`
 
 - `manifests/run-manifest-<task-type>-<seq>.json`
 - `state/team-state-<task-type>-<seq>.json`
-- `prompts/lead-execution-prompt-<task-type>-<seq>.md` *(canonical; the Claude-named snapshot remains a compatibility alias)*
+- `prompts/lead-execution-prompt-<task-type>-<seq>.md` *(the only lead prompt file; the run manifest's `resources.claudeExecutionPromptPath` is a key alias resolving to it)*
 - `prompts/<worker>-worker-prompt-<task-type>-<seq>.md`
 - `prompts/<prompt>.md.meta.json` *(invocation identity, assignment, duty identity, source paths, and the five catalog/assignment/duty/instruction/prompt digests)*
 - `prompts/duty-contracts-<task-type>-<seq>/` *(run-scoped snapshot; dispatch verification rejects drift from its catalog digest)*
@@ -171,6 +170,24 @@ Each wrapper `<prompt>.log` beside a persisted `<prompt>.md` is a growing execut
 When the same non-stage task type runs again, it reuses the same `runs/<task-type>/` run directory. Reruns of `implementation` and single-stage `final-verification` reuse their resolved `runs/<task-type>/stage-<N>/` run directories. In both cases, existing artifacts are not overwritten because run-level filenames are separated by `-<task-type>-<seq>` suffixes within type-specific subdirectories. Because `<seq>` is scanned independently for each category directory (`manifests/`, `prompts/`, `reports/`, `status/`, `state/`, `sessions/`, `worker-results/`) beneath the resolved run directory, values may differ by category even within the same run.
 If flat legacy artifacts remain at the top level of a task-type run directory, the next execution automatically moves them into the corresponding type-specific subdirectories.
 
+#### Rerun archive
+
+Because a rerun reuses the run directory, prior-sequence artifacts pile up in place. A task that re-ran `implementation-planning` twenty-four times left over two hundred files in one `worker-results/`, and checks that glob that directory counted another run's files as this run's — their failure counts grew from 30 to 140 across the reruns.
+
+Prepare therefore moves prior-sequence artifacts out of the two directories no consumer reads across sequences:
+
+```text
+runs/<task-type>/archive/run-<seq>/worker-results/…
+runs/<task-type>/archive/run-<seq>/prompts/…
+runs/<task-type>/archive/README.md
+```
+
+- **Rotated:** `worker-results/` and `prompts/`. Their only readers (`run_audit`, `context_cost`, the plan-body provenance check) scope themselves to the current run's sequence already; `okstra log-report` still counts archived wrapper transcripts because it matches on path components rather than depth.
+- **Not rotated:** `reports/`, `manifests/`, `state/`, `status/`, `sessions/`, `logs/`, `carry/`, and `user-responses/`. `state/` is read across sequences by `okstra plan-items seed --prior-state`, by the prior-planning summary, and by `okstra time-report`; `logs/` is globbed one level deep as `runs/*/logs/errors-*.jsonl` by `okstra error-report`, `okstra error-zip`, and prepare's own prior-run error digest, so an archived path would silently drop from all three.
+- **Retention floor:** the sequence the latest published report's run manifest recorded for that category (`runSequencesByCategory`). That sequence and everything above it stay in place; only older sequences move. When the report-to-manifest mapping cannot be resolved, nothing moves.
+- The move never deletes, never overwrites an existing archive entry, and never touches an entry without a `-<task-type>-<seq>` suffix (`prompts/.agent-invocations/` stays put). Because the retention floor is always at or below the directory's highest sequence, sequence allocation still sees the same maximum and stays monotonic.
+- `archive/README.md` is rewritten on each rotation with what moved, from which sequence, the retention floor used, and how to restore.
+
 ### 3. Project-level discovery and installed skill assets
 Shared project discovery pointers are created at the following paths.
 
@@ -253,8 +270,7 @@ Examples of key fields:
 - `workflow.currentPhaseState`
 - `workflow.phaseStates`
 - `workflow.lastCompletedPhase`
-- `workflow.nextRecommendedPhase` *(object `{phase, status, rationale}`; `status` is `ready` / `pending` / `blocked` / `terminal`. The lead writes `phase` only under `ready` — an authoring rule, not a constraint the struct enforces: `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a stored non-`ready` pointer that still names a phase is a normal manifest state. Read `status` to decide whether anything can be launched.)*
-- `workflow.nextRecommendedPhaseCorrection` *(present only when Phase 7 validation replaced the authored pointer — `{authored, applied}`)*
+- `workflow.nextRecommendedPhase` *(object `{phase, status, rationale}`; `status` is `ready` / `pending` / `blocked` / `terminal`. `phase` is non-empty only under `ready` — a property of the projection, not a constraint the struct enforces: `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a stored non-`ready` pointer that still names a phase is a normal manifest state. Read `status` to decide whether anything can be launched.)*
 - `workflow.awaitingApproval`
 - `workflow.lastSafeCheckpoint`
 - `phaseOutcome` *(artifact-derived semantic phase outcome; for example, when the implementation carry proves that all stages passed, the implementation phase outcome may be recorded as completed even if run contract validation failures remain)*
@@ -380,7 +396,7 @@ Convergence keeps its decision trail under the run's `state/` directory:
 - `state/convergence-work-<task-type>-<seq>.json` — engine-owned queue, finding state, and round history.
 - `state/convergence-round-<N>-plan-<task-type>-<seq>.json` — immutable roster-aware dispatch plan for one round.
 - `state/convergence-round-<N>-results-<task-type>-<seq>.json` — adapter outcomes and parsed votes supplied to the reducer.
-- `state/convergence-<task-type>-<seq>.json` — validated terminal schema v1.2 state consumed by reporting and Phase 7.
+- `state/convergence-<task-type>-<seq>.json` — validated terminal schema v1.4 state consumed by reporting and Phase 7. Historical v1.0-v1.3 artifacts are read as they are.
 - `state/migrations/` — byte-for-byte archives of invalid or partial legacy state replaced during an explicit Round 0 restart.
 
 A valid terminal legacy final is reused unchanged, and a matching valid working state resumes. Invalid new-engine working state fails closed unless seeding receives `--restart-from-round0`; an existing final can be replaced only when its migration archive still matches its original bytes.