The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix: preflight and document snapshot storage capability
haelyrabded8387ebe8
diff --git a/commands/skill-health.md b/commands/skill-health.mdindex 67c27c795..266a0ce6a 100644--- a/commands/skill-health.md+++ b/commands/skill-health.md@@ -52,3 +52,7 @@ node "$ECC_ROOT/scripts/skills-health.js" --dashboard --json- **Failure Patterns** — Clustered failure reasons with horizontal bar chart- **Pending Amendments** — Amendment proposals awaiting review- **Version History** — Timeline of version snapshots per skill++## Snapshot storage++Snapshot creation and rollback require writable storage with hardlink support. The versioning API checks that capability before creating or changing version history and refuses unsupported storage without a copy fallback. Use a hardlink-capable location for new snapshots. Reading existing health and version history does not require creating hard links.diff --git a/docs/ja-JP/commands/skill-health.md b/docs/ja-JP/commands/skill-health.mdindex 876ac5247..566b6a1dd 100644--- a/docs/ja-JP/commands/skill-health.md+++ b/docs/ja-JP/commands/skill-health.md@@ -52,3 +52,7 @@ node "$ECC_ROOT/scripts/skills-health.js" --dashboard --json- **失敗パターン** — 水平バーチャート付きのクラスタ化された失敗理由- **保留中の修正案** — レビュー待ちの修正提案- **バージョン履歴** — スキルごとのバージョンスナップショットのタイムライン++## スナップショットの保存先++スナップショットの作成とロールバックには、ハードリンクを作成できる書き込み可能な保存先が必要です。バージョン管理 API は履歴を作成または変更する前にこの機能を確認し、未対応の保存先ではコピーへのフォールバックを行わず拒否します。新しいスナップショットにはハードリンク対応の保存先を使用してください。既存のヘルス情報やバージョン履歴の読み取りでは、ハードリンクの作成は不要です。diff --git a/docs/zh-CN/commands/skill-health.md b/docs/zh-CN/commands/skill-health.mdindex 6471108aa..c7b14696a 100644--- a/docs/zh-CN/commands/skill-health.md+++ b/docs/zh-CN/commands/skill-health.md@@ -52,3 +52,7 @@ node "$ECC_ROOT/scripts/skills-health.js" --dashboard --json* **故障模式** — 聚类故障原因并显示水平条形图* **待处理修订** — 等待审查的修订提案* **版本历史** — 每个技能的版本快照时间线++## 快照存储++创建快照和回滚需要支持硬链接的可写存储。版本管理 API 会在创建或修改版本历史前检查该能力;不支持时会拒绝操作,不会回退到复制文件。新快照应存放在支持硬链接的位置。读取现有健康信息和版本历史不需要创建硬链接。diff --git a/scripts/lib/skill-evolution/versioning.js b/scripts/lib/skill-evolution/versioning.jsindex 05205c12d..349b49b1b 100644--- a/scripts/lib/skill-evolution/versioning.js+++ b/scripts/lib/skill-evolution/versioning.js@@ -231,8 +231,8 @@ function removeOwnedStaging(staging, contentIdentity) {fs.rmdirSync(staging.path);}-function prepareStaging(versionsDir) {- const stagingDir = fs.mkdtempSync(path.join(versionsDir, '.snapshot-'));+function prepareStaging(versionsDir, prefix = '.snapshot-') {+ const stagingDir = fs.mkdtempSync(path.join(versionsDir, prefix));try {return { path: stagingDir, contentPath: path.join(stagingDir, 'content.md'), identity: fs.lstatSync(stagingDir) };} catch (primaryError) {@@ -244,10 +244,54 @@ function prepareStaging(versionsDir) {}}+function verifySnapshotStorage(skillPath) {+ const versionsDir = getVersionsDir(skillPath);+ const base = fs.existsSync(versionsDir) ? versionsDir : normalizeSkillDir(skillPath);+ const staging = prepareStaging(base, '.snapshot-storage-');+ const linkPath = path.join(staging.path, 'hardlink-check.md');+ let identity;+ let linked = false;+ let linking = false;+ try {+ const descriptor = fs.openSync(staging.contentPath, 'wx');+ try {+ identity = fs.fstatSync(descriptor);+ fs.writeFileSync(descriptor, 'ECC snapshot storage check\n', 'utf8');+ } finally {+ fs.closeSync(descriptor);+ }+ linking = true;+ fs.linkSync(staging.contentPath, linkPath);+ linked = true;+ linking = false;+ removeOwnedSnapshot({ path: linkPath, identity });+ linked = false;+ removeOwnedStaging(staging, identity);+ } catch (primaryError) {+ try {+ if (linked) removeOwnedSnapshot({ path: linkPath, identity });+ removeOwnedStaging(staging, identity);+ } catch (recoveryError) {+ const error = new Error(`${primaryError.message}; storage-check cleanup failed: ${recoveryError.message}; recovery is pending`, { cause: primaryError });+ error.primaryError = primaryError;+ error.recoveryError = recoveryError;+ throw error;+ }+ if (linking && ['ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EPERM', 'EXDEV', 'EINVAL'].includes(primaryError.code)) {+ const error = new Error(`Skill versioning requires hardlink-capable storage for snapshot creation and rollback; capability check failed before history initialization (${primaryError.code})`, { cause: primaryError });+ error.code = primaryError.code;+ error.primaryError = primaryError;+ throw error;+ }+ throw primaryError;+ }+}+function publishVersion(skillPath, skillContent, options) {ensureSkillExists(skillPath);const nextVersion = allocateSnapshotVersion(skillPath);const versionsDir = getVersionsDir(skillPath);+ verifySnapshotStorage(skillPath);ensureSkillVersioning(skillPath);const staging = prepareStaging(versionsDir);const stagedPath = staging.contentPath;@@ -294,6 +338,7 @@ function recordSnapshot(skillPath, snapshot, options) {return { version: snapshot.version, path: snapshot.path, created_at: snapshot.created_at };}+/** Snapshot creation requires hardlink-capable storage, checked before history initialization. */function createVersion(skillPath, options = {}) {const skillFilePath = ensureSkillExists(skillPath);const skillContent = fs.readFileSync(skillFilePath, 'utf8');diff --git a/tests/lib/skill-evolution-storage.test.js b/tests/lib/skill-evolution-storage.test.jsindex 6b5bc09d9..9706ca2c2 100644--- a/tests/lib/skill-evolution-storage.test.js+++ b/tests/lib/skill-evolution-storage.test.js@@ -350,6 +350,34 @@ test(`unverified staging directory identity preserves ${foreign ? 'foreign conte}+for (const rollback of [false, true]) {+ test(`${rollback ? 'rollback' : 'snapshot'} rejects unsupported hardlink storage before initializing history`, fixture => {+ const { skillDir, versionsDir } = fixture;+ if (rollback) {+ fs.mkdirSync(versionsDir);+ fs.writeFileSync(path.join(versionsDir, 'v1.md'), '# Saved target\n');+ }+ const linkSync = fs.linkSync;+ const primary = Object.assign(new Error('Injected unsupported hard links'), { code: 'EOPNOTSUPP' });+ fs.linkSync = () => { throw primary; };+ try {+ assert.throws(() => rollback ? versioning.rollbackTo(skillDir, 1) : versioning.createVersion(skillDir), error =>+ /requires hardlink-capable storage/.test(error.message) && error.primaryError === primary);+ } finally {+ fs.linkSync = linkSync;+ }+ assert.equal(fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8'), '# Original\n');+ assert.equal(fs.existsSync(versioning.getEvolutionDir(skillDir)), false);+ if (rollback) {+ assert.deepEqual(fs.readdirSync(versionsDir), ['v1.md']);+ assert.equal(fs.readFileSync(path.join(versionsDir, 'v1.md'), 'utf8'), '# Saved target\n');+ } else assert.equal(fs.existsSync(versionsDir), false);+ assert.equal(fs.readdirSync(skillDir).filter(name => name.startsWith('.snapshot-')).length, 0);+ const snapshot = versioning.createVersion(skillDir);+ assert.equal(snapshot.version, rollback ? 2 : 1);+ });+}+test('successful rollback snapshots restored content and retains earlier targets for another rollback', fixture => {const { skillDir } = fixture;versioning.createVersion(skillDir);