fix(harness-component-snapshot): keep bounded diffs and usage errors useful

Post-merge review of pull request 69 found that a bounded diff sorted entries
by component ID only, so `unchanged` entries consumed the limit and a small
`--limit` could truncate away the only real difference while still reporting
`truncated: true`. Entries now order `changed`, `added`, and `removed` before
`unchanged`, falling back to the canonical component ID order so results stay
deterministic. Counts already covered every component and are unchanged.

CLI usage failures collapsed every argument problem into one opaque message.
The sanitization was protecting real privacy, because an unrecognized command
or option is caller-supplied argv that can hold a private path, but it also
discarded safe detail. Usage diagnostics now name the specific reason and, for
missing-value, duplicate, and missing-required failures, the allowlisted flag,
while never echoing an unrecognized token or any option value.

Two review findings are documentation rather than behavior: the v1
`relationships` set is fully derivable from `components`, which is now recorded
in `contract.mjs` and HCS-AC-5 as a deliberate extension point instead of
looking like accidental redundancy; and byte-level revisions differ across
operating systems when line-ending normalization differs, which the spec now
carries as an explicit risk against cross-platform `--population-key` diffs.

`.gitignore` re-includes `test/fixtures/**/.qoder/`. Those fixtures were only
tracked because they had been force-added, so new fixture assets under that
path were invisible to `git status`.

Symlink-tolerance consistency and the hard-coded read surface in
`assertProjectReadBoundaries` are recorded in the spec as deferred findings
rather than changed here, since each is a design decision beyond this slice.

Validated with `npm test` at 1290 passing, 0 failing, 0 skipped, doc links 6/6,
`npm run pack:verify` at 458 npm and 480 runtime-zip entries, and a manual
`diff --limit 1` check confirming the changed entry now survives truncation.

Co-authored-by: QoderAI (Qwen 3.8 Max) <qoder_ai@qoder.com>

Author: phodal

.gitignore

@@ -1,5 +1,6 @@
 .DS_Store
 .qoder/
+!test/fixtures/**/.qoder/
 node_modules/
 dist/
 outputs/

docs/specs/2026-08-02-harness-component-snapshot-v1.md

@@ -57,7 +57,10 @@ contract before generalizing across providers.
 - **HCS-AC-5 (minimal graph):** Each component has one typed `declared-in`
   relationship to its privacy-safe workspace artifact reference. Relationship
   validation rejects unknown component IDs, absolute targets, and mismatched
-  provenance instead of inferring semantic dependencies.
+  provenance instead of inferring semantic dependencies. In v1 this set is fully
+  derivable from `components`; it stays a serialized, validated field because the
+  typed relationship shape is the extension point for later relationship types,
+  so adding one must not be a breaking schema change.
 - **HCS-AC-6 (tamper-safe validation):** Validation recomputes component
   identity, relationship integrity, rollback references, ordering, and the
   snapshot digest. Stale or edited snapshots fail with stable diagnostic codes.
@@ -66,8 +69,11 @@ contract before generalizing across providers.
   counts. Revision changes are named `content`; route identity changes appear
   as one removal and one addition. Activation and provenance remain fixed,
   explicit evidence dimensions in this v1 producer and therefore cannot be
-  reported as changed without a future contract revision. Returned entries
-  obey an explicit bounded limit and report truncation. Different populations
+  reported as changed without a future contract revision. Counts always describe
+  every component, while returned entries obey an explicit bounded limit and
+  report truncation. Entries order `changed`, `added`, and `removed` before
+  `unchanged`, then by canonical component ID, so a small limit cannot hide the
+  actual differences behind redundant unchanged entries. Different populations
   fail closed.
 - **HCS-AC-8 (non-authorizing rollback reference):** Every component exposes a
   parseable reference binding provider, scope, population-qualified component
@@ -81,9 +87,12 @@ contract before generalizing across providers.
   `--population-key`, `validate`, `diff`, and `resolve` with parser-safe JSON
   stdout and usage/runtime failures on stderr. Runtime diagnostics expose a
   stable code without echoing caller-selected paths or untrusted snapshot
