Structure of Archify's Diagnostic Objects: Schema, Properties, and Usage

Archify's diagnostic objects follow a strict five-property schema—code, severity, subject, evidence, and supportedFixes—that enables deterministic error reporting and automated repair workflows.

The tt-a1i/archify repository uses these structured diagnostics to communicate validation failures, runtime errors, and repair suggestions across its skill ecosystem. Understanding the exact structure of Archify's diagnostic objects is essential for developers building custom skills or integrating with Archify's repair receipt system.

The Five Required Properties of Every Diagnostic

Every diagnostic emitted by the Archify engine conforms to a rigid contract. According to assertions in test/repair-receipt.test.mjs, a valid diagnostic object must contain five required fields, with optional additional metadata permitted.

Property	Type	Description
code	string	A stable, namespaced identifier for the rule that generated the diagnostic (e.g., schema/additionalProperties, output/input-alias).
severity	"error" | "warning" | "info"	The seriousness of the issue. Errors halt execution, warnings allow continuation, and info messages are advisory.
subject	object	A JSON-pointer-style description of the affected resource, using domain-specific keys like path, output, or check.
evidence	object	Concrete data explaining why the diagnostic was raised. Shape varies by diagnostic type (e.g., reason, rowCount).
supportedFixes	string[]	An array of human-readable suggestions or machine-parsable actions that can resolve the problem.

code

The code property provides a stable identifier for the specific rule violation. As implemented in tt-a1i/archify, these codes follow a hierarchical namespace pattern such as input/json-parse or output/symlink-cycle. This naming convention allows automated tools to parse the category and sub-category of any error without parsing free-form text.

severity

The severity field controls execution flow. Valid values are strictly limited to three literals: "error", "warning", and "info". When severity equals "error", the current operation blocks until resolved, whereas "warning" permits the skill to complete while logging the issue for review.

subject

The subject object acts as a locator, identifying exactly which file, configuration key, or output path triggered the diagnostic. According to docs/authoring-cookbook.md, this property uses JSON-pointer semantics but wraps them in domain-specific keys. For example, { path: '/meta/legend' } points to a specific metadata field, while { output: '/public/assets/logo.svg' } identifies a build artifact.

evidence

The evidence object contains immutable contextual data that justifies the diagnostic's existence. The shape is polymorphic depending on the code: a JSON parse error includes { reason: 'Unexpected token...' }, while a symlink cycle includes { cycle: ['/path/a', '/path/b'] }. As noted in docs/research-architecture-delta-pr-proof-2026-07-23.md, this evidence ensures that diagnostics are self-contained and serializable for deterministic receipts.

supportedFixes

The supportedFixes array lists actionable resolutions. Each entry is a string describing either a human-readable instruction or a machine-parsable command. For repairable diagnostics, this array is guaranteed non-empty, enabling the automated repair workflows demonstrated in scripts/package-smoke.mjs.

Real-World Examples from the Test Suite

The following examples from test/repair-receipt.test.mjs illustrate how these properties combine in practice.

A malformed input diagnostic:

const jsonParseDiagnostic = {
  code: 'input/json-parse',
  severity: 'error',
  subject: { input: '/meta/user' },
  evidence: { reason: 'Unexpected token < in JSON at position 0' },
  supportedFixes: ['repair the JSON syntax and run validation again']
};

A filesystem cycle diagnostic:

const symlinkCycleDiagnostic = {
  code: 'output/symlink-cycle',
  severity: 'error',
  subject: { output: '/public/assets/logo.svg' },
  evidence: { cycle: ['/public/assets/logo.svg', '/public/assets/logo.png'] },
  supportedFixes: ['remove the symlink that creates the cycle']
};

How Diagnostics Flow Through the System

Archify's diagnostic structure is not merely a logging format—it is the backbone of the repair receipt system.

docs/authoring-cookbook.md defines the contract that skill authors must follow when emitting diagnostics, ensuring that all skills produce compatible error objects. When the engine packages a skill, scripts/package-smoke.mjs consumes these diagnostics to validate that no errors exist before publication. Finally, docs/research-architecture-delta-pr-proof-2026-07-23.md describes how diagnostics are sorted and serialized into deterministic repair receipts, allowing agents to compare states across runs.

Summary

• Archify diagnostic objects require exactly five properties: code, severity, subject, evidence, and supportedFixes.
• The code uses dot-slash namespacing for stable rule identification.
• severity controls execution flow with three strict levels: error, warning, and info.
• subject provides JSON-pointer-style locators, while evidence contains immutable contextual data.
• supportedFixes enables automated repair by listing concrete resolution steps.
• Source definitions appear in test/repair-receipt.test.mjs, docs/authoring-cookbook.md, and related architecture documents.

Frequently Asked Questions

What properties are mandatory in an Archify diagnostic object?

Every diagnostic must include code, severity, subject, evidence, and supportedFixes. Optional fields such as message or detail may appear for human readability, but the five core properties are required for structured repair receipts and automated processing.

How does the severity field affect Archify's behavior?

When severity is set to "error", the current operation halts immediately, blocking skill execution until the issue is resolved. "warning" allows the process to continue while logging the issue, and "info" provides advisory output that does not affect exit codes.

Where are diagnostic structures enforced in the codebase?

Test assertions in test/repair-receipt.test.mjs validate the full object shape, while docs/authoring-cookbook.md documents the contract for skill authors. Runtime consumption occurs in scripts/package-smoke.mjs, which checks for diagnostic presence before packaging.

How do supportedFixes enable automated repairs?

The supportedFixes array provides a machine-parseable list of actions that resolve the diagnostic. By standardizing this field, Archify permits automated agents to read the array and apply fixes without human intervention, forming the basis of the repository's repair receipt workflow.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}