Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

Merge PR #389 into dev with typed evidence browser and migration coverage

tt-a1i0a18fb012ca2
diff --cc CHANGELOG.md
index ca4635d0,5dc8074f..cc56462a
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -12,18 -7,9 +12,19 @@@ All notable changes are documented here
> Development identity: `v2.17.0-dev.1`. Not a stable release.
### Added
+- **Hermes Agent community opt-in.** `integrations/hermes-agent` is a Skill-only directory plugin: it registers the existing Node Archify `SKILL.md` for Hermes. The documented install is `hermes skills install skills-sh/tt-a1i/archify/archify -y` (published GitHub Skill). A checkout symlink remains the local-dev path. Hermes still runs `node bin/archify.mjs`. This is not an official Nous product and is not an agent-switcher target.
+- **GitHub Copilot agent-switcher target.** The Start page agent switcher, README EN/ZH quick start, and landing copy add `github-copilot` alongside `cursor`, `codex`, `claude-code`, and `opencode`. It installs the same checked Skill and zero-dependency renderers via `npx skills add tt-a1i/archify --skill archify --agent github-copilot ...`; no vendor-specific fork, renderer, or schema behavior was added.
+ - **Repository evidence for every diagram type (#59).** `meta.repository` and node `sources` are now accepted by Workflow, Sequence, Data Flow, and Lifecycle as well as Architecture, and `--repo-root` reaches `render`, `validate`, `deliver`, and `preview` for all five. Each mode authors sources on its own node collection (`components`, `nodes`, `participants`, `states`) while verification is unchanged: Git top level, origin match, commit, blob, path containment, and line bounds all still have to hold, GitHub, Gitee, and `link_mode: "local-only"` repositories behave identically in every mode, and the verified payload stays keyed by node id. Architecture output is unchanged and the `repository-evidence/type-unsupported` diagnostic is removed as unreachable.
### Fixed
+- **Conservative VS15 text-width estimates.** Text-presentation selectors retain the base character's estimated width instead of forcing every sequence to one unit. This prevents wide labels, including CJK text whose font ignores VS15, from passing layout checks at half their estimated width. Actual glyph widths remain font-dependent; some text-presentation labels may now need more space. VS16 emoji estimates and text without selectors are unchanged.
+- **Readable renderer failures.** `render` and direct renderer entry points format classified input, schema, layout, and output failures without Node stacks. Filesystem failures identify the failing operation instead of labelling output errors as unreadable input; successful artifact bytes and existing validation/delivery receipt formats remain unchanged.
+- **Architecture Delta baseline arrowheads (#433).** Removed and rerouted baseline relationships retain their marker definitions in the composed Delta SVG, preserving their authored direction alongside current relationships.
+- **Compare rollback recovery (#438).** If restoring a previous output fails, compare preserves its recovery directory and reports backup-to-target paths instead of deleting the remaining backups during cleanup.
+- **固定提交的来源校验 (#420)。** 校验忽略本地 Git replacement refs,始终读取指定提交的原始对象,避免替换后的文件或行范围造成误接受或误拒绝;保留原有来源链接、诊断与用户 Git 配置。
+- **导出的独立 SVG 声明 UTF-8 编码。** 架构图「下载 SVG」和架构对比(compare)导出的 SVG 文档现在以 `<?xml version="1.0" encoding="UTF-8"?>` 声明开头;缺少声明时,部分消费方不按 XML 规范默认 UTF-8 而猜测编码,导致中文等非 ASCII 文本乱码。
+- **Architecture Delta provenance visibility.** Repository revision, provider, link-mode, and location-representation changes now produce a separate redacted provenance receipt and visible Delta notice instead of an empty authored-change claim. Provenance-only comparisons keep graph counts at zero, leave Review disabled, avoid false SVG change states, and carry the same truthful distinction into Share Cards.
+- **Compare 输入快照一致性 (#400)。** 原始输入校验使用首次读取的字节快照,使其与回执哈希和差异计算保持一致;读取后原文件发生变化不会影响本次比较,非法原始字段仍会被拒绝。
- **DSH plugin refresh.** Adapter 0.2.0 pins the current Archify development snapshot, includes the newer runtime and CLI fixes, and targets DSH 0.1.2-rc.1. Release metadata replaces the frozen 0.1.0 packaging source; the tarball uses the canonical clean-Skill stager and documents independent plugin upgrades.
- **Machine-readable CLI argument failures (#330).** `validate --json` and `deliver --json` now keep invalid or missing option values, unknown options and diagram types, unsupported option combinations, and usage errors inside one versioned failure receipt on stdout. These failures use the `arguments` stage, stable diagnostic codes, and exit status 2, while human-mode stderr behavior remains unchanged.
- **Complete artifact-check receipts (#311).** The checker now lets stdout drain before exiting, so large JSON receipts remain complete through pipes. Validation, delivery, and architecture comparison retain their original success/failure status without truncated-JSON errors.
diff --cc archify.zip
index 1f256e23,c8adaada..bd9a6379
Binary files differ
diff --cc archify/bin/archify.mjs
index adfb3e8a,3fe3a6ac..61995e94
--- a/archify/bin/archify.mjs
+++ b/archify/bin/archify.mjs
@@@ -14,16 -14,15 +14,16 @@@ const TYPES = new Set(['architecture',
function usage() {
return `Usage:
- archify render <type> <input.json> [output.html] [--quality standard|showcase] [--repo-root path (architecture only)]
+ archify render <type> <input.json> [output.html] [--quality standard|showcase] [--repo-root path]
archify compare architecture <base.json> <head.json> [output.html] [--receipt path] [--json] [--quality standard|showcase] [--repo-root path]
- archify deliver <type> <input.json> [output.html] [--json] [--open] [--quality standard|showcase] [--repo-root path (architecture only)]
- archify preview <type> <input.json> [output.html] [--no-open] [--quality standard|showcase] [--repo-root path (architecture only)]
- archify validate <type> <input.json> [--json] [--layout-json] [--quality standard|showcase] [--repo-root path (architecture only)]
- archify migrate workflow <old.json> <new.json> --to-schema 2 [--json]
+ archify deliver <type> <input.json> [output.html] [--json] [--open] [--quality standard|showcase] [--repo-root path]
+ archify preview <type> <input.json> [output.html] [--no-open] [--quality standard|showcase] [--repo-root path]
+ archify validate <type> <input.json> [--json] [--layout-json] [--quality standard|showcase] [--repo-root path]
- archify migrate workflow <old.json> <new.json> --to-schema 2 [--json]
++ archify migrate workflow <old.json> <new.json> --to-schema 2 [--json] [--repo-root path]
+ archify atlas <manifest.json> <output.html> [--json]
archify inspect <type> <input.json>
archify check <output.html>
- archify visual-check <output.html> [--json]
+ archify visual-check <output.html> [--json] [--out-dir <dir>]
archify guide [scenario or question] [--json] [--lang en|zh]
archify brands [name, alias, domain, or category] [--json]
archify brands capture <url> [--json]
@@@ -1736,7 -1650,7 +1723,8 @@@ function extractMigrationOptions(args)
}
async function commandMigrate(args) {
-- const options = extractMigrationOptions(args);
++ const repoArgs = extractRepoRootArgs(args);
++ const options = extractMigrationOptions(repoArgs.rest);
const [type, sourceArgument, destinationArgument] = options.positional;
if (
type !== 'workflow'
@@@ -1745,7 -1659,7 +1733,7 @@@
|| options.positional.length !== 3
|| options.toSchema !== '2'
) {
-- fail('Usage: archify migrate workflow <old.json> <new.json> --to-schema 2 [--json]');
++ fail('Usage: archify migrate workflow <old.json> <new.json> --to-schema 2 [--json] [--repo-root path]');
}
const sourcePath = path.resolve(sourceArgument);
@@@ -1861,7 -1775,7 +1849,7 @@@
fs.writeFileSync(candidatePath, destinationBytes, { flag: 'wx' });
const render = runNode([rendererPath('workflow'), candidatePath, artifactPath], {
stdio: 'pipe',
-- env: rendererEnv(activeQualityProfile, undefined, true),
++ env: rendererEnv(activeQualityProfile, repoArgs.repoRoot, true),
});
if (render.status !== 0) {
const failure = rendererFailure(render);
diff --cc archify/references/authoring-contract.md
index 3adeae22,579fc50c..c2189635
--- a/archify/references/authoring-contract.md
+++ b/archify/references/authoring-contract.md
@@@ -207,22 -178,19 +207,25 @@@ A card or guided view saying “retry�
## Repository evidence
- When an architecture diagram must reflect real code, inspect repository
- entrypoints, runtime boundaries, storage, transports, and deployment
- configuration before authoring. Record only evidence you actually verified.
- `--repo-root <path>` is architecture-only and is accepted by architecture
- `render`, `validate`, `deliver`, `preview`, and `compare`; workflow, sequence,
- dataflow, and lifecycle reject it. Never infer runtime causality from file
- proximity or naming alone.
+ When the diagram must reflect real code, inspect repository entrypoints,
+ runtime boundaries, storage, transports, and deployment configuration before
+ authoring. Record only evidence you actually verified. `--repo-root <path>` is
+ accepted by `render`, `validate`, `deliver`, and `preview` for every diagram
-type, and by architecture `compare`; every mode verifies `meta.repository` and
-node `sources` the same way. Never infer runtime causality from file proximity
++type, by architecture `compare`, and by workflow `migrate`; every mode verifies `meta.repository` and
++node `sources` the same way. Migrating a source-backed workflow requires the same
++`--repo-root` so its candidate is verified before replacing the destination.
++Never infer runtime causality from file proximity
+ or naming alone.
Declare `meta.repository.url` and one full 40-character `revision`, then attach
- `components[].sources` with repository-relative `path`, optional `line`,
- `end_line`, and `label`. Verification reads blobs at that commit, independently
- of working-tree edits. Verification ignores local Git replacement refs, including
- those selected by `GIT_REPLACE_REF_BASE`, and always reads the original objects
- at the pinned SHA. It does not change repository configuration or delete
- replacement refs.
+ `sources` to the mode's node collection (Architecture `components[]`, Workflow
+ and Data Flow `nodes[]`, Sequence `participants[]`, Lifecycle `states[]`) with
+ repository-relative `path`, optional `line`, `end_line`, and `label`.
-Verification reads blobs at that commit, independently of working-tree edits. A matching local origin, available commit, bounded path,
++Verification reads blobs at that commit, independently of working-tree edits.
++Verification ignores local Git replacement refs, including those selected by
++`GIT_REPLACE_REF_BASE`, and always reads the original objects at the pinned SHA.
++It does not change repository configuration or delete replacement refs.
+A matching local origin, available commit, bounded path,
blob, and valid line range are required in every link mode. Verification is
local and makes no remote requests; it establishes neither public availability
nor the current reader's access rights.
diff --cc archify/test/repository-evidence-types-browser.test.mjs
index 00000000,00000000..23eab121
new file mode 100644
--- /dev/null
+++ b/archify/test/repository-evidence-types-browser.test.mjs
@@@ -1,0 -1,0 +1,71 @@@
++import assert from 'node:assert/strict';
++import { execFileSync } from 'node:child_process';
++import fs from 'node:fs';
++import os from 'node:os';
++import path from 'node:path';
++import test from 'node:test';
++import { fileURLToPath } from 'node:url';
++import { ChromeVisualBrowser, findChrome } from '../bin/visual-check.mjs';
++
++const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
++const chrome = Object.hasOwn(process.env, 'ARCHIFY_CHROME') ? findChrome() : null;
++
++test('non-architecture sources reach real Viewer beacons, Focus and Finder', {
++ skip: !chrome,
++ timeout: 60000,
++}, async (t) => {
++ const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-typed-evidence-browser-'));
++ t.after(() => fs.rmSync(repo, { recursive: true, force: true }));
++ const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
++ fs.writeFileSync(path.join(repo, 'source.js'), 'export function source() {\n return true;\n}\n');
++ git('init');
++ git('config', 'user.name', 'Archify Tests');
++ git('config', 'user.email', '[email protected]');
++ git('add', 'source.js');
++ git('commit', '-m', 'source fixture');
++ git('remote', 'add', 'origin', 'https://github.com/example/evidence-repo');
++ const revision = git('rev-parse', 'HEAD');
++ const browser = new ChromeVisualBrowser(chrome);
++ t.after(() => browser.close());
++ const cases = [
++ ['workflow', 'nodes', 'agent-tool-call.workflow.json', false, 'light'],
++ ['sequence', 'participants', 'cache-miss-request.sequence.json', false, 'dark'],
++ ['dataflow', 'nodes', 'product-analytics.dataflow.json', true, 'light'],
++ ['lifecycle', 'states', 'agent-run.lifecycle.json', true, 'dark'],
++ ];
++ for (const [type, collection, example, local, theme] of cases) {
++ const url = local ? 'http://git.internal/Team/repo' : 'https://github.com/example/evidence-repo';
++ git('remote', 'set-url', 'origin', url);
++ const diagram = JSON.parse(fs.readFileSync(path.join(root, 'examples', example), 'utf8'));
++ const node = diagram[collection][0];
++ node.sources = [{ path: 'source.js', line: 1, end_line: 3 }];
++ diagram.meta.repository = { url, revision, ...(local ? { link_mode: 'local-only' } : {}) };
++ const input = path.join(repo, `${type}.json`), artifactPath = path.join(repo, `${type}.html`);
++ fs.writeFileSync(input, JSON.stringify(diagram));
++ execFileSync(process.execPath, [path.join(root, 'bin/archify.mjs'), 'deliver', type, input, artifactPath, '--repo-root', repo, '--json'], { encoding: 'utf8' });
++ await browser.inspect({ artifactPath, width: 1440, height: 900, theme });
++ const session = await browser.sessionPromise;
++ const response = await browser.cdp.send('Runtime.evaluate', {
++ expression: `(() => {
++ const node = [...document.querySelectorAll('[data-node-id]')].find(n => n.dataset.nodeId === ${JSON.stringify(node.id)});
++ node.dispatchEvent(new MouseEvent('click', {bubbles:true}));
++ const panel = document.getElementById('focus-evidence');
++ const rows = [...panel.querySelectorAll('.semantic-passport-source')];
++ const finder = document.getElementById('node-finder-input');
++ finder.value = 'source.js';
++ finder.dispatchEvent(new Event('input', {bubbles:true}));
++ return { visible: !panel.hidden, beacon: !!node.querySelector('[data-source-evidence-beacon]'),
++ paths: rows.map(r => r.querySelector('small').textContent),
++ links: rows.filter(r => r.tagName === 'A').map(r => r.getAttribute('href')),
++ search: document.getElementById('node-finder-results').textContent };
++ })()`, returnByValue: true,
++ }, session);
++ assert.equal(response.exceptionDetails, undefined, type);
++ const result = response.result.value;
++ assert.equal(result.visible, true, type);
++ assert.equal(result.beacon, true, type);
++ assert.deepEqual(result.paths, ['source.js'], type);
++ assert.deepEqual(result.links, local ? [] : [`${url}/blob/${revision}/source.js#L1-L3`], type);
++ assert.ok(result.search.includes(node.label), `${type}: Finder must match the source-backed node`);
++ }
++});
diff --cc archify/test/repository-evidence-types.test.mjs
index 00000000,ac1ec837..6b3287fd
mode 000000,100644..100644
--- a/archify/test/repository-evidence-types.test.mjs
+++ b/archify/test/repository-evidence-types.test.mjs
@@@ -1,0 -1,337 +1,389 @@@
+ import assert from 'node:assert/strict';
+ import { execFileSync, spawnSync } from 'node:child_process';
+ import fs from 'node:fs';
+ import os from 'node:os';
+ import path from 'node:path';
+ import test from 'node:test';
+ import { fileURLToPath } from 'node:url';
+ import { startPreview } from '../bin/preview.mjs';
+
+ const here = path.dirname(fileURLToPath(import.meta.url));
+ const skillRoot = path.resolve(here, '..');
+ const cli = path.join(skillRoot, 'bin', 'archify.mjs');
+
+ // One table for the whole file: every diagram type names its node array
+ // differently, and repository evidence must behave identically across all of
+ // them. `first` is the first authored node id, which is where the fixtures
+ // attach sources and where the verified payload must key them.
+ const TYPES = [
+ { type: 'architecture', collection: 'components', example: 'web-app.architecture.json', first: 'users' },
+ { type: 'workflow', collection: 'nodes', example: 'agent-tool-call.workflow.json', first: 'user' },
+ { type: 'sequence', collection: 'participants', example: 'cache-miss-request.sequence.json', first: 'user' },
+ { type: 'dataflow', collection: 'nodes', example: 'product-analytics.dataflow.json', first: 'web' },
+ { type: 'lifecycle', collection: 'states', example: 'agent-run.lifecycle.json', first: 'queued' },
+ ];
+
+ function git(repo, ...args) {
+ return execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
+ }
+
+ function run(args) {
+ return spawnSync(process.execPath, [cli, ...args], { cwd: skillRoot, encoding: 'utf8' });
+ }
+
+ function evidencePayload(html) {
+ const match = html.match(/<script id="archify-source-evidence-data" type="application\/json">([\s\S]*?)<\/script>/);
+ assert.ok(match, 'verified evidence payload missing');
+ return JSON.parse(match[1]);
+ }
+
+ // A throwaway origin-matched checkout plus the typed diagram that points at it.
+ function fixture({ type, collection, example, first }) {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-evidence-types-'));
+ fs.mkdirSync(path.join(root, 'src', 'nested'), { recursive: true });
+ fs.writeFileSync(path.join(root, 'src', 'router.js'), 'export function route(input) {\n return input.kind;\n}\n');
+ fs.writeFileSync(path.join(root, 'src', 'store.js'), 'export const store = new Map();\n');
+ git(root, 'init');
+ git(root, 'config', 'user.name', 'Archify Tests');
+ git(root, 'config', 'user.email', '[email protected]');
+ git(root, 'remote', 'add', 'origin', '[email protected]:example/evidence-repo.git');
+ git(root, 'add', '.');
+ git(root, 'commit', '-m', 'fixture');
+ const revision = git(root, 'rev-parse', 'HEAD');
+
+ const diagram = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', example), 'utf8'));
+ diagram.meta.repository = { url: 'https://github.com/example/evidence-repo', revision };
+ const node = diagram[collection].find((candidate) => candidate.id === first);
+ assert.ok(node, `${type} example is missing node ${JSON.stringify(first)}`);
+ node.sources = [
+ { path: 'src/router.js', line: 1, end_line: 3, label: 'Request router' },
+ { path: 'src/store.js', line: 1 },
+ ];
+ const input = path.join(root, `diagram.${type}.json`);
+ const write = () => fs.writeFileSync(input, JSON.stringify(diagram, null, 2));
+ write();
+ return { root, revision, diagram, node, input, write };
+ }
+
+ for (const shape of TYPES) {
+ const { type, collection, first } = shape;
+
+ test(`${type} repository evidence is revision-verified, receipt-backed, and keyed by node id`, () => {
+ const data = fixture(shape);
+ const output = path.join(data.root, `verified.${type}.html`);
+ const result = run(['deliver', type, data.input, output, '--repo-root', data.root, '--json']);
+ assert.equal(result.status, 0, result.stderr || result.stdout);
+
+ assert.deepEqual(JSON.parse(result.stdout).evidence, {
+ verified: true,
+ repository: 'https://github.com/example/evidence-repo',
+ revision: data.revision,
+ references: 2,
+ });
+
+ const html = fs.readFileSync(output, 'utf8');
+ const evidence = evidencePayload(html);
+ assert.equal(evidence.verified, true);
+ assert.equal(evidence.referenceCount, 2);
+ assert.equal(evidence.repository.shortRevision, data.revision.slice(0, 7));
+ assert.deepEqual(Object.keys(evidence.nodes), [first]);
+ assert.equal(evidence.nodes[first].length, 2);
+ assert.equal(
+ evidence.nodes[first][0].href,
+ `https://github.com/example/evidence-repo/blob/${data.revision}/src/router.js#L1-L3`,
+ );
+ assert.equal(evidence.nodes[first][0].label, 'Request router');
+
+ // The verified node must exist in the artifact under the same id, or the
+ // viewer's beacon pass has nothing to attach the SRC affordance to.
+ assert.match(html, new RegExp(`data-node-id="${first}"`));
+ assert.match(html, /Archify\.sourceEvidence\.installBeacons\(\)/);
+
+ const svg = html.match(/<svg\b[\s\S]*?<\/svg>/)?.[0] || '';
+ assert.doesNotMatch(svg, /src\/router\.js|github\.com\/example\/evidence-repo|source-evidence/);
+ });
+
+ test(`${type} repository evidence applies every architecture verification`, () => {
+ const data = fixture(shape);
+ const output = path.join(data.root, `must-stay.${type}.html`);
+ fs.writeFileSync(output, 'trusted previous artifact');
+ const deliver = (...args) => run(['deliver', type, data.input, output, ...args, '--json']);
+
+ // No --repo-root at all.
+ let result = deliver();
+ assert.equal(result.status, 1);
+ assert.match(JSON.parse(result.stdout).error, /Pass --repo-root/);
+
+ // Not the Git top-level directory.
+ result = deliver('--repo-root', path.join(data.root, 'src'));
+ assert.equal(result.status, 1);
+ assert.match(JSON.parse(result.stdout).error, /must be the Git top-level directory/);
+
+ // Origin does not match the authored repository.
+ git(data.root, 'remote', 'set-url', 'origin', 'https://github.com/example/other-repo.git');
+ result = deliver('--repo-root', data.root);
+ assert.equal(result.status, 1);
+ assert.match(JSON.parse(result.stdout).error, /does not match/);
+ git(data.root, 'remote', 'set-url', 'origin', '[email protected]:example/evidence-repo.git');
+
+ // Commit does not exist locally.
+ const pinned = data.diagram.meta.repository.revision;
+ data.diagram.meta.repository.revision = '0'.repeat(40);
+ data.write();
+ result = deliver('--repo-root', data.root);
+ assert.equal(result.status, 1);
+ assert.match(JSON.parse(result.stdout).error, /is not available in the local repository/);
+ data.diagram.meta.repository.revision = pinned;
+
+ // Path escape.
+ data.node.sources = [{ path: '../outside.js' }];
+ data.write();
+ result = deliver('--repo-root', data.root);
+ assert.equal(result.status, 1);
+ assert.match(JSON.parse(result.stdout).error, /must stay inside the repository/);
+
+ // Non-POSIX / control-character path.
+ data.node.sources = [{ path: 'src/router.js\n' }];
+ data.write();
+ result = deliver('--repo-root', data.root);
+ assert.equal(result.status, 1);
+ assert.match(JSON.parse(result.stdout).error, /repo-relative POSIX path/);
+
+ // Blob does not exist at the pinned revision.
+ data.node.sources = [{ path: 'src/missing.js' }];
+ data.write();
+ result = deliver('--repo-root', data.root);
+ assert.equal(result.status, 1);
+ assert.match(JSON.parse(result.stdout).error, /does not identify a file/);
+
+ // Line range beyond the pinned blob.
+ data.node.sources = [{ path: 'src/router.js', line: 4 }];
+ data.write();
+ result = deliver('--repo-root', data.root);
+ assert.equal(result.status, 1);
+ assert.match(JSON.parse(result.stdout).error, /has 3 lines/);
+
+ // Inverted line range.
+ data.node.sources = [{ path: 'src/router.js', line: 3, end_line: 2 }];
+ data.write();
+ result = deliver('--repo-root', data.root);
+ assert.equal(result.status, 1);
+ assert.match(JSON.parse(result.stdout).error, /must be greater than or equal to line/);
+
+ // end_line without line.
+ data.node.sources = [{ path: 'src/router.js', end_line: 2 }];
+ data.write();
+ result = deliver('--repo-root', data.root);
+ assert.equal(result.status, 1);
+ assert.match(JSON.parse(result.stdout).error, /requires line/);
+
+ assert.equal(fs.readFileSync(output, 'utf8'), 'trusted previous artifact');
+ });
+
++ test(`${type} duplicate evidence node IDs cannot replace a trusted artifact`, () => {
++ const data = fixture(shape);
++ const duplicate = structuredClone(data.node);
++ duplicate.sources = [{ path: 'src/store.js', line: 1 }];
++ data.diagram[collection].push(duplicate);
++ data.write();
++ const output = path.join(data.root, 'duplicate.html');
++ fs.writeFileSync(output, 'trusted previous artifact');
++ for (const args of [
++ ['validate', type, data.input, '--repo-root', data.root, '--json'],
++ ['deliver', type, data.input, output, '--repo-root', data.root, '--json'],
++ ]) {
++ const result = run(args);
++ assert.equal(result.status, 1, type);
++ assert.match(result.stdout, /ids must be unique|duplicate-node-id/, type);
++ }
++ assert.equal(fs.readFileSync(output, 'utf8'), 'trusted previous artifact');
++ });
++
+ test(`${type} repository evidence honors Gitee links and local-only mode`, () => {
+ const data = fixture(shape);
+ const output = path.join(data.root, `provider.${type}.html`);
+
+ data.diagram.meta.repository = { url: 'https://gitee.com/example/evidence-repo', revision: data.revision, provider: 'gitee' };
+ data.write();
+ git(data.root, 'remote', 'set-url', 'origin', '[email protected]:example/evidence-repo.git');
+ let result = run(['deliver', type, data.input, output, '--repo-root', data.root, '--json']);
+ assert.equal(result.status, 0, result.stderr || result.stdout);
+ let evidence = evidencePayload(fs.readFileSync(output, 'utf8'));
+ assert.equal(evidence.repository.href, `https://gitee.com/example/evidence-repo/tree/${data.revision}`);
+ assert.equal(evidence.nodes[first][0].href, `https://gitee.com/example/evidence-repo/blob/${data.revision}/src/router.js#L1-3`);
+
+ data.diagram.meta.repository.provider = 'github';
+ data.write();
+ result = run(['validate', type, data.input, '--repo-root', data.root, '--json']);
+ assert.equal(result.status, 1);
+ assert.ok(JSON.parse(result.stdout).diagnostics.some((entry) => entry.code === 'repository-evidence/provider-invalid'));
+
+ data.diagram.meta.repository = { url: 'http://git.internal:3000/Platform/evidence-repo', revision: data.revision, link_mode: 'local-only' };
+ data.write();
+ git(data.root, 'remote', 'set-url', 'origin', 'http://git.internal:3000/Platform/evidence-repo');
+ result = run(['deliver', type, data.input, output, '--repo-root', data.root, '--json']);
+ assert.equal(result.status, 0, result.stderr || result.stdout);
+ assert.equal(JSON.parse(result.stdout).evidence.linkMode, 'local-only');
+ evidence = evidencePayload(fs.readFileSync(output, 'utf8'));
+ assert.equal(evidence.repository.linkMode, 'local-only');
+ assert.equal(evidence.repository.href, undefined);
+ assert.equal(evidence.nodes[first].length, 2);
+ assert.ok(evidence.nodes[first].every((source) => !Object.hasOwn(source, 'href')));
+ });
+
+ test(`${type} evidence diagnostics point at its own node collection`, () => {
+ const data = fixture(shape);
+ data.node.sources = [{ path: 'src/missing.js' }];
+ data.write();
+ const result = run(['validate', type, data.input, '--repo-root', data.root, '--json']);
+ assert.equal(result.status, 1);
+ const receipt = JSON.parse(result.stdout);
+ const diagnostic = receipt.diagnostics.find((entry) => entry.code === 'repository-evidence/file-missing');
+ assert.ok(diagnostic, JSON.stringify(receipt.diagnostics));
+ assert.match(diagnostic.subject.path, new RegExp(`^/${collection}/\\d+/sources/0/path$`));
+ assert.equal(diagnostic.subject.nodeId, first);
+ assert.equal(diagnostic.evidence.sourcePath, 'src/missing.js');
+ assert.ok(diagnostic.supportedFixes.length);
+ });
+
+ test(`${type} sources stay bounded by the shared schema shape`, () => {
+ const data = fixture(shape);
+ data.node.sources = [
+ { path: 'src/router.js' },
+ { path: 'src/router.js' },
+ { path: 'src/router.js' },
+ { path: 'src/router.js' },
+ ];
+ data.write();
+ let result = run(['validate', type, data.input, '--repo-root', data.root]);
+ assert.equal(result.status, 1);
+ assert.match(result.stderr, /must NOT have more than 3 items/);
+
+ data.node.sources = [{ path: 'src/router.js', branch: 'main' }];
+ data.write();
+ result = run(['validate', type, data.input, '--repo-root', data.root]);
+ assert.equal(result.status, 1);
+ assert.match(result.stderr, /must NOT have additional properties/);
+ });
+
+ test(`${type} node sources require pinned repository metadata`, () => {
+ const data = fixture(shape);
+ delete data.diagram.meta.repository;
+ data.write();
+ const result = run(['validate', type, data.input, '--repo-root', data.root, '--json']);
+ assert.equal(result.status, 1);
+ assert.ok(JSON.parse(result.stdout).diagnostics.some(
+ (entry) => entry.code === 'repository-evidence/repository-required',
+ ));
+ });
+
+ test(`${type} repository metadata requires at least one verified source`, () => {
+ const data = fixture(shape);
+ delete data.node.sources;
+ data.write();
+ const result = run(['validate', type, data.input, '--repo-root', data.root, '--json']);
+ assert.equal(result.status, 1);
+ assert.ok(JSON.parse(result.stdout).diagnostics.some(
+ (entry) => entry.code === 'repository-evidence/source-required',
+ ));
+ });
+ }
+
+ // The issue's own reproduction: --repo-root must be accepted by every typed
+ // command, including for a diagram that carries no evidence at all.
+ test('--repo-root is accepted for every diagram type', () => {
+ for (const { type, example } of TYPES) {
+ const result = run(['validate', type, path.join(skillRoot, 'examples', example), '--repo-root', '.']);
+ assert.equal(result.status, 0, `${type}: ${result.stderr || result.stdout}`);
+ }
+ });
+
+ test('repository evidence no longer rejects any supported diagram type', () => {
+ const rejected = run(['validate', 'lifecycle', path.join(skillRoot, 'examples', 'agent-run.lifecycle.json'), '--repo-root', '.']);
+ assert.equal(rejected.status, 0, rejected.stderr);
+ assert.doesNotMatch(rejected.stderr, /architecture diagrams only/);
+ assert.doesNotMatch(
+ fs.readFileSync(path.join(skillRoot, 'renderers', 'shared', 'repository-evidence.mjs'), 'utf8'),
+ /type-unsupported/,
+ 'the type-unsupported diagnostic is unreachable and must be removed deliberately',
+ );
+ });
+
+ test('ordinary typed artifacts still carry no repository evidence', () => {
+ for (const { type, example } of TYPES) {
+ const output = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'archify-no-evidence-types-')), `${type}.html`);
+ const result = run(['render', type, path.join(skillRoot, 'examples', example), output]);
+ assert.equal(result.status, 0, result.stderr);
+ const html = fs.readFileSync(output, 'utf8');
+ assert.doesNotMatch(html, /id="archify-source-evidence-data"/);
+ }
+ });
+
+ async function waitForState(url, predicate, timeoutMs = 12000) {
+ const started = Date.now();
+ let latest;
+ while (Date.now() - started < timeoutMs) {
+ latest = await (await fetch(new URL('/state', url))).json();
+ if (predicate(latest)) return latest;
+ await new Promise((resolve) => setTimeout(resolve, 40));
+ }
+ assert.fail(`preview did not settle; latest state: ${JSON.stringify(latest)}`);
+ }
+
+ test('live preview publishes verified evidence for a non-architecture type', { timeout: 20000 }, async () => {
+ const shape = TYPES.find(({ type }) => type === 'lifecycle');
+ const data = fixture(shape);
+ const output = path.join(data.root, 'preview.lifecycle.html');
+ const preview = await startPreview({
+ type: shape.type,
+ input: data.input,
+ output,
+ repoRoot: data.root,
+ open: false,
+ debounceMs: 30,
+ pollMs: 60,
+ });
+ try {
+ const state = await waitForState(preview.url, (candidate) => candidate.status === 'verified');
+ assert.equal(state.revision, 1);
+ const html = await (await fetch(new URL('/artifact.html', preview.url))).text();
+ const evidence = evidencePayload(html);
+ assert.equal(evidence.repository.revision, data.revision);
+ assert.equal(evidence.nodes[shape.first].length, 2);
+ } finally {
+ await preview.stop();
+ }
+ });
++
++test('workflow migration verifies and preserves pinned source evidence before replacement', () => {
++ const data = fixture(TYPES.find(shape => shape.type === 'workflow'));
++ const repository = data.diagram.meta.repository;
++ const legacy = JSON.parse(fs.readFileSync(path.join(skillRoot, 'test/fixtures/v1-workflow-explicit-coordinates.workflow.json'), 'utf8'));
++ legacy.meta.repository = repository;
++ legacy.nodes[0].sources = [{ path: 'src/router.js', line: 1, end_line: 3 }];
++ const sourceBytes = JSON.stringify(legacy);
++ fs.writeFileSync(data.input, sourceBytes);
++ const output = path.join(data.root, 'migrated.json');
++ fs.writeFileSync(output, 'trusted prior migration');
++ const args = ['migrate', 'workflow', data.input, output, '--to-schema', '2', '--json'];
++ const missing = run(args);
++ assert.equal(missing.status, 1);
++ assert.match(missing.stdout, /repository-evidence\/root-required/);
++ assert.equal(fs.readFileSync(output, 'utf8'), 'trusted prior migration');
++ const migrated = run([...args, '--repo-root', data.root]);
++ assert.equal(migrated.status, 0, migrated.stdout || migrated.stderr);
++ const doc = JSON.parse(fs.readFileSync(output, 'utf8'));
++ assert.equal(doc.schema_version, 2);
++ assert.deepEqual(doc.meta.repository, repository);
++ assert.deepEqual(doc.nodes.find(n => n.id === legacy.nodes[0].id).sources, legacy.nodes[0].sources);
++ assert.equal(fs.readFileSync(data.input, 'utf8'), sourceBytes);
++ assert.equal(run(['validate', 'workflow', output, '--repo-root', data.root, '--json']).status, 0);
++ const trusted = fs.readFileSync(output);
++ legacy.nodes[0].sources[0].line = 999;
++ delete legacy.nodes[0].sources[0].end_line;
++ fs.writeFileSync(data.input, JSON.stringify(legacy));
++ const invalid = run([...args, '--repo-root', data.root]);
++ assert.equal(invalid.status, 1);
++ assert.match(invalid.stdout, /repository-evidence\/line-out-of-range/);
++ assert.deepEqual(fs.readFileSync(output), trusted);
++});
diff --cc scripts/run-browser-tests.mjs
index 0b0a88a2,00000000..838b837f
mode 100644,000000..100644
--- a/scripts/run-browser-tests.mjs
+++ b/scripts/run-browser-tests.mjs
@@@ -1,52 -1,0 +1,53 @@@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findChrome } from '../archify/bin/visual-check.mjs';
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'archify');
+// Shared by PR CI and tag releases. WebM decoding stays in test:webm.
+const testFiles = [
+ 'desktop-reader-browser.test.mjs',
+ 'atlas-browser.test.mjs',
+ 'reader-layout-browser.test.mjs',
+ 'sequence-header-clearance.test.mjs',
+ 'lifecycle-rail-browser.test.mjs',
+ 'export-cleanup-browser.test.mjs',
+ 'offline-font-browser.test.mjs',
+ 'i18n.test.mjs',
+ 'semantic-radar.test.mjs',
+ 'viewer-chrome-layout.test.mjs',
+ 'viewer-camera-browser.test.mjs',
+ 'motion-governor-browser.test.mjs',
+ 'finder-browser.test.mjs',
+ 'intent-trace-browser.test.mjs',
+ 'semantic-lens-browser.test.mjs',
+ 'route-probe-browser.test.mjs',
+ 'guided-views-browser.test.mjs',
+ 'focus-browser.test.mjs',
+ 'semantic-passport-move-browser.test.mjs',
+ 'export-browser.test.mjs',
+ 'viewer-identifiers-browser.test.mjs',
+ 'repository-evidence.test.mjs',
++ 'repository-evidence-types-browser.test.mjs',
+];
+
+const chrome = findChrome();
+if (!chrome) {
+ console.error('Browser tests require an executable Chrome/Chromium. Set ARCHIFY_CHROME to its path; this gate cannot skip browser coverage.');
+ process.exit(1);
+}
+
+const args = ['--test'];
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major > 18 || (major === 18 && minor >= 19)) args.push('--test-concurrency=2');
+args.push(...testFiles.map((file) => path.join('test', file)));
+const result = spawnSync(process.execPath, args, {
+ cwd: skillRoot,
+ env: { ...process.env, ARCHIFY_CHROME: chrome },
+ stdio: 'inherit',
+});
+if (result.error) throw result.error;
+if (result.signal) console.error(`browser test runner terminated by ${result.signal}`);
+process.exitCode = result.status ?? 1;