native-nostalgia-stack

原生怀旧技术栈

仅将契约材料应用于所请求的工作。项目 AGENTS 和文档规定实现规则和准确命令；project-structure/SKILL.md 规定与语言无关的布局和文档要求。

编译器和布局

• 使用项目和 CI 固定的 FPC 版本；新项目固定使用最新稳定版。除非项目文档明确选择其他模式，否则使用 Delphi 模式。
• 将项目范围的编译器指令放在一个共享 include 文件中，并由每个单元使用。
• 将 Pascal 源代码放在一个根目录下（优先使用 source/），使用带命名空间的文件名；在命名空间变得难以管理之前，保持扁平布局。
• 将单元测试与对应代码放在一起；将交付的端到端测试语料库放在根目录的 tests/ 下。
• 将所有被忽略的构建输出放在根目录的 build/ 下。
• 一次性 Pascal 脚本优先使用可执行的 InstantFPC；只有在明显更简单时，才使用现有任务运行器或动态语言。

编写或审查 Pascal 源代码时，请阅读 references/code-style.md。

构建契约

项目自行选择实现方式，但需提供一个根入口点：

• 不带参数调用时，执行所有二进制文件的干净开发构建；
• 位置参数名称用于选择一个或多个二进制目标；
• 默认使用开发配置，生产标志用于选择发布配置；
• clean 是一个目标，并且可以与其他目标组合使用；
• 每个二进制文件都输出到 build/ 下。

在 docs/build-system.md 中记录入口点、目标和标志；更改它们之前请先阅读该文档。

格式化工具和健康度契约

一个格式化工具／代码检查工具命令默认会重写 Pascal 代码，并提供非修改的 --check 模式；代码偏离规范时，该模式以非零状态码退出。项目特定的风格规则应放在工具和 docs/code-style.md 中，而不是分散在各处的配置文件中。

代码库健康度门禁需报告定位到具体位置的重复代码、每个函数的圈复杂度和认知复杂度、可排序的文件健康度，以及复杂度与变更频率相乘得到的热点。阈值和忽略项集中在一个根配置文件中；超出阈值时以非零状态码退出。在 docs/tooling.md 中记录该工具和阈值。

钩子

Lefthook 会对暂存的 Pascal 文件运行项目的格式检查，并运行构建与测试命令。使用项目的准确入口点，通过文档中的快速入门安装钩子；未经用户明确指示，绝不绕过钩子。

完成条件

• 已检查根目录和相关区域的 AGENTS，fpc -iV 与项目／CI 固定的版本一致，并且在依赖任何已修改工具的行为之前，已实时验证其版本。
• 已确认项目的格式化和构建与测试门禁均通过。
• 仅更新了本次更改所影响的权威文档。