跳转至

简体中文

Help and Triage

This page helps developers choose the right entry point before using the error-code, process-exit, and symptom triage paths. 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.

Choose an Entry Point First

Problem Entry point Boundary
Determine whether an existing capability fits foundation-adoption-review The single natural-language adoption-diagnosis Skill. It reads caller-provided exact-version facts, capability-catalog query results, and adopt-plan results, then reports a full match, partial match, candidate match, no match, or a missed existing capability
Run a complete static engineering review or read an existing Foundation proof foundation-engineering-check The static engineering-review Skill in the same Plugin. It reviews selected engineering declarations, public capability adoption, and call boundaries, then projects a shared conclusion with check proof-create. Read an old proof with check proof. Passing the two mechanical version and entry branches is not a full-family pass
Inventory an existing project and compare it with the reference skeleton planAdoption({ root, allowGitSpawn: false }) or adopt-plan --no-git-spawn Read-only output covering the write set, conflicts, risks, and migration completion conditions. The reference skeleton is not a mandatory directory standard for every project
Compare engineering declarations with physical files runChecks, runCoreCheck, runEntryContractCheck, or check Reads files and configuration statically and reports findings within the selected check policy. It does not run target Skills, business scripts, or hooks
Initialize an empty directory or materialize a managed projection scaffold or projection Use only after the caller authorizes the corresponding writes. There is no generic apply for existing projects

The adoption-diagnosis Skill does not install or initialize a project, run check, probe qualification, or invoke a host. It also does not decide Audit compliance. It interprets supplied facts and points to a concrete public entry point; incomplete evidence remains a candidate or an open fact.

Governance Checks and Development Self-Tests

Governance checks inspect the target project's declarations, paths, and files. Ordinary check is read-only. It neither launches target programs nor proves that every file operation, permission, or internal procedure across a host is controlled by Foundation.

Development self-tests exercise Foundation itself. Package tests, host drivers, and qualification tests run only in an authorized development or verification workflow and establish facts about Foundation's implementation. A passing self-test does not replace the target project's domain gate, real-host qualification, or independent audit.

Existing checks retain their policy assumptions, including Foundation-style version sources, entry shapes, and the nine check classes. Interpret those results as policy findings only when the target project has adopted the corresponding policy. Do not force a single-package project, an independently versioned unit, a non-npm version source, or another entry shape into that policy. Treat stable capabilities, candidate capabilities, and the current source tree as separate states; see Current Product Status and the capability catalog for the exact version in use.

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

  • Published-capability fit / duplicate proposed mechanism → foundation-adoption-review.
  • Complete static engineering review / read an existing Foundation proof → foundation-engineering-check.
  • 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.