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
docs: strengthen the contribution contract (#97)
tt-a1i95e8a3a9d501
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 11e8c6c4..309c7d5c 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1,19 +1,50 @@# Contributing to Archify-Thank you for helping Archify make engineering diagrams more trustworthy and useful. Stability comes before feature count: small reproductions, explicit contracts, and evidence-backed changes are easier to review and safer to ship.+Thank you for helping Archify make engineering diagrams more trustworthy and useful. Archify is Agent-first: people describe the system they want to explain, while the Skill, typed JSON contract, renderers, validators, and delivery receipts make the result reproducible.++Stability comes before feature count. A small change with a real reproduction, an explicit contract, and evidence from the final artifact is easier to review and safer to ship than a broad rewrite.## Choose the right path- Found a renderer, validator, package, or viewer problem? Use [the bug report form](.github/ISSUE_TEMPLATE/bug-report.yml).- Made a useful real-world diagram? Use [the showcase form](.github/ISSUE_TEMPLATE/showcase.yml).-- Want to change behavior? Open or link an issue before a broad refactor so the contract and non-goals are clear.-- Found a security vulnerability? Do not open a public reproduction containing exploit details or secrets; use GitHub's private security reporting for this repository.+- Want to change a schema, renderer contract, validation rule, installation path, export, or other product behavior? Open or link an issue before implementing it. Agree on the user value, compatibility boundary, and non-goals first.+- Found a security vulnerability? Do not publish exploit details or secrets. Use GitHub's private security reporting for this repository.++Small documentation corrections and narrowly scoped test fixes do not require a planning issue. Large documentation surfaces do: prefer improving the canonical Skill, contract, diagnostic, or existing guide over creating a second explanation of the same behavior.++Do not include secrets, access tokens, credentials, private repository content, personal data, or customer data in prompts, JSON fixtures, logs, screenshots, generated artifacts, or package tests.++## Before writing code++Start from the latest `main`. Recheck it before final review: a concurrent change may already solve the problem or alter the relevant contract. A test result from an old base is not integration evidence.++Keep one pull request focused on one behavior or one tightly related delivery slice. The PR should state:++- the user problem and linked issue, when one exists;+- what changes and what deliberately does not;+- compatibility and migration impact;+- failure behavior and rollback path;+- exact tests and final-artifact evidence.-Do not include secrets, access tokens, credentials, private repository content, personal data, or customer data in prompts, JSON fixtures, logs, screenshots, or generated artifacts.+Draft PRs are welcome for early technical feedback. Mark the PR ready only when its scope is stable, it is current with `main`, its generated artifacts are intentional, and the stated checks have actually run.++## Product and compatibility contracts++Archify's public behavior is larger than a renderer function. Treat these as contracts:++- Existing schema-v1 typed JSON remains valid unless a reviewed change explicitly introduces a breaking rule and migration path.+- Explicit authored geometry such as `via`, named routes, channels, sides, and label placement remains authoritative unless the contract says otherwise. Do not silently rewrite topology or authored intent.+- `standard` preserves broad compatibility. A new `showcase` failure must identify a real, repairable defect, avoid rejecting necessary routing, and return a stable machine-readable diagnostic.+- Agent-facing failures belong in `diagnostics[]`: use a stable `code`, precise `subject`, concrete `evidence`, and executable `supportedFixes`. Do not require ordinary users or Agents to scrape prose from logs.+- Agent-first does not mean documentation-free. It means one canonical contract per behavior. Link to that source instead of copying evolving CLI stages, receipt fields, or error-code tables into parallel manuals.+- A valid SVG is not automatically a good diagram. Geometry, projected text, z-order, masks, interaction, export, and real browser layout can fail independently.++If a validation rule expresses taste rather than correctness, begin with evidence or a warning. Before making it a hard error, test legitimate exceptions such as obstacles, shared ports, explicit routing, nested boundaries, and existing checked-in examples.## Local setup-The renderer package lives in `archify/` and supports Node.js 18 and later; CI covers Node.js 18, 20, 22, and 24.+The renderer package lives in `archify/` and supports Node.js 18 and later. CI covers Node.js 18, 20, 22, and 24.```bashcd archify@@ -21,50 +52,94 @@ npm cinpm test```-During development, run the narrowest relevant test first, then the full suite before opening a pull request. Behavioral fixes should include a failing regression test that demonstrates the problem before the implementation changes. Cross-renderer contracts belong in one public CLI seam (`archify render`/`validate` against final SVG/HTML), not tests of private resolver helpers.+During development, run the narrowest relevant test first, then the full suite before requesting final review. Behavioral fixes should include a failing regression test that demonstrates the problem before the implementation changes.-## Bug fixes+Test public behavior through a supported seam whenever possible: `archify render`, `validate`, `deliver`, `visual-check`, or the final SVG/HTML. Private helper tests are useful for edge cases, but they do not replace a CLI or artifact-level regression.-A useful bug report contains:+## Evidence by change type-1. The exact Archify version or commit, installation method, command, and environment.-2. The smallest redacted typed JSON that still reproduces the failure.-3. The complete machine-readable validation receipt or exact error.-4. Expected versus actual behavior.-5. A final-artifact screenshot only when the problem is visual.+### Renderer, layout, and validation-Do not replace deterministic evidence with a screenshot. For visual defects, keep both the validator result and the final rendered evidence.+Include the smallest redacted typed JSON that reproduces the behavior. Verify both the intended fix and plausible exceptions. At minimum:-## Community showcase submissions+1. Run the focused regression tests.+2. Run the candidate against relevant checked-in examples and frozen compatibility fixtures.+3. Run `npm test` from `archify/`.+4. For visible changes, render the final HTML and run `visual-check`.+5. Inspect the generated screenshots or HTML in a capable visual surface.-Showcase cases should be reproducible proof, not promotional screenshots. Submit the original prompt, agent/client, exact model, Archify version, redacted typed JSON, artifact, validation receipt, and truthful visual-review status through `.github/ISSUE_TEMPLATE/showcase.yml`.+Static SVG/XML checks cannot prove desktop readability, stacking order, font settling, or interaction. When the adaptive reader or viewer layout changes, run the real browser test with Chrome available:++```bash+cd archify+ARCHIFY_CHROME="/path/to/chrome" node --test test/desktop-reader-browser.test.mjs+```++A browser test that was skipped because Chrome was unavailable is **skipped**, not passed. Report that status exactly.++### CLI, receipts, and delivery-Maintainers may ask for a smaller source file, rerun validation, or decline a case that cannot be safely published. A submission is not guaranteed inclusion. Accepted cases should preserve author attribution and must not be presented as proof of model quality without a controlled benchmark protocol.+Preserve non-zero exit behavior and machine-readable receipts. A successful `validate` does not prove atomic delivery, and a successful `deliver` does not prove perceptual quality. Follow [the delivery contract](archify/references/delivery-contract.md) and test the failure stage you changed.-## Pull requests+### Packages, plugins, and releases-Keep a pull request focused on one behavior or one tightly related delivery slice. Describe its non-goals, compatibility risk, failure behavior, tests, and rollback path. Preserve unrelated worktree changes and generated files.+Published artifacts must be reproducible from tracked repository content.-From the repository root, regenerate only the artifacts whose sources changed:+- Never recursively package the live working tree with an unrestricted `cp`, `rsync`, or equivalent operation.+- Use a tracked-only, symlink-safe staging path or an explicit allowlist.+- Add a negative test proving that an untracked file and an external symlink cannot enter the archive.+- Test the extracted package outside the repository and, when applicable, on every advertised host or operating-system shape.+- Treat a published version as immutable. If host-visible plugin or Skill bytes change, use the agreed next release identity and keep every relevant manifest synchronized. Do not reuse a tag or version for different content.++Do not change release versions, tags, or distribution identities in an ordinary feature PR unless the issue or a maintainer explicitly includes release work in scope.++## Generated artifacts++Review source and tests before flooding a PR with generated output. Regenerate only artifacts whose authoritative inputs changed, ideally once after the implementation is accepted.++From the repository root, the main builders are:```bashnode scripts/build-gallery.mjs docsnode scripts/build-guide.mjs docs/guide.htmlnode scripts/build-start.mjs docs/start.htmlnode scripts/build-readme-showcase.mjs-node scripts/build-zip.sh /tmp/archify-contrib.zip+scripts/build-zip.sh /tmp/archify-contrib.zip```-Bundled example or viewer changes normally require the Gallery rebuild. Skill runtime, schema, renderer, or published `SKILL.md` changes require checking `archify.zip` freshness and committing a rebuilt archive when the checked-in package contents differ. Do not regenerate unrelated artifacts simply to produce a large diff.+Bundled example or viewer changes normally require the Gallery rebuild. Skill runtime, schema, renderer, or published `SKILL.md` changes require checking `archify.zip` freshness and committing a rebuilt archive when the checked-in package contents differ.-Before submitting:+List every regenerated file in the PR description. Do not regenerate unrelated HTML, GIFs, screenshots, manifests, or archives merely to make the branch look current. Generated artifacts are evidence and delivery payloads, not a substitute for reviewing the source change.-```bash-cd archify-npm test-```+## Bug fixes++A useful bug report or fix contains:++1. The exact Archify version or commit, installation method, command, and environment.+2. The smallest redacted typed JSON that still reproduces the failure.+3. The complete machine-readable validation receipt or exact error.+4. Expected versus actual behavior.+5. A final-artifact screenshot only when the problem is visual.++Do not replace deterministic evidence with a screenshot. For visual defects, keep both the validator result and final rendered evidence.++## Community showcase submissions++Showcase cases should be reproducible proof, not promotional screenshots. Submit the original prompt, agent/client, exact model, Archify version, redacted typed JSON, artifact, validation receipt, and truthful visual-review status through `.github/ISSUE_TEMPLATE/showcase.yml`.++Maintainers may ask for a smaller source file, rerun validation, or decline a case that cannot be safely published. Inclusion is not guaranteed. Accepted cases should preserve author attribution and must not be presented as proof of model quality without a controlled benchmark protocol.++## Before requesting review++- Rebase or merge the latest `main`, resolve generated-artifact conflicts by rebuilding from the final source, and rerun affected checks.+- Complete `.github/PULL_REQUEST_TEMPLATE.md` with exact commands and numeric results; do not write only “tests pass.”+- Add or update a regression test for behavioral changes.+- Confirm existing public examples and compatibility fixtures still behave as intended.+- State `visual review: passed`, `failed`, or `skipped` truthfully for visible changes.+- Confirm remote CI actually ran on the current head. Local green checks do not mean GitHub CI passed, and zero checks is not green.+- Remove unrelated files, debug output, local paths, generated noise, and sensitive data from the diff.-Fill in `.github/PULL_REQUEST_TEMPLATE.md` with exact commands and results. Visible changes need before/after final-artifact evidence and a truthful `passed`, `failed`, or `skipped` visual-review status.+Maintainers may ask for a large PR to be split or rebuilt from current `main` when generated artifacts, stale history, or overlapping implementations make the behavior difficult to review safely.## Licensediff --git a/README_ZH.md b/README_ZH.mdindex 2d2a14e5..5578b950 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -285,3 +285,5 @@ Claude.ai 中的上传入口:## 参与贡献欢迎提交 Issue、Pull Request 和真实场景图。请先阅读[贡献指南](CONTRIBUTING.md);遇到问题时使用可复现 Bug 表单,也可以通过[社区 Showcase 表单](https://github.com/tt-a1i/archify/issues/new?template=showcase.yml)提交已验证成品。++较大的功能或行为调整请先通过 Issue 对齐价值、兼容边界和非目标,再基于最新 `main` 开发。一个 PR 尽量只解决一个问题;核心代码和回归测试先行,生成物最后统一重建。Archify 坚持 Agent-first,优先完善稳定的机器可读诊断和现有权威合同,避免新增容易与 CLI 漂移的重复说明。diff --git a/archify/test/community-proof-intake.test.mjs b/archify/test/community-proof-intake.test.mjsindex 04301857..5557da93 100644--- a/archify/test/community-proof-intake.test.mjs+++ b/archify/test/community-proof-intake.test.mjs@@ -73,11 +73,25 @@ test('contributor and pull-request guides keep proof changes reproducible and st'.github/ISSUE_TEMPLATE/bug-report.yml','npm test','node scripts/build-gallery.mjs docs',- 'node scripts/build-zip.sh','Do not include secrets',+ 'Agent-first',+ 'diagnostics[]',+ 'Start from the latest `main`',+ 'tracked-only, symlink-safe',+ 'is **skipped**, not passed',]) {assert.match(contributing, new RegExp(required.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')), required);}+ assert.match(+ contributing,+ /(?:^|\n)scripts\/build-zip\.sh \/tmp\/archify-contrib\.zip(?:\n|$)/,+ 'the archive builder must be documented as an executable shell script',+ );+ assert.doesNotMatch(+ contributing,+ /\bnode\s+scripts\/build-zip\.sh\b/,+ 'the shell archive builder must not be documented as a Node.js command',+ );for (const required of ['Stability impact','Tests run',diff --git a/archify/test/release-package-gates.test.mjs b/archify/test/release-package-gates.test.mjsindex c9bc135a..6e5b46b8 100644--- a/archify/test/release-package-gates.test.mjs+++ b/archify/test/release-package-gates.test.mjs@@ -144,6 +144,37 @@ test('package smoke rejects every dependency metadata field in a built package',}});+test('archive build excludes untracked files and external symlinks from the live working tree', () => {+ const marker = `.package-negative-${process.pid}-${Date.now()}`;+ const untracked = path.join(repoRoot, 'archify', `${marker}.txt`);+ const externalRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-external-'));+ const externalTarget = path.join(externalRoot, 'secret.txt');+ const externalLink = path.join(repoRoot, 'archify', `${marker}.link`);+ const outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-negative-'));+ const archive = path.join(outputRoot, 'archify.zip');++ try {+ fs.writeFileSync(untracked, 'must not ship\n');+ fs.writeFileSync(externalTarget, 'external content must not ship\n');+ fs.symlinkSync(externalTarget, externalLink, 'file');++ const build = spawnSync(path.join(repoRoot, 'scripts', 'build-zip.sh'), [archive], {+ cwd: repoRoot,+ encoding: 'utf8',+ });+ assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);++ const listing = spawnSync('unzip', ['-Z1', archive], { encoding: 'utf8' });+ assert.equal(listing.status, 0, `${listing.stdout}\n${listing.stderr}`);+ assert.doesNotMatch(listing.stdout, new RegExp(marker), 'untracked files and symlinks must not enter the archive');+ } finally {+ fs.rmSync(untracked, { force: true });+ fs.rmSync(externalLink, { force: true });+ fs.rmSync(externalRoot, { recursive: true, force: true });+ fs.rmSync(outputRoot, { recursive: true, force: true });+ }+});+test('CI tests the declared Node floor plus every maintained current lane', () => {const packageJson = JSON.parse(fs.readFileSync(path.join(repoRoot, 'archify', 'package.json'), 'utf8'));assert.equal(packageJson.engines?.node, '>=18');diff --git a/archify/test/route-share-card.test.mjs b/archify/test/route-share-card.test.mjsindex 15b260af..c94cde98 100644--- a/archify/test/route-share-card.test.mjs+++ b/archify/test/route-share-card.test.mjs@@ -157,7 +157,11 @@ test('skill and READMEs describe the optional Export variant and show one real cassert.equal(png.readUInt32BE(20), 630);const buildZip = fs.readFileSync(path.join(repoRoot, 'scripts/build-zip.sh'), 'utf8');- assert.match(buildZip, /--exclude '\.validator-check-\*'/, 'concurrent validator scratch must never leak into archify.zip');+ assert.match(+ buildZip,+ /git -C "\$repo_root" ls-files -z -- archify/,+ 'archive inputs must come from Git tracking so concurrent validator scratch cannot leak into archify.zip',+ );});process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));diff --git a/scripts/build-zip.sh b/scripts/build-zip.shindex 72185bbb..50c9b5fc 100755--- a/scripts/build-zip.sh+++ b/scripts/build-zip.sh@@ -9,29 +9,44 @@ if [[ "$out" != /* ]]; thenout="$(pwd)/$out"fi-# Stage a clean copy: node_modules never ships; test/ is repo-only (the golden-# harness compares against ../examples at the repo root, which does not exist-# in an installed skill); local agent coordination folders are also excluded so-# a developer's working tree cannot leak into the distributable archive. The npm-# scripts and build-only dependencies are stripped from the shipped-# package.json. Runtime schema validation is provided by the committed-# standalone validators, so installing the skill never requires npm install.+# Stage only files tracked by Git. This keeps untracked working-tree content out+# of the archive, and rejecting tracked paths that are symlinks prevents an+# archive build from reading through links to content outside the repository.+# test/ is repo-only (the golden harness compares against ../examples at the+# repo root, which does not exist in an installed skill). The npm scripts and+# build-only dependencies are stripped from the shipped package.json. Runtime+# schema validation is provided by the committed standalone validators, so+# installing the skill never requires npm install.stage="$(mktemp -d)"trap 'rm -rf "$stage"' EXITif [[ ! -f "$repo_root/archify/renderers/shared/generated-validators.mjs" ]]; thenecho 'generated validators are missing — run npm run generate:validators in archify/' >&2exit 1fi-rsync -a \- --exclude 'node_modules' \- --exclude 'test' \- --exclude 'scripts/generate-brand-marks.mjs' \- --exclude 'scripts/generate-validators.mjs' \- --exclude '.DS_Store' \- --exclude '.hive' \- --exclude '.workbuddy' \- --exclude '.validator-check-*' \- "$repo_root/archify/" "$stage/archify/"+while IFS= read -r -d '' tracked; do+ case "$tracked" in+ archify/test | archify/test/* | \+ archify/package-lock.json | \+ archify/scripts/generate-brand-marks.mjs | \+ archify/scripts/generate-validators.mjs)+ continue+ ;;+ esac++ source="$repo_root/$tracked"+ if [[ -L "$source" ]]; then+ echo "refusing to package tracked symlink: $tracked" >&2+ exit 1+ fi+ if [[ ! -f "$source" ]]; then+ echo "tracked package input is missing or not a regular file: $tracked" >&2+ exit 1+ fi++ target="$stage/$tracked"+ mkdir -p "$(dirname "$target")"+ cp -p "$source" "$target"+done < <(git -C "$repo_root" ls-files -z -- archify)node -e "const fs = require('fs');const p = '$stage/archify/package.json';