跳转至

简体中文

Help and Triage

This page provides triage paths by error code, process exit code, and symptom. Foundation's error-code system is frozen in Contracts (src/error-codes.json) and does not drift; mechanism failures are unified as SFC2004 with a stable details.kind.

Triage by Stable Error Code

Error code Name Meaning Handling
SFC1001 SCHEMA_VALIDATION_FAILED Document failed target Schema validation Check the document's required fields and type constraints
SFC1002 UNKNOWN_SCHEMA_ID $id is not registered in the registry Confirm the $id spelling and Contracts version
SFC1003 DUPLICATE_SCHEMA_ID Duplicate $id registration refused Do not re-register; reuse the existing registration
SFC1004 DUPLICATE_PROTOCOL_NAME Duplicate protocol name/version refused Do not re-register a protocol
SFC1005 UNRESOLVED_REF $ref target cannot be resolved Check the $ref target
SFC1006 UNSUPPORTED_DIALECT Dialect is not in the supported set Use only draft-07 / 2020-12
SFC1007 UNKNOWN_CHECK_TYPE Rule uses a check type outside the nine classes Do not define custom check types
SFC1008 RULE_BUDGET_EXCEEDED Mandatory rule exceeded budget/ceiling Do not exceed 20 (absolute 30)
SFC1009 UNKNOWN_ERROR_CODE Referenced an unregistered error code Reference only the frozen registry
SFC1010 FIXTURE_EXPECTATION_MISMATCH Fixture behavior does not match expectation Check the fixture declaration
SFC1011 UNKNOWN_PROTOCOL Referenced an unregistered protocol Confirm protocol name/version
SFC1012 SCHEMA_COMPILE_FAILED The Schema itself cannot be compiled Check Schema syntax
SFC2002 UNKNOWN_OPERATION Operation name is not in the frozen vocabulary Use only validate
SFC2003 INVALID_PARAMS Parameters do not satisfy the params contract Check parameters
SFC2004 EXECUTION_FAILED Mechanism execution failed See details.kind for the sub-classification
SFC3001 REPORT_DIGEST_MISMATCH Report/result digest is inconsistent with the binding Recompute model/result
SFC3002 REPORT_ELEMENT_MISSING Report is missing a mandatory element Complete the report fields
SFC3003 REPORT_FACT_DRIFT Report bytes deviated from deterministic re-render Re-render from machine results

Triage by Process Exit Code (Engineering Kit)

Exit code Meaning Handling
0 Success / no findings No handling needed
1 check found findings Address the findings; Kit does not auto-fix
2 Refused / usage / mechanism error Check command name, parameters, and refused flags such as --fix

Triage by Symptom

  • Validation keeps reporting SFC1002: $id is unregistered; first confirm the Contracts version and $id namespace.
  • Path operation reports SFC2004 + path-traversal/symlink-escape/realpath-escape: the path escaped the contained root; confirm the root-directory boundary, and do not cram business-selection rules into Foundation.
  • Atomic write reports SFC2004 + atomic-write-failed: the target is out of bounds or the content type is illegal; check path containment and content type.
  • State storage reports store-locked: an old writer may still hold the lock; confirm outside Foundation that the old writer has terminated, then call recoverStateStoreLock with the exact owner/fencing.
  • CLI host apply fails immediately: Engineering Kit's adopt-plan host-apply, generic apply, and remote apply remain stably refused. The package API applyHostPlan is limited to digest-bound local install/update for registered hosts; executing an uninstall plan returns manual-recovery-required without deleting files. The full Qoder driver remains unsupported.
  • Peer-adapter verification fails: verifyHostPeers accepts only hosts and path categories proved by registered Profiles. Any peer path, closure, byte, or logicalMappings mismatch fails closed and does not grant install or release status.
  • Document versions/commands do not match the source of truth: rely on the recomputation result of scripts/docs/fact-check.mjs; do not revise from memory.

Project Routing

  • Publishing remote state / npm publish → release-skill.
  • Tasks / retries / rework / acceptance → loop-agent.
  • Artifact relationships / version-lock → artifact-graph.
  • Domain-audit semantics → independent audit consumer.
  • General structure / mechanism issues → this repository's docs/architecture.md and docs/agents/.

Command Quick Reference and Authoritative Facts

The Engineering Kit has only four top-level commands: scaffold, adopt-plan, projection, check. Of these, check only diagnoses and does not fix; the caller handles the findings.

  • Current product status (versions, package set, mirror coordinates, gates): Current Product Status (the single status page).
  • Development and commit specifications: Git Lifecycle Guide.