Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
fix(update): let users act on reminders and survive slow networks
tt-a1ie5ad7bd98c70
diff --git a/archify.zip b/archify.zipindex 41473c25..66590550 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 2b3f4ed4..7efc61bd 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -43,7 +43,7 @@ Use this path for ordinary generation. Read branch references only when their st## Update awareness-`finalize` and standalone `deliver` include `update` in their receipts. Do not run a separate check for the same delivery. If `update.noticeRequired` is true, read `references/update-awareness.md` and keep one update line in your final response to the user, even after a quality gate fails. For a task with several diagrams, mention the update once in the final response. Never acknowledge, snooze, ignore, install, or update on the user's behalf.+`finalize` and standalone `deliver` include `update` in their receipts. Do not run a separate check for the same delivery. If `update.noticeRequired` is true, read `references/update-awareness.md` and keep one update line in your final response to the user, even after a quality gate fails. For a task with several diagrams, mention the update once in the final response. Snooze or ignore a reminder only when the user explicitly asks; never install or update on your own initiative.Before the first candidate, use the authoring references and relevant repository source, not Archify implementation or tests. Inspect Archify implementation if diagnostics remain unactionable after focused repairs.diff --git a/archify/bin/delivery-update.mjs b/archify/bin/delivery-update.mjsindex 5b36ee46..a5bd08cd 100644--- a/archify/bin/delivery-update.mjs+++ b/archify/bin/delivery-update.mjs@@ -29,7 +29,7 @@ function normalize(result) {? result.checkedAt? `A previous check at ${result.checkedAt} found a newer release.`: 'A previous check found a newer release; its check time is unknown.'- : 'A newer release is available.'} Release notes: ${result.releaseNotes}. The installed Skill has not changed.`+ : 'A newer release is available.'} Release notes: ${result.releaseNotes}. The installed Skill has not changed; ask to snooze or ignore this reminder.`: null;return {status: 'update_available',diff --git a/archify/bin/finalize.mjs b/archify/bin/finalize.mjsindex 7854009e..4407059b 100644--- a/archify/bin/finalize.mjs+++ b/archify/bin/finalize.mjs@@ -19,6 +19,7 @@ import {import { startDeliveryUpdateCheck } from './delivery-update.mjs';export const FINALIZE_STAGES = Object.freeze(['validate', 'deliver', 'check', 'browser-check']);+const FINALIZE_UPDATE_DEADLINE_MS = 4_000;function sha256(buffer) {return createHash('sha256').update(buffer).digest('hex');@@ -693,7 +694,9 @@ export async function runFinalize({summaryCapture = writeJsonAtomic(resolvedSummary, compactFinalizeReceipt(receipt), summaryCapture, assertReceiptPaths);};persistReceipts();- const updateCheck = startUpdateCheck({ env });+ // The gates below usually take seconds, so a slower network can finish the+ // update check in parallel instead of timing out on every delivery.+ const updateCheck = startUpdateCheck({ env, deadlineMs: FINALIZE_UPDATE_DEADLINE_MS });// Only launch/attach the blank browser here. The normal browser gate still// verifies current delivery provenance before it consumes this one-shot factory.diff --git a/archify/references/update-awareness.md b/archify/references/update-awareness.mdindex 5ab52704..a79d348b 100644--- a/archify/references/update-awareness.md+++ b/archify/references/update-awareness.md@@ -2,9 +2,11 @@Read this file when a `finalize` or standalone `deliver` receipt has `update.noticeRequired: true`.-Keep one compact line in the final response, in the user's language, with `installedVersion`, `availableVersion`, and the official `releaseNotes` link. Say that the installed Skill has not changed. If `source` is `cache`, say that a previous check found the update; use `checkedAt` only when present, and otherwise say the check time is unknown. A process message or tool output does not replace this final line.+Keep one compact line in the final response, in the user's language, with `installedVersion`, `availableVersion`, and the official `releaseNotes` link. Say that the installed Skill has not changed and that the user can ask to snooze or ignore the reminder. If `source` is `cache`, say that a previous check found the update; use `checkedAt` only when present, and otherwise say the check time is unknown. A process message or tool output does not replace this final line.For `severity: "security"`, label it as a security update without making installation automatic or urgent by default.-You may translate the fixed local `noticeText`. Never quote, summarize, or translate the remote manifest's summary. Do not run `--ack`, `--snooze`, or `--ignore` yourself. A user may explicitly choose `--snooze <eventKey>` (seven days by default) or `--ignore <eventKey>` (this exact release only); those commands do not install an update.+You may translate the fixed local `noticeText`. Never quote, summarize, or translate the remote manifest's summary.++When the user explicitly asks to pause or stop this reminder, run `node scripts/check-update.mjs --snooze "<eventKey>"` (seven days) or `--ignore "<eventKey>"` (this exact release only) from the Skill directory with the receipt's `update.eventKey`, then report the returned status. Never run them on your own initiative; `--ack` is a no-op. These commands do not install an update, and a newer release notifies again.The notice is information, not permission. Keep the installed version unchanged. This workflow never downloads, installs, or executes an update, and silence is never consent.diff --git a/archify/scripts/delivery-update-child.mjs b/archify/scripts/delivery-update-child.mjsindex 9c978c2a..b7d0da7c 100644--- a/archify/scripts/delivery-update-child.mjs+++ b/archify/scripts/delivery-update-child.mjs@@ -17,6 +17,8 @@ const result = await checkForUpdate({? { releasePath: process.env.ARCHIFY_UPDATE_RELEASE_PATH } : {}),...(process.env.ARCHIFY_UPDATE_CACHE_DIRECTORY? { cacheDirectory: process.env.ARCHIFY_UPDATE_CACHE_DIRECTORY } : {}),- timeoutMs: 850,+ // Leave time to record a failed fetch, so a slow network backs off instead+ // of being killed before its result reaches the cache.+ timeoutMs: Math.max(1, Math.floor(remainingMs - 150)),});process.stdout.write(`${JSON.stringify(result)}\n`);diff --git a/archify/test/delivery-update.test.mjs b/archify/test/delivery-update.test.mjsindex 252cfed5..1a4905c6 100644--- a/archify/test/delivery-update.test.mjs+++ b/archify/test/delivery-update.test.mjs@@ -4,7 +4,7 @@ import os from 'node:os';import path from 'node:path';import { spawnSync } from 'node:child_process';import test from 'node:test';-import { fileURLToPath } from 'node:url';+import { fileURLToPath, pathToFileURL } from 'node:url';import { checkForUpdate } from '../scripts/check-update.mjs';import { startDeliveryUpdateCheck } from '../bin/delivery-update.mjs';@@ -65,6 +65,7 @@ test('bounded service returns the same cached notice on repeated deliveries', asassert.equal(result.source, 'cache');assert.equal(result.noticeRequired, true);assert.match(result.noticeText, /previous check/);+ assert.match(result.noticeText, /ask to snooze or ignore this reminder/);assert.ok(performance.now() - started < 1_200);}});@@ -83,6 +84,24 @@ test('service deadline kills a blocked child and leaves no later result', asyncassert.deepEqual(fs.readdirSync(root).sort(), ['blocker.mjs', 'skill-release.json']);});+test('a slow network records its failed check before the deadline and backs off', async (t) => {+ const testFixture = fixture(t);+ const calls = path.join(testFixture.root, 'fetch-calls');+ const preload = path.join(testFixture.root, 'slow-fetch.mjs');+ fs.writeFileSync(preload, `import fs from 'node:fs';+globalThis.fetch = (_url, { signal }) => {+ fs.appendFileSync(${JSON.stringify(calls)}, 'x');+ return new Promise((_resolve, reject) => signal.addEventListener('abort', () => reject(signal.reason)));+};+`);+ const slowEnv = { ...env(testFixture), NODE_OPTIONS: `--import=${pathToFileURL(preload).href}` };+ const first = await startDeliveryUpdateCheck({ env: slowEnv, deadlineMs: 600 });+ assert.equal(first.reason, 'check-failed');+ const second = await startDeliveryUpdateCheck({ env: slowEnv, deadlineMs: 600 });+ assert.equal(second.status, 'unavailable');+ assert.equal(fs.readFileSync(calls, 'utf8'), 'x');+});+test('a synchronous renderer delay does not turn a completed check into a timeout', async (t) => {const testFixture = fixture(t);await seed(testFixture);diff --git a/archify/test/skill-metadata.test.mjs b/archify/test/skill-metadata.test.mjsindex aa4ebe3a..335b1e9a 100644--- a/archify/test/skill-metadata.test.mjs+++ b/archify/test/skill-metadata.test.mjs@@ -55,7 +55,8 @@ test('update awareness is notification-only and never replaces the requested worassert.match(skill + updateAwareness, /`update\.noticeRequired`[\s\S]*final response/i);assert.match(skill + updateAwareness, /several diagrams[\s\S]*once in the final response/i);assert.match(skill + updateAwareness, /information, not permission/i);- assert.match(skill + updateAwareness, /Do not run `--ack`, `--snooze`, or `--ignore` yourself/);+ assert.match(skill, /Snooze or ignore a reminder only when the user explicitly asks/);+ assert.match(updateAwareness, /explicitly asks to pause or stop[\s\S]*--snooze "<eventKey>"[\s\S]*--ignore "<eventKey>"[\s\S]*Never run them on your own initiative/);assert.match(skill + updateAwareness, /installed Skill has not changed/i);assert.doesNotMatch(skill, /npx skills update|gh skill update/i);});diff --git a/scripts/run-tests.mjs b/scripts/run-tests.mjsindex 9f87b8a4..a1381ce1 100644--- a/scripts/run-tests.mjs+++ b/scripts/run-tests.mjs@@ -2,6 +2,7 @@import { spawnSync } from 'node:child_process';import fs from 'node:fs';+import os from 'node:os';import path from 'node:path';import { fileURLToPath } from 'node:url';@@ -19,10 +20,14 @@ const args = ['--test'];if (supportsConcurrencyFlag) args.push('--test-concurrency=2');args.push(...testFiles);+// Delivery commands check for updates; keep that state out of the user's cache.+const updateCache = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'archify-test-update-')));const result = spawnSync(process.execPath, args, {cwd: skillRoot,stdio: 'inherit',+ env: { ...process.env, ARCHIFY_UPDATE_CACHE_DIRECTORY: updateCache },});+fs.rmSync(updateCache, { recursive: true, force: true });if (result.error) throw result.error;if (result.signal) {