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:
$idis unregistered; first confirm the Contracts version and$idnamespace. - 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 callrecoverStateStoreLockwith 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 APIapplyHostPlanis limited to digest-bound local install/update for registered hosts; executing an uninstall plan returnsmanual-recovery-requiredwithout deleting files. The full Qoder driver remains unsupported. - Peer-adapter verification fails:
verifyHostPeersaccepts only hosts and path categories proved by registered Profiles. Any peer path, closure, byte, orlogicalMappingsmismatch 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.mdanddocs/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.