Lingtai Kernel Dev

LingTai Kernel Development

Read this skill before every development task in this repository. It owns the workflow; Anatomy owns structure and Contract owns interface promises. Follow its links instead of copying the root documents into this file.

Above all, root CONTRACT.md ## Design principles is mandatory reading, and you MUST apply every one of those principles to each change — including the i18n gate, progressive disclosure, the manual-per-capability rule, and manual discoverability from both the capability CONTRACT.md and its paired ANATOMY.md (related_files on both twins; one edge alone is a defect). Route each change to the manual that teaches the capability it touches.

First establish the task and baseline

1. Re-read the latest human or maintainer instruction. Separate the requested change from suggested follow-up work and from unauthorized side effects.
2. Name the selected baseline: normally live origin/main, or an explicit tag or commit chosen by the maintainer.
3. Work in a real repository worktree. Before analysis or editing, prove the worktree is clean and HEAD equals the selected baseline. A directory name or recorded SHA without equality is not enough.
4. Use a focused branch and keep unrelated local/runtime worktrees untouched.

See CONTRIBUTING.md for the public contribution workflow and its route to the full coding-agent and test reference.

Read the distributed systems before editing

Use progressive disclosure in this order:

1. Read root ANATOMY.md, then descend through the nearest child anatomy until cited code answers where the relevant files, connections, composition, and state live.
2. Read root CONTRACT.md, beginning with ## Design principles. If the component is governed, read its paired local contract before changing its interface or expected behavior.
3. Read the cited code and narrow tests. Anatomy is navigation, not evidence in place of code; Contract is the normative promise, not a description to weaken when implementation drifts.
4. Load a narrower manual only when the task needs its commands, examples, or troubleshooting. Do not preload unrelated references.

The lingtai-kernel-anatomy skill owns how to enter and descend those two graphs; this skill owns how to develop and validate a change.

Make the smallest complete change

Before editing, state the relevant invariant, the intended variation axis, and the explicit non-goals. Prefer one behavior-locked boundary or vertical slice over a directory reshuffle or speculative abstraction.

For every code or architecture-document change, assess both distributed systems:

• Files, symbols, connections, composition, or state ownership changed: update the relevant Anatomy in the same PR.
• Port, Adapter, Behavior, error, ordering, retry, cancellation, recovery, or state semantics changed: update the relevant Contract and shared contract tests in the same PR.
• Both changed: update the pair together.
• Neither changed: record that both were checked; do not create documentation churn to simulate compliance.

Follow the repair direction defined by root CONTRACT.md ## Maintenance contract: verified code is normally the structural truth for Anatomy, while Contract is normative for interface and Behavior, so implementation drift is a defect unless a maintainer explicitly authorizes a promise change. Do not create a second graph registry; maintain YAML related_files around the nodes you touch.

Classify the Anatomy/Contract relationship first

Root CONTRACT.md owns the full pairing and ownership rule: a governed architectural component owns reciprocal Anatomy/Contract twins, while an implementation, Adapter, or navigation-only Anatomy instead points to exactly one owning governed Contract and explains why it has no independent local Contract. Never manufacture an empty or duplicate Contract for filename symmetry. If the relationship does not satisfy the root rule, stop and report the root-defined mismatch fields and suggested action; do not normalize or auto-fix it without authorization.

Tridirectional linkage: Contract ⇄ Behaviors ⇄ Anatomy

Root BEHAVIORS.md defines the LingTai Agent Behavior Task (LABT) system: self-contained agent-executable scenarios that prove the contract's important behavior clauses do not drift. BEHAVIORS.md is the sibling of CONTRACT.md (stronger connection: every important behavior clause is verified by a LABT); the paired ANATOMY.md is the third node, and all three files are interconnected if applicable. A governed component MAY own a BEHAVIORS.md beside its CONTRACT.md/ANATOMY.md when it has agent-observable behavior worth verifying (see the audit: candidates are the CONVERT_BEHAVIOR pytest files). The three documents cross-link instead of duplicating:

• contract → behaviors: every important behavior clause in a CONTRACT.md MUST reference the guarding LABT(s) with a relative [B###](BEHAVIORS.md#behavior-b###) link.
• behaviors → contract: every LABT MUST annotate the clause it guards (guards: <contract-name> § <clause>) with a link back.
• behaviors ↔ anatomy: the paired ANATOMY.md lists BEHAVIORS.md in related_files and names the LABT ids in entries for implementing code.

Change one, check the other two. When any of the three changes in a way that could affect agent-observable behavior, update or at least re-check the other two in the same change. This is a review gate, not optional polish; the root BEHAVIORS.md carries the full LABT format and templates.

When migrating a CONVERT_BEHAVIOR pytest to a LABT, record the original pytest as supersedes in the behavior entry so the trace stays complete; the pytest may be kept for bottom asserts or removed per judgment.

Keep Maintenance guidance aligned

When you create or update a child component CONTRACT.md, keep its maintenance note concise and aligned with root CONTRACT.md: retain complete, safe related_files, reciprocal Anatomy/Contract and ownership links, and the rule to update the pair when structure or normative behavior changes. The note is documentation, not a byte-identical snapshot; do not add a second registry or a generated/hash-based maintenance mechanism.

Validate in layers

Run the narrowest decisive checks first, then the affected broader checks. At a minimum:

python -m pytest -q <targeted-tests>
python -m pytest -q tests/test_architecture_documents.py  # when either graph changes
# Run the canonical Anatomy drift checker in --check mode (see the Anatomy skill).
git diff --check

tests/test_architecture_documents.py validates frontmatter path safety, root and child pairing, reciprocal graph links, and unique ownership for linked implementation Anatomies. If it reports a mismatch, stop and report the offending path and links rather than silently normalizing or auto-fixing documents.

Also run package, import, build, adapter, or source-drift tests when the diff crosses those boundaries. Use the repository virtual environment, inspect every non-zero exit, and never report a timed-out or interrupted suite as passing. Review the final diff against the human instruction and name any untested risk.

Pull-request and side-effect gate

Use a pull request; never push directly to main. Before committing, pushing, or opening the PR:

1. re-read the latest human scope and authorization;
2. verify live base equality and stop if the base moved;
3. verify local Git author identity and the intended GitHub CLI account;
4. ensure the staged diff contains only the reviewed change;
5. capture focused validation evidence and unresolved risks.

Commit, push, open/close/merge PRs, publish, install, refresh, release, or change configuration only within the maintainer's explicit authorization for that specific side effect. Opening a PR does not imply permission to merge it.

Keep documentation frontmatter current

Every Markdown file in the repository — including this file's own frontmatter above — must carry related_files and maintenance YAML metadata, checked by docs.yaml and validated by scripts/check_docs_governance.py / tests/test_docs_governance.py. This is a separate, generic baseline from the Anatomy/Contract frontmatter schemas above — do not conflate them. When you add or edit a doc, fill in real related_files/maintenance; when you create a new governed component ANATOMY.md/CONTRACT.md, its stricter specialized schema already satisfies this baseline.

Grow this as the repository agent dev kit

This directory owns the kernel repository's complete reusable development kit, not only this entry document. Add supporting material when real repeated work justifies it: scripts/ for deterministic checks, maintenance, or generation; references/ for deep procedures loaded only when needed; assets/ for templates, examples, or fixed resources. Do not create empty directories or copy repository rules into support files.

Keep one SKILL.md entry and let it route progressively: detailed architecture belongs in Anatomy/Contract, and tool-specific recipes belong in the narrower manuals they own. When this workflow changes, update this skill and the README/Anatomy/Contract entry routes together; change the normative root documents only when their own meaning, schema, or promises change.