-  fields. Public API failures use stable sanitized messages without appending
-  filesystem or parser error details. Global and leaf help remain help-only
-  human text and do not inspect a workspace.
+  fields. Usage diagnostics name the specific failure reason and may name an
+  allowlisted flag, but never echo an unrecognized command, unrecognized option,
+  or any option value, because those are caller-supplied argv that can hold a
+  private path. Public API failures use stable sanitized messages without
+  appending filesystem or parser error details. Global and leaf help remain
+  help-only human text and do not inspect a workspace.
 - **HCS-AC-10 (portable evidence):** Fixtures cover Windows, macOS, and Linux
   route forms, stable input ordering, provider/scope isolation, secret and home
   sentinels, hook activation, tampering, bounded diff states, and rollback
@@ -148,7 +157,9 @@ from accepted host evidence to the component snapshot contract.
   rollback-reference mismatches.
 - **HCS-AC-9:** `node --test test/harness-component-snapshot-cli.test.mjs`
   verifies help, strict parsing, JSON stdout, path-safe stderr failures, and all
-  four direct CLI operations. Contract tests also verify that malformed Hook
+  four direct CLI operations. A dedicated case asserts that usage failures name
+  an allowlisted flag while never echoing an unrecognized command, unrecognized
+  option, or option value. Contract tests also verify that malformed Hook
   input cannot expose parser details, caller paths, or private sentinels through
   the public API error message.
 - **HCS-AC-10:** `node --test test/doc-link-graph.test.mjs`,
@@ -165,6 +176,25 @@ from accepted host evidence to the component snapshot contract.
   follow-up additionally replaced per-read workspace-root resolution with a
   snapshot-scoped boundary and removed parser/filesystem details from public
   Hook configuration errors.
+- **Post-merge review follow-up (2026-08-05):** A maintainer review after the
+  merge of pull request 69 corrected the observed repository-wide count above: on
+  the merged tree the run reports 1,289 passing with 0 failures and 0 skips on
+  macOS, not 1,288 passing with 1 skip. Four review findings were then applied on
+  `main`: bounded diff entries
+  now order significant statuses before `unchanged`; usage diagnostics name their
+  reason and any allowlisted flag; the v1 relationship redundancy and its
+  extension-point rationale are recorded in `contract.mjs` and HCS-AC-5; and
+  `.gitignore` re-includes `test/fixtures/**/.qoder/` so fixture assets are no
+  longer invisible to `git status`. Re-verification passed 1,290 tests with 0
+  failures and 0 skips, documentation links 6/6, and package verification at 458
+  npm and 480 runtime-zip entries.
+- **Deferred review findings (2026-08-05):** Two findings remain open rather than
+  fixed here, because each is a design decision beyond this slice. Symbolic-link
+  tolerance is inconsistent: probed collector roots and Skill trees reject any
+  symlink, while `workspaceFileEvidence` accepts one whose realpath stays inside
+  the workspace. `assertProjectReadBoundaries` also hard-codes the read surface of
+  `qoderWorkspaceRuleSources`, so a new rule source added in `agent-customize`
+  would silently narrow the fail-closed guarantee without failing a test.
 - **Risk — privacy:** A route or source field could expose an absolute home.
   Mitigation: accept only normalized workspace-relative routes and serialize
   no inventory path fields.
@@ -182,6 +212,16 @@ from accepted host evidence to the component snapshot contract.
   files cannot cross-diff or resolve rollback references. Repositories that
   relocate or compare across operating systems must provide the same opaque
   population key; only its domain-separated digest enters artifacts.
+- **Risk — line-ending normalization across operating systems:** A revision is a
+  digest of raw file bytes, so the same commit checked out with `core.autocrlf`
+  on Windows and with LF on Linux produces different revisions for every text
+  component. A cross-operating-system diff that shares one explicit
+  `--population-key` would then report each component as a `content` change.
+  Mitigation for this repository: `.gitattributes` pins `eol=lf` for `.md`,
+  `.json`, `.mjs`, `.js`, `.yaml`, and `.yml`. Snapshotted consumer projects
+  carry no such guarantee, so cross-operating-system comparison requires a
+  matching checkout normalization; byte-identical revisions are not claimed
+  across differing line-ending configurations.
 - **Risk — incomplete rollback:** A privacy-safe snapshot cannot itself restore
   omitted source bytes. The v1 reference is resolvable and non-authorizing;
   executable restore remains gated on a future content-store or Git provenance

scripts/harness-component-snapshot/README.md

