yam-flow 2.3.0 → 2.3.1

package/AGENTS.md

@@ -21,3 +21,21 @@
 19. Treat security as the first project lens: identify sensitive surfaces early and guide safer defaults before convenience.
 20. Keep final reports short and concrete, but always include remaining tasks or state that none are meaningful.
 21. When relevant, include architecture hygiene in the Study Note: avoid dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs when existing project boundaries, scoped styles, typed tables, constraints, or indexes fit better.
+
+## Latest Update Trigger
+
+When the user says exactly `yam 최신 업데이트 사항 반영해줘` in a chat for this project, treat that phrase as explicit authorization to update the globally installed package and refresh the installed yam skills.
+
+Run these commands sequentially from the yam project directory:
+
+```bash
+npm install -g yam-flow
+yam install
+yam version
+yam status
+```
+
+- Request any environment approval required for network access or writes outside the workspace.
+- Stop at the first failed command, report the blocker, and do not claim that later steps ran.
+- After all four commands pass, report the installed version and skill status, then tell the user that Codex can be restarted to reload the updated skills.
+- Do not restart Codex automatically.

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.3.1 - 2026-07-21
+
+### Added
+
+- Added a transactional skill installer that stages and SHA-256 verifies the complete managed skill set before replacing the active installation.
+- Added `yam.install-receipt.v1` with the installed package version, source identity, timestamp, destination, skill inventory, per-file hashes, and aggregate source digest.
+- Added deterministic install transaction smoke coverage for successful commit, forced mid-commit rollback, drift detection and repair, mirror cleanup, and concurrent-install locking.
+
+### Improved
+
+- `yam status` now detects missing files, unexpected files, hash drift, receipt drift, and package-version drift instead of checking only for `SKILL.md` and `references/` existence.
+- Failed commits restore the previous managed skill set and receipt; legacy and retired skill cleanup now participates in the same rollback boundary.
+- Unfinished transaction artifacts are surfaced by `yam status` and block a new install so recovery backups are not silently overwritten.
+- `yam uninstall` removes the install receipt and refuses to run while an install lock is present.
+
+### Verification
+
+- `npm run verify:self`
+- `npm run dist:freshness`
+- `npm run package-boundary:check`
+- `npm run cli-smoke`
+
 ## v2.3.0 - 2026-07-13
 
 ### Added

package/README.md

@@ -96,21 +96,13 @@ cd ~/Documents/Codex/tools/yam
 yam install
 ```
 
-This copies each skill plus the shared `references/` directory into `~/.agents/skills/`, which is the user skill root used by this Codex desktop setup.
+`yam install` stages every managed skill plus the shared `references/` directory, verifies the complete staged file manifest with SHA-256, and only then replaces the active set in `~/.agents/skills/`. If any commit or post-install verification step fails, yam restores the previous managed skill set and receipt.
 
-Manual install is also possible by copying selected skill folders into your active Codex user skill root, but make sure each installed skill also receives a `references/` folder.
+A successful install writes `~/.agents/skills/.yam-flow-install-receipt.json`. The receipt records the package version, source identity, install timestamp, destination, managed skill inventory, and per-file hashes. `yam status` independently recomputes source and installed hashes, so a stale package install, local file change, unexpected file, or modified receipt is reported as drift.
 
-Recommended v0:
+An ordinary install error rolls back automatically. An abrupt process or machine termination can leave `.yam-flow-install.lock` and a hidden transaction directory; `yam status` surfaces the unfinished transaction and yam refuses another mutation while recovery state remains. Remove the lock only after confirming no install is running, and preserve any transaction directory until the previous installation state has been inspected.
 
-```bash
-mkdir -p ~/.agents/skills
-for skill in quick ueye question scout deep mission; do
-  rm -rf "$HOME/.agents/skills/$skill"
-  mkdir -p "$HOME/.agents/skills/$skill"
-  cp "skills/$skill/SKILL.md" "$HOME/.agents/skills/$skill/SKILL.md"
-  cp -R references "$HOME/.agents/skills/$skill/references"
-done
-```
+Manual copying can still make a skill loadable, but it intentionally remains unverified: without a matching receipt, `yam status` exits non-zero and recommends `yam install`.
 
 Restart Codex after installing so skills reload.
 
@@ -187,6 +179,8 @@ npm install -g yam-flow
 yam status
 ```
 
+After `yam status` reports all skills and the install receipt as `ok`, restart Codex so the refreshed skills reload.
+
 Publishing still requires confirming the final npm package name and account access.
 
 ## Trust Kernel

package/ROADMAP.md

@@ -8,6 +8,7 @@ Implemented:
 - Six routes: quick, ueye, question, scout, deep, mission.
 - Shared references.
 - Local CLI: list, status, verify, doctor, examples, path, install, uninstall.
+- Transactional skill install with rollback, SHA-256 receipt, install lock, and status drift detection. Done.
 - CLI helpers: detect, budget, template, tune-log, version.
 - Optional advisory `yam-lite` hook with status/enable/disable. Done.
 - Opt-in project memory: init, add, list, summary, resolve.
