Skip to content

armgit / ECC

Public Imported from GitHub
0

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.md
index 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.md
index 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.md
index 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.js
index 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.js
index 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);