بوّابة المطابقة
بوابة المطابقة
بوابة المطابقة في Apothem — الجزء الميكانيكي من بوابة ما قبل الإصدار ذات الخمسة عشر شريطًا (M1-M15) التي يجب أن يجتازها كل مُخرَج يُصدَر.
الأشرطة الخمسة عشر
| الشريط | المُعرِّف | التفويض | فئة الفحص | الإخفاق ← الإجراء |
|---|---|---|---|---|
| 1 | M1 | حياد المشروع المُضيف | استدلالي | راجِع لمطابقة اصطلاحات المُضيف |
| 2 | M2 | الانضباط التحريري (سجلّ الإفصاح) | استدلالي | أضِف علامات الإفصاح |
| 3 | M3 | أبعاد الجودة العشرة | ميكانيكي + استدلالي | راجِع الأبعاد المُخفِقة |
| 4 | M4 | التطبيق الذاتي (كتلة التحقّق حاضرة) | استدلالي | سجِّل كتلة التحقّق |
| 5 | M5 | مبدأ السلطة (لا هوية أو نقطة نهاية أو سرّ مُختلَق) | ميكانيكي | حوِّل إلى الاستفسار |
| 6 | M6 | دمج الخبرة (الثغرات المُبرَزة) | استدلالي | أبرِز الثغرات؛ واستشهد بالتحسينات |
| 7 | M7 | التعليق التوضيحي للخيارات (علامة Recommended + مبرّر العامل الحاسم) | ميكانيكي | علِّق توضيحيًا على مجموعات الخيارات |
| 8 | M8 | القطعية (لا تحوّط في النثر التوجيهي) | ميكانيكي | حوِّل التحوّطات إلى عبارات شرطية |
| 9 | M9 | الرافعة البصرية (الموضوعات البنيوية تحمل مخططات) | ميكانيكي + استدلالي | ألِّف المخطط / حدِّثه |
| 10 | M10 | الربط ثنائي الاتجاه (المؤشرات العكسية المتبادلة مُغلَقة) | ميكانيكي | أغلِق أنصاف الحواف |
| 11 | M11 | السباقات الرشيقة (الهدف / قائمة الأعمال / DoR / DoD / المراجعة / الاستعراض الاسترجاعي) | استدلالي | أعِد الهيكلة في صورة سباقات |
| 12 | M12 | تقارير المراحل والتخطيط الكانوني | ميكانيكي + استدلالي | ألِّف التقرير التجميعي؛ وانقل إلى التخطيط الكانوني |
| 13 | M13 | حِرفة الشيفرة (lint / format / type-check؛ الأرقام السحرية؛ bare-except) | ميكانيكي | طبِّق قواعد حِرفة الشيفرة الخاصة بكل لغة |
| 14 | M14 | المنظومية (يُعلِن المنبع / المصبّ / الأقران / المُنفِّذين) | ميكانيكي + استدلالي | أعلِن؛ وفهرِس في السجلّات |
| 15 | M15 | الجاهزية للإنتاج (اختبارات + وثائق + CHANGELOG + كوميت مطابق + CI أخضر + استقرار semver) | ميكانيكي + استدلالي | أضِف الأسطح الناقصة |
لا تُشغّل البوابة إلا أدوات تحقّق قابلة للفحص الآلي. أما الحكم الاستدلالي الذي تتطلّبه الأشرطة الاستدلالية، والنصف الاستدلالي من كل شريط ميكانيكي + استدلالي، فيُقيَّم في المراجعة.
سُلّم الخطورة
لا تملك البوابة سلّمًا من المستويات حرج ومهمّ واستشاري، ولا عتبة من نتيجتين. ومن دون --strict (أو APOTHEM_CONFORMITY_STRICT=1) تُبلغ البوابة عن النتائج وتخرج برمز 0. ومع --strict يخرج فحص الملف الواحد أو فحص الخطّاف برمز 2 عند فشل أي مُطابِق، ويخرج تشغيل المدوّنة (--all أو --all-perwrite) برمز 2 عند فشل أداة تحقّق حاجبة أو مُطابِق حاجب؛ أما النتائج الاستشارية فيُبلَّغ عنها فقط. ولا يمرّر خطّاف Write/Edit المثبَّت --strict، فيُبلغ عن النتائج وتمضي الكتابة ما لم يُضبط APOTHEM_CONFORMITY_STRICT=1 في بيئته.
أدوات التحقّق
يقع الجزء الميكانيكي في src/apothem/conformity/، ويُنسِّقه src/apothem/conformity/gate.py.
تعمل كل أداة تحقّق بإحدى ثلاث طرق:
- per-write: على كل كتابة معلّقة (
--hook)، أو على كل ملف متتبَّع مع--all-perwrite. - standalone: عبر المستودع كله مع
--all، أو واحدة تلو الأخرى مع--check <name>. - change-set: على فرق مُجهَّز للإيداع، وتُشغَّل مباشرةً بالصيغة
python -m apothem.conformity.semver_stability_grep --staged، لا عبر البوابة.
الجدول أدناه مُولَّد من وحدات أدوات التحقّق.
The conformity package ships 54 validators: 22 per-write, 31 standalone and 1 change-set. The gate registers the per-write and standalone ones.
| Validator | Runs | Rule anchor | What it checks |
|---|---|---|---|
agent-capability-grep | standalone | agent-capability-discipline (per-harness capability matrix) | Verify every harness declares its agentic-capability matrix. |
agents-md-coverage-grep | standalone | rules/agents-md-convention.md | Flag stale agent-companion files under the root-only AGENTS.md convention. |
agnosticism-grep | standalone | rules/agnostic-posture.md §3 (harness neutrality) + §1 (default-off) | Flag harness bias and re-introduced enforcement presets in shipped surfaces. |
always-on-budget-grep | per-write | D1 token-budget-discipline §Always-on body budget | Body-budget conformity matcher for always-on rules. Pointed at a rules directory it also holds the loaded always-on set and the rule index to byte ceilings. |
bare-except-grep | per-write | M13.3 error handling | Flag bare except clauses without typed exceptions or re-raise. |
binding-five-direction-grep | standalone | M10 bidirectional-binding §1 (five-direction Bindings section) | Require the five-direction Bindings section on every rule, command, agent, and skill. |
binding-reciprocity-corpus-grep | standalone | M10 bidirectional-binding §2 (↔ self-reciprocal) | Cross-file binding-reciprocity corpus walk — the ↔-symmetric half-edge check. |
binding-reciprocity-grep | per-write | M10 bidirectional-binding §Notation | Flag binding declarations using non-canonical arrow notation. |
brand-mark-grep | per-write | rules/plain-language.md (brand-mark display/identifier casing) | Flag brand-mark display/identifier form drift on brand-touched surfaces. |
commented-out-code-grep | per-write | M13.1 why-not-what comments | Flag substantial commented-out code blocks left in source. |
completion-claim-grep | per-write | rules/session-closure.md (verifiable-close output honesty) | Flag unsupported completion / guarantee claims in cohort prose. |
conventional-commit-grep | standalone | CLAUDE.md Coding Conventions — Conventional Commits | Flag HEAD commit messages that drift from the Conventional-Commits grammar. |
copilot-instructions-presence-grep | per-write | — | GitHub Copilot surface presence check. |
cross-platform-matrix-grep | standalone | cross-platform OS x Python CI matrix | Verify CI declares a cross-platform OS x Python matrix. |
determinism-grep | standalone | rules/determinism.md | Prove every command and skill surface has a deterministic output shape. |
diagram-staleness-grep | per-write | M9 visual-leverage §Fidelity | Flag diagrams whose verification date is missing or stale. |
dynamism-grep | standalone | rules/dynamism.md (static-version embeds) | Flag static-string version embeds in dynamism-required surfaces. |
editorconfig-presence-grep | standalone | supply-chain SOTA-rigor §editorconfig | Verify a canonical .editorconfig is present at the project root. |
file-header-grep | per-write | — | Authorship-header presence and canonical-form check. |
freshness-token-grep | standalone | rules/freshness-facade.md | Flag freshness-narrative phrases on shipped public surfaces. |
frontmatter-grep | per-write | the per-class frontmatter JSON Schemas (src/apothem/schemas/) | Validate per-artifact-class YAML frontmatter against required-key sets. |
frontmatter-value-grep | standalone | per-class JSON Schema enum/pattern value constraints | Validate frontmatter VALUES against the per-class JSON Schema enum/pattern constraints. |
gate-evidence-grep | standalone | commands/plan-execute.md Gate evidence; rules/pre-emission-gate-bars.md section 2 (attestation schema) | Advisory: flag plan-suite gate claims that lack a command, an exit status or output, and a HEAD SHA beside them, and fifteen-bar attestations that omit a field of the rule's schema. |
gitattributes-presence-grep | standalone | supply-chain .gitattributes contract | Verify the repo-root .gitattributes carries the canonical contract. |
harden-runner-grep | standalone | harden-runner egress baseline | Verify every workflow job opens with a conformant harden-runner step. |
hedging-grep | per-write | M8 definitiveness §Hedging | Flag hedging vocabulary in prescriptive contexts. |
license-author-consistency-grep | per-write | — | LICENSE author-identity presence check. |
link-check | per-write | rules/code-craft-markdown.md §6 Link Discipline | Validate Markdown internal links against the on-disk reference graph. |
magic-number-grep | per-write | M13.10 magic numbers | Flag magic numbers in source code. |
multi-surface-coherence-grep | per-write | — | Shared-claim coherence across AI-conventions surfaces. |
naming-grep | standalone | CLAUDE.md Coding Conventions (kebab-case naming) | Validate filesystem paths against the canonical naming convention. |
no-global-plans-grep | standalone | CLAUDE.md Plans Discipline (no global plans) | Walk the git index for tracked plans paths; fail when found. |
no-toplevel-docs-grep | standalone | single-source-of-truth (docs live in site/, not root docs/) | Fail when a top-level docs/ directory exists at the repository root. |
oidc-trusted-publishing-grep | standalone | OIDC trusted publishing | Verify release workflows use OIDC trusted publishing. |
option-annotation-grep | per-write | M7 option-annotation (H6 per-option bind) | Enforce the per-option Recommended label-to-body bind (H6). |
orphan-output-grep | per-write | M12 canonical-layout + M14 systemicity | Flag artifacts emitted to non-canonical locations or without provenance. |
permissions-minimum-scope-grep | standalone | minimum-scope workflow permissions | Verify every GitHub Actions workflow declares a minimum-scope permissions: block. |
plain-language-grep | standalone | rules/plain-language.md — user-facing prose | Flag mechanistic / harness-internal vocabulary in user-facing prose. |
plan-next-step-consistency-grep | standalone | rules/recommend-next-step.md | Advisory: flag plan-suite infra files whose Recommended-Next-Step footer drifts from the suite's recorded next pipeline stage. |
plan-suite-structure-grep | standalone | context-management-scratch 2 (suite-locality + closed vocab) + canonical-layout-reporting-tiers 2.1 (numeric-prefix discipline) | Validate plan-suite structure: suite-locality, closed vocab, numeric prefix. |
plans-discipline-language-grep | standalone | CLAUDE.md Plans Discipline (multi-surface language) | Verify the canonical Plans Discipline language reaches every required surface. |
production-ready-pr-grep | per-write | M15 production-ready §Same-change-set | Flag commits whose change-set lacks the production-ready four-class shape. |
recommend-next-step-grep | standalone | rules/recommend-next-step.md | Verify every command file carries a ## Recommended Next Step block. |
redundancy-grep | standalone | rules/operational-mandates.md §CM-7 coherent-product non-redundancy | Flag substantively-duplicated paragraphs across the governed corpus. |
reference-token-grep | standalone | rules/own-voice-reimplementation.md | Flag leaked reference-platform branding tokens on authored surfaces. |
registry-capability-consistency-grep | standalone | rules/agent-capability-discipline.md — registry capability cells backed by evidence | Flag registry capability cells not backed by install / materializer / projection evidence. |
secret-leak-grep | per-write | M13.8 security + M15 production-ready | Block emission of artifacts containing hardcoded credentials. |
semver-stability-grep | change-set | M15 semver-stability | Semver stability matcher (M15 mechanical fraction). |
smoke-install-grep | standalone | production-ready section 8.1 paired install scripts | Smoke-test the paired install scripts at the repository root. |
static-version-grep | standalone | rules/dynamism.md §static-version-resolution | Verify version-bearing sites resolve dynamically, not as static literals. |
token-efficiency-grep | per-write | clean-room-generation §5 + token-efficiency-rewrite | Flag filler phrases, throat-clearing openers, and content-free qualifiers. |
unpinned-action-grep | per-write | M15 production-ready §Supply-chain | Flag GitHub Actions workflows that pin actions to mutable refs. |
user-confirm-grep | per-write | M5 authority-inquiry §10 | Block emission of artifacts containing unresolved authority placeholders. |
workflow-concurrency-grep | standalone | workflow concurrency + per-job timeouts | Enforce concurrency + per-job timeout discipline on GitHub workflows. |
تشغيل البوابة
على إطار عمل مُثبَّت، تعمل البوابة تلقائيًا: يربطها settings.json الخاص بـ
Claude Code بوصفها خطّاف PreToolUse يستدعي النسخة المُجسَّدة في
~/.claude/.apothem/support/conformity/gate.py قبل كل عملية
Write/Edit. ولا تفحص البوابة حينئذٍ إلا عمليات الكتابة الواقعة ضمن نطاق خطّافها،
وتمرّ الكتابة الواقعة خارج النطاق بصمت؛ ويسرد تشغيل بوابة المطابقة
هذا النطاق. ومن نسخة مسحوبة من المصدر، تُشغِّل صيغة الوحدة الشيفرةَ نفسها؛
فابدأ كل أمر python أدناه بالبادئة PYTHONPATH=src. والبوابة
استشارية افتراضيًا: تُبلِغ عن النتائج وتخرج بالرمز 0. أضِف --strict
لتخرج بالرمز 2 عند نتيجة حاجبة. ويخرج الأمر بالرمز 3 عند اسم
أداة تحقّق غير معروف.
# Every standalone validator across the repository:
python -m apothem.conformity.gate --all .
# The same sweep, failing on a blocking finding (the CI form):
python -m apothem.conformity.gate --all --strict .
# Every per-write validator against every tracked file:
python -m apothem.conformity.gate --all-perwrite .
# One validator by name (names come from --list):
python -m apothem.conformity.gate --check naming-grep .
# List every registered validator as JSON:
python -m apothem.conformity.gate --list
# Single-file dispatch (mimics the PreToolUse hook):
echo '{"tool_input": {"file_path": "path/to/file", "content": "..."}}' \
| python -m apothem.conformity.gate --hookيطبع python -m apothem.conformity.gate --help ملخّص الاستخدام.
راجِع تشغيل بوابة المطابقة للإجراء الكامل.
المراجع
- سجلّ بوابة ما قبل الإصدار — تعريفات الأشرطة المرجعية
- سجلّ المطابقة الخارجية — الدلالات التفصيلية لـ M1-M15
- التفويضات الشاملة — مصدر الحقيقة للتفويضات
- انضباط الأداء — ميزانيات زمن التشغيل لكل فئة