@@ -94,6 +95,7 @@ Tasks:
 
 - Add symlink-friendly local install.
 - Add version command. Done.
+- Add staged transactional install, rollback, receipt, and drift-aware status. Done.
 - Consider npm packaging only after route behavior stabilizes.
 
 ### 8. Scout / Research Workflow

package/dist/bin/yam.js

@@ -9,6 +9,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { TRUTH_STATUSES, buildLoopReport, buildMediaGenerationProof, buildMissionCompletionGate, buildMissionPatchEnvelope, buildMissionSubagentReceipt, buildRollbackHint, buildRuntimeBackendEvidence, buildStudyNote, buildUeyeDesignCompletionGate, buildUeyeVisualProvenance, buildUeyeRunReport, buildUeyeSurfaceContext, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
 import { archiveUeyeRevision, inspectImageFile, upsertUeyeAsset, verifyUeyeAssetManifest, verifyUeyeRevisionHistory } from '../lib/ueye-artifacts.js';
+import { INSTALL_LOCK_NAME, INSTALL_RECEIPT_NAME, inspectSkillInstallation, installSkillSetTransactional } from '../lib/skill-installation.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -167,73 +168,77 @@ async function exists(file) {
 async function rmrf(target) {
     await fsp.rm(target, { recursive: true, force: true });
 }
-async function copyDir(source, target) {
-    await fsp.mkdir(target, { recursive: true });
-    const entries = await fsp.readdir(source, { withFileTypes: true });
-    for (const entry of entries) {
-        const from = path.join(source, entry.name);
-        const to = path.join(target, entry.name);
-        if (entry.isDirectory()) {
-            await copyDir(from, to);
-        }
-        else if (entry.isFile()) {
-            await fsp.copyFile(from, to);
-        }
-    }
-}
-async function installSkill(skill) {
-    const source = path.join(ROOT, 'skills', skill);
-    const target = path.join(DEST, skill);
-    const references = path.join(ROOT, 'references');
-    if (!await exists(path.join(source, 'SKILL.md'))) {
-        throw new Error(`missing skill source: ${source}`);
-    }
-    await rmrf(target);
-    await fsp.mkdir(target, { recursive: true });
-    await fsp.copyFile(path.join(source, 'SKILL.md'), path.join(target, 'SKILL.md'));
-    await copyDir(references, path.join(target, 'references'));
-}
 async function install() {
-    await fsp.mkdir(DEST, { recursive: true });
-    for (const skill of SKILLS) {
-        await installSkill(skill);
-    }
-    for (const legacySkill of LEGACY_SKILLS) {
-        await rmrf(path.join(DEST, legacySkill));
-    }
-    for (const retiredSkill of RETIRED_SKILLS) {
-        await rmrf(path.join(DEST, retiredSkill));
-    }
-    if (CODEX_MIRROR !== DEST && fs.existsSync(CODEX_MIRROR)) {
-        for (const skill of [...SKILLS, ...LEGACY_SKILLS, ...RETIRED_SKILLS]) {
-            await rmrf(path.join(CODEX_MIRROR, skill));
-        }
-    }
+    const result = await installSkillSetTransactional({
+        sourceRoot: ROOT,
+        destination: DEST,
+        codexMirror: CODEX_MIRROR,
+        packageName: String(PACKAGE_JSON.name || 'yam-flow'),
+        version: VERSION,
+        skills: SKILLS,
+        legacySkills: LEGACY_SKILLS,
+        retiredSkills: RETIRED_SKILLS
+    });
     console.log(`yam installed to ${DEST}`);
+    console.log(`install receipt: ${result.receiptPath}`);
+    console.log(`integrity: ${result.installedFiles} files, sha256:${result.sourceDigest}`);
+    for (const warning of result.cleanupWarnings)
+        console.warn(`warning: ${warning}`);
     console.log('Restart Codex to reload skills.');
 }
 async function uninstall() {
+    const lockPath = path.join(DEST, INSTALL_LOCK_NAME);
+    if (await exists(lockPath)) {
+        throw new Error(`cannot uninstall while an install lock exists: ${lockPath}`);
+    }
     for (const skill of [...SKILLS, ...LEGACY_SKILLS, ...RETIRED_SKILLS]) {
         await rmrf(path.join(DEST, skill));
         if (CODEX_MIRROR !== DEST) {
             await rmrf(path.join(CODEX_MIRROR, skill));
         }
     }
+    await rmrf(path.join(DEST, INSTALL_RECEIPT_NAME));
     console.log(`yam removed from ${DEST}`);
     if (CODEX_MIRROR !== DEST)
         console.log(`yam mirror entries removed from ${CODEX_MIRROR}`);
     console.log('Restart Codex to unload skills.');
 }
 async function status({ quiet = false } = {}) {
-    let missing = 0;
-    for (const skill of SKILLS) {
-        const ok = await exists(path.join(DEST, skill, 'SKILL.md')) && await exists(path.join(DEST, skill, 'references'));
-        if (!quiet)
-            console.log(`${ok ? 'ok     ' : 'missing'} ${skill}`);
-        if (!ok)
-            missing += 1;
+    const report = await inspectSkillInstallation({
+        sourceRoot: ROOT,
+        destination: DEST,
+        packageName: String(PACKAGE_JSON.name || 'yam-flow'),
+        version: VERSION,
+        skills: SKILLS
+    });
+    if (!quiet) {
+        for (const skill of report.skills) {
+            const label = skill.status === 'ok' ? 'ok     ' : skill.status === 'missing' ? 'missing' : 'drift  ';
+            console.log(`${label} ${skill.skill}`);
+        }
+        if (report.receiptStatus === 'ok' && report.receipt) {
+            console.log(`ok      install receipt ${report.receipt.package.name}@${report.receipt.package.version}`);
+            console.log(`        sha256:${report.receipt.integrity.source_digest}`);
+        }
+        else {
+            console.log(`${report.receiptStatus === 'missing' ? 'missing' : 'drift  '} install receipt`);
+        }
+        if (report.issues.length) {
+            console.log('');
+            console.log('Install integrity issues:');
+            for (const issue of report.issues.slice(0, 12))
+                console.log(`- ${issue}`);
+            if (report.issues.length > 12)
+                console.log(`- ... ${report.issues.length - 12} more issue(s)`);
+            if (report.recoveryArtifacts.length) {
+                console.log('Confirm no install is running, then inspect and preserve the transaction backup before retrying.');
+            }
+            else {
+                console.log('Run `yam install` to restore the package-bundled skill set.');
+            }
+        }
     }
-    return missing;
+    return report.ok ? 0 : Math.max(1, report.issues.length);
 }
 async function list() {
     const manifest = await loadManifest();
@@ -279,6 +284,8 @@ async function verify({ quiet = false } = {}) {
         return failOrReport('yam verify', issues, quiet);
     if (manifest.name !== 'yam')
         issues.push('manifest name must be yam');
+    if (manifest.version !== VERSION)
+        issues.push(`manifest version must match package version: ${manifest.version || 'missing'} != ${VERSION}`);
     if (manifest.defaultHooks !== false)
         issues.push('manifest defaultHooks must be false');
     if (!Array.isArray(manifest.routes) || manifest.routes.length !== SKILLS.length) {

package/dist/lib/skill-installation.d.ts

@@ -0,0 +1,76 @@
+export declare const INSTALL_RECEIPT_NAME = ".yam-flow-install-receipt.json";
+export declare const INSTALL_LOCK_NAME = ".yam-flow-install.lock";
+export declare const INSTALL_RECEIPT_SCHEMA = "yam.install-receipt.v1";
+export declare const INSTALL_TRANSACTION_PREFIX = ".yam-flow-install-";
+export type InstallFileDigest = {
+    path: string;
+    bytes: number;
+    sha256: string;
+};
+export type InstallReceipt = {
+    schema: typeof INSTALL_RECEIPT_SCHEMA;
+    package: {
+        name: string;
+        version: string;
+    };
+    source: {
+        kind: 'package-bundled-skills';
+        identity: string;
+    };
+    destination: string;
+    installed_at: string;
+    transaction_id: string;
+    skills: string[];
+    integrity: {
+        algorithm: 'sha256';
+        file_count: number;
+        source_digest: string;
+        files: InstallFileDigest[];
+    };
+};
+export type InstallFailpointEvent = {
+    phase: 'after-stage' | 'after-backup' | 'skill-installed' | 'receipt-installed' | 'mirror-cleaned' | 'before-verify';
+    skill?: string;
+};
+export type TransactionalInstallOptions = {
+    sourceRoot: string;
+    destination: string;
+    codexMirror?: string;
+    packageName: string;
+    version: string;
+    skills: string[];
+    legacySkills?: string[];
+    retiredSkills?: string[];
+    now?: () => Date;
+    transactionId?: string;
+    failpoint?: (event: InstallFailpointEvent) => void | Promise<void>;
+};
+export type InstallationInspectionOptions = Pick<TransactionalInstallOptions, 'sourceRoot' | 'destination' | 'packageName' | 'version' | 'skills'> & {
+    ignoreRecoveryArtifacts?: boolean;
+};
+export type SkillInstallStatus = {
+    skill: string;
+    status: 'ok' | 'missing' | 'drift';
+    issues: string[];
+};
+export type InstallationInspection = {
+    ok: boolean;
+    destination: string;
+    receiptPath: string;
+    receiptStatus: 'ok' | 'missing' | 'drift';
+    receipt?: InstallReceipt;
+    sourceDigest?: string;
+    recoveryArtifacts: string[];
+    skills: SkillInstallStatus[];
+    issues: string[];
+};
+export type TransactionalInstallResult = {
+    receipt: InstallReceipt;
+    receiptPath: string;
+    installedFiles: number;
+    sourceDigest: string;
+    cleanupWarnings: string[];
+};
+export declare function findInstallRecoveryArtifacts(root: string): Promise<string[]>;
+export declare function inspectSkillInstallation(options: InstallationInspectionOptions): Promise<InstallationInspection>;
+export declare function installSkillSetTransactional(options: TransactionalInstallOptions): Promise<TransactionalInstallResult>;