@@ -20,6 +20,11 @@ node scripts/harness-component-snapshot/cli.mjs resolve --snapshot before.json -
 valid snapshot. Its result always sets `mutationAuthorized` to `false`; this
 capability neither stores source bodies nor restores files.
 
+`diff` counts always describe every component, while `entries` is bounded by
+`--limit`. Entries list `changed`, `added`, and `removed` before `unchanged`, so
+a small limit truncates redundant unchanged entries rather than the actual
+differences; `truncated` and `totalEntries` report what was dropped.
+
 Without `--population-key`, the population reference is a privacy-safe digest
 of the canonical workspace boundary, so two unrelated workspaces cannot be
 cross-diffed accidentally. Use the same opaque key only when two locations are

scripts/harness-component-snapshot/cli.mjs

@@ -26,30 +26,35 @@ Operational commands emit one JSON document on stdout; help emits this text.
 
 const COMMANDS = new Set(["create", "validate", "diff", "resolve"]);
 
+// Usage reasons stay explicit, but only allowlisted flag names may appear in
+// them. Unrecognized commands and options are caller-supplied argv that can
+// hold a private path, so they are reported without their value.
 class UsageError extends Error {
-  constructor(message) {
-    super(message);
+  constructor(reason, safeFlag) {
+    super(safeFlag ? `${reason}: ${safeFlag}` : reason);
     this.code = "INVALID_USAGE";
     this.exitCode = 64;
+    this.usageReason = reason;
+    this.usageFlag = safeFlag;
   }
 }
 
 function parseOptions(argv, allowed) {
   const options = {};
   for (let index = 0; index < argv.length; index += 1) {
     const flag = argv[index];
-    if (!flag.startsWith("--") || !allowed.has(flag)) throw new UsageError(`unknown option: ${flag}`);
+    if (!flag.startsWith("--") || !allowed.has(flag)) throw new UsageError("unrecognized option");
     const value = argv[index + 1];
-    if (value === undefined || value.startsWith("--")) throw new UsageError(`missing value for ${flag}`);
-    if (Object.hasOwn(options, flag)) throw new UsageError(`duplicate option: ${flag}`);
+    if (value === undefined || value.startsWith("--")) throw new UsageError("missing option value", flag);
+    if (Object.hasOwn(options, flag)) throw new UsageError("duplicate option", flag);
     options[flag] = value;
     index += 1;
   }
   return options;
 }
 
 function requireOption(options, flag) {
-  if (!options[flag]) throw new UsageError(`missing required option: ${flag}`);
+  if (!options[flag]) throw new UsageError("missing required option", flag);
   return options[flag];
 }
 
@@ -70,7 +75,7 @@ export async function runHarnessComponentSnapshotCli(argv) {
     return;
   }
   const [command, ...rest] = argv;
-  if (!COMMANDS.has(command)) throw new UsageError(`unknown command: ${command}`);
+  if (!COMMANDS.has(command)) throw new UsageError("unrecognized command");
   if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
     process.stdout.write(HELP);
     return;
@@ -107,7 +112,7 @@ if (isMain) {
   runHarnessComponentSnapshotCli(process.argv.slice(2)).catch((error) => {
     const code = error.code ?? "SNAPSHOT_FAILED";
     const message = error instanceof UsageError
-      ? "invalid component snapshot arguments"
+      ? error.message
       : "component snapshot operation failed";
     process.stderr.write(`${code}: ${message}\n`);
     process.exitCode = error.exitCode ?? 1;

scripts/harness-component-snapshot/contract.mjs

@@ -249,6 +249,10 @@ function validateCoverage(snapshot) {
   }
 }
 
+// In v1 every relationship is exactly one `declared-in` edge per component, so
+// the set is fully derivable from `components`. It stays a serialized, validated
+// field because the typed relationship shape is the stable extension point for
+// later relationship types; adding one must not be a breaking schema change.
 function validateRelationships(snapshot) {
   if (!Array.isArray(snapshot.relationships)) fail("INVALID_RELATIONSHIPS", "snapshot relationships must be an array");
   const byId = new Map(snapshot.components.map((component) => [component.id, component]));

scripts/harness-component-snapshot/diff.mjs

@@ -10,6 +10,16 @@ import {
   validateHarnessComponentSnapshot,
 } from "./contract.mjs";
 
+// Significant statuses come first so a small limit truncates redundant
+// `unchanged` entries instead of hiding the actual differences. Ordering stays
+// deterministic because ties fall back to the canonical component ID order.
+const STATUS_ORDER = Object.freeze(["changed", "added", "removed", "unchanged"]);
+
+function compareEntries(left, right) {
+  const statusDelta = STATUS_ORDER.indexOf(left.status) - STATUS_ORDER.indexOf(right.status);
+  return statusDelta || compareCodeUnits(left.componentId, right.componentId);
+}
+
 function boundedLimit(value) {
   const limit = value === undefined ? 200 : Number(value);
   if (!Number.isInteger(limit) || limit < 0 || limit > MAX_DIFF_LIMIT) {
@@ -56,7 +66,7 @@ export function diffHarnessComponentSnapshots(before, after, options = {}) {
     componentId,
     beforeById.get(componentId),
     afterById.get(componentId),
-  ));
+  )).sort(compareEntries);
   const counts = Object.fromEntries(["added", "removed", "changed", "unchanged"]
     .map((status) => [status, allEntries.filter((entry) => entry.status === status).length]));
   const diff = {

test/harness-component-snapshot-cli.test.mjs

@@ -33,19 +33,38 @@ test("direct CLI provides global and leaf help without performing work", () => {
     const result = run(args);
     assert.equal(result.status, 64, `${args.join(" ")} unexpectedly succeeded`);
     assert.equal(result.stdout, "");
-    assert.equal(result.stderr, "INVALID_USAGE: invalid component snapshot arguments\n");
+    assert.match(result.stderr, /^INVALID_USAGE: unrecognized (command|option)\n$/u);
   }
 
   const privatePath = path.join(os.tmpdir(), "PRIVATE-USAGE-PATH-SENTINEL", "snapshot.json");
   for (const args of [[privatePath], ["validate", privatePath]]) {
     const result = run(args);
     assert.equal(result.status, 64);
     assert.equal(result.stdout, "");
-    assert.equal(result.stderr, "INVALID_USAGE: invalid component snapshot arguments\n");
+    assert.match(result.stderr, /^INVALID_USAGE: unrecognized (command|option)\n$/u);
     assert.equal(result.stderr.includes(privatePath), false);
+    assert.equal(result.stderr.includes("PRIVATE-USAGE-PATH-SENTINEL"), false);
   }
 });
 
+test("direct CLI names allowlisted flags in usage failures without echoing their values", async (t) => {
+  const { workspace } = await fixtureWorkspace(t);
+  const privateValue = path.join(os.tmpdir(), "PRIVATE-FLAG-VALUE-SENTINEL", "snapshot.json");
+
+  const missingValue = run(["create", "--workspace"]);
+  assert.equal(missingValue.status, 64);
+  assert.equal(missingValue.stderr, "INVALID_USAGE: missing option value: --workspace\n");
+
+  const duplicate = run(["create", "--workspace", workspace, "--workspace", privateValue]);
+  assert.equal(duplicate.status, 64);
+  assert.equal(duplicate.stderr, "INVALID_USAGE: duplicate option: --workspace\n");
+  assert.equal(duplicate.stderr.includes(privateValue), false);
+
+  const missingRequired = run(["validate"]);
+  assert.equal(missingRequired.status, 64);
+  assert.equal(missingRequired.stderr, "INVALID_USAGE: missing required option: --snapshot\n");
+});
+
 test("direct CLI creates parser-safe private JSON and rejects unknown options", async (t) => {
   const { workspace } = await fixtureWorkspace(t);
   const created = run([

test/harness-component-snapshot.test.mjs

@@ -476,6 +476,14 @@ test("bounded diff reports added, removed, changed, and unchanged independently"
   assert.equal(bounded.entries.length, 2);
   assert.equal(bounded.totalEntries, full.totalEntries);
   assert.equal(bounded.truncated, true);
+  assert.deepEqual(bounded.counts, full.counts);
+  assert.equal(bounded.entries.some((entry) => entry.status === "unchanged"), false);
+
+  const significant = diffHarnessComponentSnapshots(before, after, { limit: 3 });
+  assert.deepEqual(
+    significant.entries.map((entry) => entry.status),
+    ["changed", "added", "removed"],
+  );
   assert.throws(() => diffHarnessComponentSnapshots(before, after, { limit: 1001 }), { code: "INVALID_DIFF_LIMIT" });
 });