# INITKOA CONTEXT PACK repository: Rejean-McCormick/SemantiK-Architect-GF-Zone-Auditor source_commit: 4afe1d65acdc252fe738450f3876c57cb29f0c0e source_mode: git working_tree_markdown: clean working_tree_selected: clean selection_mode: markdown wiki_source_commit: none wiki_working_tree_markdown: none policy_version: 2026-09-10.13 repo_files: 12 wiki_files: 0 source_files: 12 included_files: 12 excluded_files: 0 duplicate_files: 0 content_bytes: 244568 authority_counts: {"reference":12} content_role_counts: {"knowledge":12} generated_at: 2026-09-10T13:04:11-04:00 files: 12 content_sha256: 65c4dbab531a5abc828c824ed4f03e22b842153ac8e6e16c7c42b6e00e03a9dc ================================================================================================ FILE INDEX ================================================================================================ 01. [reference] [knowledge] docs/00_main_design.md | bytes=32501 | sha256=c711e9bfd7fbecd0742880a3a0134a735b13fc912c59145358d7a5d7e29cd430 02. [reference] [knowledge] docs/01_scope_contract.md | bytes=15245 | sha256=48f3a9b48c8156e4f78e4f7d72ff0db0ba7ba2add70d2bd213245f25856f3c64 03. [reference] [knowledge] docs/02_analyzer_contract.md | bytes=16912 | sha256=e8446ced3000bbffa0260a5fded6266b2390a9ef5d4825ae6c83652c3c106cb5 04. [reference] [knowledge] docs/03_report_contract.md | bytes=26005 | sha256=c6a81010bdaf964946a2f14f630af64233c4b601aa470c7697e891ca44008a2e 05. [reference] [knowledge] docs/04_profiles.md | bytes=19771 | sha256=3717bf4df57b7987566ff7fd307672eb7b3ba34538c76bffe18f20aa1f123335 06. [reference] [knowledge] docs/05_rulepacks.md | bytes=21190 | sha256=24456f5f31a45e8f9ca8d5304317f5030c9eb32d5f9e9701edc6cd84d957fd81 07. [reference] [knowledge] docs/06_probe_spec.md | bytes=22349 | sha256=c78fa2cb2e31d135827265d9969e3c769bf326fd08519cdc732d907be3004461 08. [reference] [knowledge] docs/07_semantik_inventory.md | bytes=17628 | sha256=f664d774efe502e482c26eaa132b51df358e8edc63ce146014df4db98f78af37 09. [reference] [knowledge] docs/08_acceptance_contract.md | bytes=19318 | sha256=89ef63e7305725d2b5e7fe3db1df649401fb4d3fa90182a5ea1014b58950fbaa 10. [reference] [knowledge] docs/09_change_control.md | bytes=19498 | sha256=94dd862dae55308fbc9e3e585f223eca38d3814d04e18ea8468f4b4e7dd92970 11. [reference] [knowledge] docs/10_gui_contract.md | bytes=17935 | sha256=c84b37d357fb31fa061df7775b31c1a0873e1cc2e710b50463f90f88e2044fd1 12. [reference] [knowledge] README.md | bytes=16216 | sha256=0e9aeb7a8abe4a9f60ae7ac2f53c19eb222d638ef0278cb285a32a046f1ed303 ================================================================================================ FILE: docs/00_main_design.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: c711e9bfd7fbecd0742880a3a0134a735b13fc912c59145358d7a5d7e29cd430 CONTENT_BYTES: 32501 ================================================================================================ # SemantiK Grammar Surface Auditor ## *Design documentation for adapting gf-audit into a robust auditor for SemantiK’s GF grammar surface, bioframework, and Wiki-language files* **Working decision document** Purpose: define a straight, robust implementation path with no patchwork broadening of the current GF-only tool, and no drift into whole-system or runtime auditing. | Decision in one sentence: keep the existing strengths of gf-audit for real `.gf` files, but refactor it into a grammar-surface auditor specialized for SemantiK’s Wiki/bioframework layer, with first-class support for GF compilation, grammar-surface rule packs, probe assets, and language-behavior probes. | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | # **Document map** * This document defines the scope boundary, architecture, output contract, analyzer model, profile model, and migration plan for the modified tool. * The target is not whole-system validation and not general SemantiK runtime troubleshooting. The target is the **SemantiK grammar surface**: the real GF grammars, their shared and concrete Wiki layers, the probe/fixture assets directly used to verify bio/event realization, and the narrow helper tools that directly support that verification. * The design intentionally avoids cheap solutions such as widening the `.gf` file filter to unrelated code, conflating runtime integration with grammar correctness, or treating compile success as proof of correct language behavior. ## **Authority and precedence** This document is the top-level design authority for the SemantiK Grammar Surface Auditor. Normative precedence order: 1. `docs/00_main_design.md` 2. `docs/01_scope_contract.md` 3. `docs/02_analyzer_contract.md` 4. `docs/03_report_contract.md` 5. `docs/04_profiles.md` 6. `docs/05_rulepacks.md` 7. `docs/06_probe_spec.md` 8. `docs/07_semantik_inventory.md` 9. `docs/08_acceptance_contract.md` 10. `docs/09_change_control.md` 11. implementation details Any normative document that repeats precedence must use this exact order. # **1. Executive summary** The current gf-audit tool already has a strong foundation. It cleanly separates selection, heuristic scanning, compilation, failure classification, diffing, and reporting. It supports whole-project and single-file runs, optional compile skipping, per-file logs, and AI-ready handoff reports. That baseline should be preserved. However, the earlier broadening idea toward a general “GF-zone” is not the right target for this project. SemantiK already has broader troubleshooting and runtime tools for planner behavior, response metadata, runtime path selection, and generation debugging. This new tool should not duplicate or overlap that surface. The right target is narrower and deeper: the **grammar surface** itself, especially the Wiki/bioframework layer where the real multilingual realization decisions live. That includes the shared GF layers, concrete language grammars, grammar-surface helper files, and explicit probe fixtures used to verify that a given concrete really behaves like its language. The modification proposed here is therefore not a runtime-audit expansion. It is a structural adaptation from a generic GF-source auditor into a **SemantiK grammar-surface auditor**. Real GF modules remain first-class compilable artifacts. In addition, the tool gains grammar-surface rule packs and a probe engine that can detect issues such as inherited English literals, missing concrete overrides, constructor parity drift, and language leakage in realized outputs. This preserves rigor. Real GF modules are still treated as grammars, not as text blobs. Probe fixtures are treated as language-behavior verification assets, not as substitute runtime tests. Reporting remains unified, but the scope stays strict: **Wiki files, bio/event realization, shared vs concrete surface behavior, probe assets, and direct grammar-surface helper tools only**. # **2. Why this adaptation exists** The immediate language bug discussed in the handoff exposed the exact class of problem this tool should own. A French failure can originate inside the grammar surface even when routing is correct, because a shared layer still contains hardcoded English realization strings. That is a grammar-surface defect, not a planner defect and not an API defect. Your request is not to test the entire system. That boundary is correct and should be kept. A file auditor should not turn into a substitute for planner tests, API smoke tests, fallback-path investigations, or response-contract validation. SemantiK already has other tools for those concerns. This tool should instead own the **static, compile-time, and probe-time correctness of the grammar surface** and produce precise evidence for where a language problem lives inside that surface. In practical terms, the modified tool must answer four questions reliably. First: which grammar-surface artifacts were selected and what happened when they were scanned or compiled? Second: which shared and concrete modules participate in the same realization path? Third: do those artifacts contain inherited literals, missing overrides, suspicious concatenative realization patterns, or cross-language asymmetries? Fourth: when probed with representative bio/event constructions, do the resulting outputs behave like the intended language? That is the correct boundary and the correct value. # **3. Baseline: what gf-audit already does well** The existing tool has several design qualities that should remain authoritative in the adapted version. * Clear run modes: audit all selected files or exactly one target file. * A clean split between scan results and compile results. * Per-file compilation with timeout, GF version probing, and structured parsing of compile output. * Failure classification that distinguishes direct failures from downstream cascades and ambiguous failures. * Stable reporting artifacts: `summary.json`, `summary.md`, `AI_READY.md`, `top_errors.txt`, per-file logs, and run-to-run diffs. * Configurable selection through scan directory, glob, include regex, exclude regex, max-files, and no-compile mode. These are not incidental implementation details. They are the backbone of why the current tool is useful. The adaptation should reuse them instead of bypassing them. The generic parts of the current architecture are especially valuable: orchestration, run metadata, fingerprints, output generation, diffing, and result bucketing. The parts that are too generic or too broad from the earlier draft are anything aimed at runtime adapters, response contracts, or non-grammar system behavior. Those are intentionally removed from scope for this project. # **4. Scope boundary for SemantiK** The modified tool should audit the **SemantiK grammar surface**. That surface is defined functionally, but it remains narrow. | Tier | Source kind | Examples | Included by default | | :--- | :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------- | | A | Native GF source | `gf/WikiI.gf`, `gf/WikiEng.gf`, `gf/WikiFre.gf`, `gf/SemantikArchitect.gf`, related `gf/Wiki*.gf` files | Yes | | B | Grammar probe and expectation assets | bio/event probe fixtures, forbidden-literal lists, expected-concrete manifests, required-constructor manifests | Yes | | C | Direct grammar-facing helper tools | grammar compile helpers, grammar visualization helpers, grammar QA scripts used specifically to exercise Wiki/bio outputs | Yes, but only when directly tied to grammar-surface verification | | D | Runtime adapters and broader application code | `gf_wrapper.py`, `gf_engine.py`, planner internals, API contracts, renderer metadata, fallback routing | No | Tier D is out of scope for this tool. This is a deliberate decision. This boundary matters. A tool becomes weak when it tries to own everything and ends up proving nothing. The SemantiK grammar surface is the area where multilingual realization is authored and where the class of regressions you care about can be caught before they appear as user-facing generation defects. The modified tool should therefore be honest about non-goals. It is not a substitute for end-to-end generation tests. It is not a planner validator. It is not an API contract verifier. It is a precise auditor for the grammar surface, with special emphasis on the Wiki/bioframework realization path. # **5. Design principles** 1. No fake generalization. Do not broaden the tool into a general SemantiK code auditor. 2. No one-off patches. Do not keep the old GF-only internals and sprinkle Wiki-specific exceptions everywhere. 3. Keep the compile/scan/probe split. Static findings, compile outcomes, aggregate probe outcomes, and per-execution probe evidence must remain separate evidence channels. 4. Make probes first-class. Compile success is necessary but not sufficient for multilingual surface correctness. 5. Use grammar-surface source kinds, not broad repo categories. 6. Make evidence first-class. Every finding must have a stable rule id, source kind, severity, message, and target reference. 7. Preserve deterministic outputs. The existing run directory and summary artifacts are strengths and should remain stable. 8. Support narrow and broad grammar runs. Single-file diagnosis must remain as strong as multi-file auditing. 9. Do not smuggle runtime validation into a grammar auditor. 10. Prefer explicit probe fixtures and rule packs over free-form heuristics when the surface is known. These principles are intended to prevent two bad outcomes: a tool that is still secretly GF-only but patched for one repo, or a tool that becomes so broad that its results stop being trustworthy. # **6. Target architecture** The core change is to move from a **generic GF-source pipeline** to a **SemantiK grammar-surface pipeline** with first-class grammar analyzers and probes. ## **6.1 Architectural shape** * Selection layer: resolves profiles into grammar-surface artifact candidates. * Classification layer: assigns each artifact a grammar-surface source kind. * Analyzer registry: dispatches one or more analyzers per source kind. * Evidence model: stores findings in a common schema regardless of analyzer. * Result synthesis layer: derives artifact status, diagnostic class, severity totals, dependency links, and run summaries. * Report layer: emits machine-readable and human-readable outputs. This is not a rewrite for its own sake. It is a refactor that isolates the reusable gf-audit foundation from the new grammar-surface logic, allowing stronger verification without expanding into unrelated SemantiK surfaces. ## **6.2 Recommended internal package split** * `selection/`: profile resolution, file discovery, inclusion/exclusion rules, path policies. * `kinds/`: grammar-surface source kind classifiers and path-to-kind mappings. * `analyzers/gf_source/`: GF compile analyzer, GF static scan analyzer, GF dependency analyzer. * `analyzers/probes/`: linearization probe analyzer, forbidden-literal probe analyzer, cross-language probe analyzer. * `analyzers/assets/`: probe fixture analyzer, expected-concretes analyzer, required-constructors analyzer, forbidden-literals analyzer. * `evidence/`: common finding models, severity, rule metadata, locations, related artifact links. * `reports/`: mostly preserved, but fed by richer artifact results. * `profiles/`: named run profiles for pure GF and SemantiK grammar-surface auditing. The earlier idea of separate runtime-adapter analyzers and system-contract analyzers is intentionally dropped. This tool stays centered on the grammar surface. # **7. Source kinds and analyzer pipelines** Each source kind gets analyzers that match its nature. | Source kind | Primary analyzers | Status basis | Typical failure examples | | :--------------------- | :------------------------------------------------------------------------------------------------------- | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | | `gf_source` | `gf_static_scan`, `gf_compile`, `gf_dependency_scan` | compile plus static evidence | syntax/type errors, inherited literals, missing concrete, shared-layer leakage | | `probe_asset` | `probe_fixture_scan`, `expected_concretes_scan`, `required_constructors_scan`, `forbidden_literals_scan` | finding severity synthesis | missing probe coverage, missing expected concrete declarations, missing constructor expectations, incomplete forbidden-literal coverage | | `grammar_surface_tool` | `tool_contract_scan`, `language_list_consistency_scan` | finding severity synthesis | compile helper drift, probe helper drift, omitted language coverage | | `linearization_probe` | `gf_linearization_probe`, `forbidden_literal_probe`, `cross_language_probe` | probe evidence | French output leaking English literals, missing bio/event overrides, parity failures | ## **7.1 `gf_source` pipeline** This pipeline preserves the existing strengths of gf-audit. It selects real `.gf` files, runs GF-aware static scanning, compiles them with `gf.exe`, parses compile output, and classifies failures. For SemantiK, this pipeline gains grammar-surface specific rule packs. Those rule packs should explicitly understand the Wiki/bioframework patterns that matter here, including: * shared-layer literal leakage * expected realization functions such as `mkBioProf`, `mkBioNat`, `mkBioFull`, and `mkEvent` * completeness of language concretes relative to the shared layer * suspicious direct string concatenation in realization hotspots * cross-language asymmetry in the same constructor family ## **7.2 `probe_asset` pipeline** Probe and expectation files are not GF modules, but they are part of the grammar surface because they define what the tool is supposed to verify. This pipeline should validate: * expected language lists * expected concrete names * required constructor coverage * forbidden literal lists by language * fixture completeness for the bio/event realization path The goal is not generic asset linting. The goal is to ensure the verification surface stays aligned with the actual grammar surface. ## **7.3 `grammar_surface_tool` pipeline** Some helper tools are directly about grammar compilation, visualization, or grammar-specific QA. Those may be included, but only when they are narrowly tied to the grammar surface. This pipeline should inspect tool entry points, expected arguments, hardcoded language lists, and internal assumptions about the Wiki/bioframework surface. It should not expand into general SemantiK tooling. ## **7.4 `linearization_probe` pipeline** This is the most important addition. Compile success alone is not enough for language-surface work. The tool must be able to compile a nominated root grammar or PGF, verify that required concretes exist, and linearize selected trees or canned expressions in specific languages. That probe stage is the correct place to catch issues such as a French concrete that compiles but still surfaces English literals. # **8. Output contract** The current run outputs are worth keeping. What changes is the shape of each artifact result and the role of probes. ## **8.1 Run-level outputs** * `summary.json` remains the canonical machine-readable run result. * `summary.md` remains the human-readable report. * `AI_READY.md` remains the handoff packet. * `top_errors.txt`, per-artifact logs, and diff entries remain part of the run directory. ## **8.2 Artifact-level result model** Each artifact result should include at least the following fields: * `artifact_ref` * `artifact_path` when applicable * `source_kind` * `selected_by_profile` * `fingerprint` * `analyzers_run` * `artifact_status` * `diagnostic_class` * `blocked_by` * `compile_summary` when relevant * `probe_summary` when relevant and only for aggregate probe status * `probe_execution_summary` when relevant and only for per-execution probe detail * `findings[]` * `related_artifacts[]` * `timing_ms` For `linearization_probe`, `artifact_path` may be null if `artifact_ref` and probe identity are sufficient. `probe_summary` is the aggregate artifact-level probe object. It carries roll-up probe state and counts such as applicability, attempt state, execution outcome, probe catalog identity, case counts, pass/fail counts, blocked reason, languages checked, forbidden-literal hits, missing concretes, and parity failures. `probe_execution_summary` is the per-execution probe object. It carries execution-specific probe detail such as applicability, attempt state, execution outcome, probe id, grammar target, exactly one of `target_concrete` or `target_language`, expectation references, findings count, forbidden-literal match count, related constructor families, and output excerpt. These two objects are intentionally separate. Aggregate probe reporting never carries per-execution fields, and per-execution probe evidence never replaces aggregate probe reporting. The key improvement is `findings[]`. A compile failure is only one kind of evidence. A shared-layer literal leak is another. A missing French constructor override is another. A forbidden-literal probe hit is another. All of them should live under one normalized evidence model. ## **8.3 Findings schema** Each finding should include at least: * `finding_id` * `rule_id`: stable identifier such as `GF001` or `SKA_WIKI_012` * `severity`: `info`, `warning`, `error` * `message` * `source_kind` * `target_ref` * `artifact_path` when applicable * `line` or `span` when available * `related_paths` * `evidence_excerpt` * `suggested_fix_kind`: `code`, `fixture`, `config`, `test`, `investigate` * `analyzer_id` This gives the tool enough structure to drive diffs, summaries, and future UI improvements without flattening everything into free text. # **9. Static rule packs** The modified tool should ship named rule packs rather than one monolithic scanner. ## **9.1 GF source rule pack** * Existing GF static rules for suspicious lambda and table patterns remain. * Add literal-leak rules for shared interlingua layers that contain explicit pivot-language surface strings. * Add concrete override completeness rules for known language-surface functions such as `mkBioProf`, `mkBioNat`, `mkBioFull`, and `mkEvent` when the profile is SemantiK Wiki surface. * Add constructor-family parity rules across `WikiEng`, `WikiFre`, and other `Wiki*` concretes. * Add dependency-shape rules for expected root grammars and concrete naming conventions. * Add realization-hotspot rules for concatenative surface assembly where a stronger language-specific realization is expected. ## **9.2 Probe asset rule pack** * Probe language lists should match the available `Wiki*` concretes under `gf/`. * Required bio/event probe cases should exist for supported languages. * Forbidden literal lists should be defined for non-English probes where leakage risk is known. * Expected concrete manifests should not silently omit supported concretes. * Required constructor manifests should not silently omit supported constructor families. ## **9.3 Grammar-surface tool rule pack** * `compile_pgf`, `visualize_ast`, `eval_bios`, and similar grammar-facing tools should agree on root grammars, language naming, and invocation patterns. * Grammar-surface QA tools that validate multilingual output should include language-identity assertions, not only non-empty-output assertions. * Helper tools should not silently hardcode outdated concrete inventories. Rule packs should be profile-aware. A generic GF project should not suddenly inherit SemantiK Wiki-specific expectations. # **10. Compilation and linearization verification** This section is central. A robust grammar-surface auditor must be able to say more than “the file compiled.” For language work, compile success is necessary but not sufficient. The adapted tool should support a probe phase for `gf_source` artifacts when the active profile enables or requires probes. The phase compiles a designated root grammar or PGF, checks that required concretes are present, and linearizes selected trees or canned expressions in nominated languages. In the SemantiK Wiki-surface profile, probe cases should include the biography and event realization paths that were involved in the French leakage issue. The probe should compare outputs against language-specific expectations and forbidden-literal sets. For example, a French probe may explicitly forbid `is a`, `is`, and `participated in` when the output is expected to be French. The probe phase produces two layers of reportable evidence: * aggregate probe status in `probe_summary` * per-execution probe detail in `probe_execution_summary` Additional rules for this phase: * Probe input can be a small catalog of language-agnostic test trees or canned AST expressions. * Probe expectations should be profile-specific and stored as explicit fixtures. * Probe results must not be merged into `compile_summary`. * Aggregate probe status belongs in `probe_summary`. * Per-execution evidence belongs in `probe_execution_summary`. * A probe failure is a real language-surface failure even if the underlying `.gf` files compiled. This is the mechanism that turns the tool from “GF build checker” into “grammar-surface auditor.” # **11. CLI, profiles, and user workflow** The CLI should preserve the existing mental model while adding profiles that stay within grammar-surface scope. * `pure-gf`: current behavior for a normal GF project. * `semantik-grammar-surface`: native GF files plus grammar-surface fixtures and direct grammar-facing tools. * `semantik-wiki-surface`: narrower profile for Wiki grammars, bio/event probes, and related expectation assets. * `file` mode: still valid, but target interpretation depends on source kind and profile. The profile should determine candidate roots, source-kind mappings, analyzer sets, probe fixtures, and rule packs. This is much stronger than asking users to manually rebuild the same selection logic with regex flags every time. ## **11.1 Suggested commands** * `grammar-surface-audit --profile pure-gf --project-root ...` * `grammar-surface-audit --profile semantik-grammar-surface --project-root ...` * `grammar-surface-audit --profile semantik-wiki-surface --mode file --target-file gf/WikiFre.gf ...` * `grammar-surface-audit --profile semantik-wiki-surface --run-probes ...` The exact binary name can be decided later. The important decision is profile-driven behavior within a strict scope. # **12. Testing strategy** The modified tool should be test-driven at three layers. | Layer | What is tested | Why it matters | | :------------------- | :-------------------------------------------------------------------------------- | :------------------------------------------------------ | | Unit | selector rules, source-kind classification, individual analyzers, evidence schema | prevents accidental scope drift and analyzer regression | | Fixture integration | small synthetic grammar repos, probe assets, and helper-tool fixtures | proves profiles and analyzers work together | | Real-repo regression | SemantiK snapshots and known French-bio failure fixtures | guards against the actual failure modes we care about | * Add golden `summary.json` fixtures for representative runs. * Add probe fixtures that verify French outputs do not leak English literals. * Add shared-layer fixtures that deliberately place English literals in the wrong layer and expect an error finding. * Add concrete-coverage fixtures that deliberately omit `mkBioProf` or `mkEvent` in one language and expect a finding or probe failure. * Keep current scanner and report tests; extend them rather than replacing them. # **13. Migration plan** The migration should be phased and reversible at each stage. | Phase | Objective | Main changes | Exit condition | | :---- | :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- | | 1 | Refactor core | Introduce grammar-surface `source_kind`, normalized analyzer outputs, and `findings[]` without changing current pure-GF behavior | `pure-gf` profile remains backward compatible | | 2 | Add profiles | Implement SemantiK grammar-surface and Wiki-surface profile maps | tool can select grammar-surface artifacts deterministically | | 3 | Add grammar-surface rule packs | Ship SemantiK-specific GF-source and probe-asset rules | grammar-surface findings are structured and useful | | 4 | Add probe engine | Compile root grammar or PGF and linearize nominated fixtures | language-surface leakage can be caught automatically | | 5 | Stabilize outputs | Finalize summary schema, including aggregate `probe_summary` and per-execution `probe_execution_summary`, plus aggregation behavior, diff behavior, and AI handoff content | reports remain stable and useful | The most important sequencing rule is this: do not add SemantiK Wiki-specific exceptions directly into the old GF scanner and selector. First establish the grammar-surface architecture, then add the SemantiK-specific rule packs and probes. # **14. Risks and anti-patterns** * Anti-pattern: broadening the file selector to include runtime Python files while keeping one GF scanner and one GF compiler pipeline. * Anti-pattern: collapsing static findings, compile failures, aggregate probe results, and per-execution probe evidence into the same free-text bucket. * Anti-pattern: claiming language correctness from compile success alone. * Anti-pattern: widening the scope to planner/runtime/API surfaces because they are nearby in the repo. * Anti-pattern: using only non-empty-output assertions in multilingual probe logic. * Anti-pattern: hiding source-kind differences behind one generic status flag without separate `artifact_status`, `diagnostic_class`, `compile_summary`, `probe_summary`, and `probe_execution_summary`. The most serious technical risk is false confidence. A weakly generalized tool may run across more files and still miss the real cause of a grammar-surface language bug. The mitigation is explicit grammar-surface source kinds, profile-specific rule packs, and probe-based verification. The most serious maintenance risk is architecture leakage. If SemantiK Wiki-specific assumptions are placed directly in the generic core, the pure GF use case will become harder to maintain. The mitigation is strict separation between the platform core and profile-owned rule packs. # **15. Acceptance criteria** 1. The `pure-gf` profile preserves current behavior for real `.gf` projects with no regression in compile, scan, classification, diffing, or reporting. 2. The SemantiK grammar-surface profile can select native GF grammars, grammar probe assets, and direct grammar-facing tools without widening core selector rules into ad hoc exceptions. 3. The tool never attempts GF compilation on non-GF artifacts. 4. The output contract clearly distinguishes compile results, aggregate probe results, per-execution probe results, and static findings. 5. A known French Wiki-surface regression can be represented as a fixture and is detected automatically. 6. A shared grammar layer containing English surface literals where a neutral layer is expected produces a structured finding. 7. A concrete grammar missing required bio/event realization coverage produces a structured finding or probe failure. 8. Reports remain compact at the top and detailed underneath, preserving the current debugging workflow. 9. Single-file diagnosis remains strong for both GF files and probe/expectation assets. These criteria are intentionally concrete. The modification is only successful if it gives you a better engineering instrument for the grammar surface, not just a broader scanner. # **16. Initial file inventory for SemantiK** The first SemantiK profile should start from a reviewed inventory rather than free-form directory crawling. * Native GF surface: `gf/SemantikArchitect.gf`, `gf/WikiI.gf`, `gf/WikiEng.gf`, `gf/WikiFre.gf`, and related `gf/Wiki*.gf` files. * Grammar-facing tools and QA: `compile_pgf`, `visualize_ast`, `eval_bios`, and any tightly related grammar-surface helpers used specifically to compile, inspect, or verify Wiki/bio outputs. * Grammar-surface tests and acceptance artifacts: `docs/testing/EN_FR_bio_acceptance.md`, explicit probe fixture catalogs, forbidden-literal lists, expected-concrete manifests, and required-constructor manifests. * Optional grammar-facing test assets: tightly scoped tests or fixtures that directly encode grammar-surface expectations, not general runtime tests. This inventory should be encoded in the SemantiK profiles as explicit include roots and source-kind mappings. That makes the scope reviewable and stable. Further expansion should happen only if it still stays inside the grammar surface. A tight first product will be stronger than a sprawling one. # **Final recommendation** **Proceed with a real architectural adaptation: keep gf-audit as the GF-specialist core, refactor it into a SemantiK grammar-surface auditor, and implement grammar-surface rule packs plus language-behavior probes for the Wiki/bioframework layer. Do not widen the current `.gf`-only tool into runtime or whole-system auditing.** # **Appendix A. Implementation notes for the first engineering pass** 1. Freeze the current pure-GF behavior with regression tests before refactoring. 2. Introduce `source_kind`, normalized analyzer outputs, `findings[]`, aggregate `probe_summary`, and per-execution `probe_execution_summary` into the result model first. 3. Move current scanner and compiler behind analyzer interfaces without changing their logic. 4. Add profile configuration for `pure-gf`, `semantik-grammar-surface`, and `semantik-wiki-surface`. 5. Implement native GF support first, then probe assets, then grammar-surface tool checks, then the probe engine. 6. Only after probes are stable should the tool be treated as a language-surface gate. ================================================================================================ FILE: docs/01_scope_contract.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 48f3a9b48c8156e4f78e4f7d72ff0db0ba7ba2add70d2bd213245f25856f3c64 CONTENT_BYTES: 15245 ================================================================================================ # Scope Contract ## SemantiK Grammar Surface Auditor **Normative document** This file defines the scope boundary for the SemantiK Grammar Surface Auditor. Its purpose is to make the product boundary explicit, stable, and enforceable. This document is **normative**. It is not explanatory guidance. It defines what the app is allowed to audit, what it is not allowed to audit, and what kinds of future expansion are permitted. If implementation behavior, tests, or future documentation conflict with this file, this file takes precedence unless `docs/00_main_design.md` is intentionally revised and this contract is updated accordingly. --- ## 1. Purpose of this contract The SemantiK Grammar Surface Auditor exists to audit the **grammar surface** of SemantiK. The grammar surface is the part of the code and asset space where multilingual realization is authored, represented, verified, and constrained. In this project, that means: * real GF grammar modules * shared and concrete Wiki-language modules * bio/event realization surface * grammar-focused probe fixtures and expectation assets * direct grammar-facing helper tools used to compile, inspect, or verify that surface This contract exists to prevent three failure modes: 1. accidental expansion into broad SemantiK runtime auditing 2. patchwork inclusion of unrelated files because they are “near” the grammar surface 3. future weakening of the product into a generic repo scanner --- ## 2. Product boundary statement The SemantiK Grammar Surface Auditor is a **grammar-surface auditor**. It is **not**: * a whole-system SemantiK auditor * a runtime path validator * a planner validator * an API contract validator * a renderer metadata inspector * a generic Python static analysis tool * a substitute for end-to-end generation tests The tool is allowed to reason about source files and assets **only insofar as they directly define, verify, or constrain the SemantiK grammar surface**. --- ## 3. Scope principle A file, asset, or helper tool is in scope only if at least one of the following is true: 1. it is a real GF module used in the SemantiK grammar surface 2. it is a probe or expectation asset used to verify grammar-surface behavior 3. it is a direct grammar-facing helper tool whose primary function is to compile, inspect, or verify that grammar surface If none of these are true, the artifact is out of scope. Being related to language work in a broad sense is **not** sufficient. Being located near `gf/` or mentioned in language debugging conversations is **not** sufficient. Being useful to another SemantiK troubleshooting tool is **not** sufficient. --- ## 4. Definitions ### 4.1 Grammar surface The **grammar surface** is the authored and verifiable layer where language realization is defined and checked. For this project, it includes: * GF abstract and concrete grammars * shared Wiki/bioframework layers * language-specific realization modules * explicit probe cases and expected outputs * forbidden-literal lists * required constructor manifests * grammar-facing helper scripts that directly operate on the above ### 4.2 Native GF source A **native GF source** is a real `.gf` file that participates in the grammar surface, including: * abstract grammars * concrete grammars * shared intermediate modules * Wiki-language modules * SemantiK root grammar modules ### 4.3 Probe asset A **probe asset** is a non-`.gf` artifact whose primary purpose is to define what the auditor must verify about grammar-surface behavior. Examples include: * probe catalogs * expected concrete manifests * required constructor manifests * forbidden literal lists * language-specific expectation files ### 4.4 Grammar-surface tool A **grammar-surface tool** is a helper script or command artifact whose primary purpose is to compile, inspect, visualize, or verify the grammar surface. A file is not a grammar-surface tool merely because it mentions GF. ### 4.5 Out-of-scope runtime artifact An **out-of-scope runtime artifact** is any file whose primary role is runtime orchestration, route selection, rendering, API service behavior, planner logic, fallback handling, or application-level debugging. Such files remain outside this product even if they touch language generation indirectly. --- ## 5. Source kinds allowed by this product The product supports exactly these source kinds: * `gf_source` * `probe_asset` * `grammar_surface_tool` * `linearization_probe` ### 5.1 `gf_source` Represents native GF modules that can be scanned and, when appropriate, compiled. Typical examples: * `gf/WikiI.gf` * `gf/WikiEng.gf` * `gf/WikiFre.gf` * `gf/SemantikArchitect.gf` * related `gf/Wiki*.gf` modules ### 5.2 `probe_asset` Represents probe fixtures and expectation assets that define the grammar-surface verification contract. Typical examples: * `fixtures/probes/probe_catalog.yaml` * `fixtures/probes/expected_concretes.yaml` * `fixtures/probes/required_constructors.yaml` * `fixtures/probes/forbidden_literals.fr.yaml` ### 5.3 `grammar_surface_tool` Represents helper tooling used specifically to operate on the grammar surface. Typical examples include tightly scoped compile, visualization, or grammar QA helpers such as: * `compile_pgf` * `visualize_ast` * `eval_bios` A tool enters this source kind only if its primary responsibility is grammar-surface work. ### 5.4 `linearization_probe` Represents the execution of a defined probe case against a compiled grammar surface. This is a run-time source kind inside the auditor, not a repo file extension category. It exists to represent observed behavior such as: * forbidden literal leakage * missing concrete behavior * cross-language parity failures * constructor realization failure --- ## 6. Included artifact families The following artifact families are included by default in the SemantiK grammar-surface profiles. ### 6.1 Native GF grammar files Included: * `gf/SemantikArchitect.gf` * `gf/WikiI.gf` * `gf/WikiEng.gf` * `gf/WikiFre.gf` * related `gf/Wiki*.gf` files * closely related GF modules required to compile or reason about the same grammar surface ### 6.2 Grammar-surface probe and expectation assets Included: * probe catalogs * expected concrete manifests * required constructor manifests * forbidden literal lists * grammar-surface expectation fixtures * grammar-surface acceptance fixtures specifically tied to Wiki/bio realization ### 6.3 Direct grammar-facing helper tools Included only when directly used for grammar-surface work: * compile helpers for the grammar surface * visualization helpers for grammar trees or grammar outputs * grammar QA helpers tied to Wiki/bio outputs * narrowly scoped scripts for evaluating multilingual grammar outputs ### 6.4 Grammar-surface documentation artifacts Included only when they encode grammar-surface acceptance or expectation data rather than general prose. Examples may include tightly scoped acceptance files such as: * `docs/testing/EN_FR_bio_acceptance.md` Such documentation is included only when it materially defines expected grammar behavior. --- ## 7. Explicitly excluded artifact families The following artifact families are out of scope, even if they mention GF, languages, rendering, or generation. ### 7.1 Runtime adapter code Excluded: * `gf_wrapper.py` * `gf_engine.py` * `gf_construction_adapter.py` * other adapters whose primary role is application/runtime behavior These may be important elsewhere in SemantiK, but they are not part of this product. ### 7.2 Planner and orchestration code Excluded: * planner internals * runtime selection logic * fallback orchestration * construction routing logic * generation use-case orchestration ### 7.3 API and response-contract code Excluded: * API response mappers * response-contract enforcement * metadata reporting layers * renderer/debug payload shaping ### 7.4 General application code Excluded: * frontend code * service wiring * non-grammar business logic * unrelated utility code * broad QA tooling not dedicated to grammar-surface verification ### 7.5 Whole-system tests Excluded: * end-to-end generation tests * planner smoke tests * API contract tests * integration tests that use grammar artifacts only as one part of a broader runtime scenario The auditor may reference the existence of such tests in documentation, but it must not take responsibility for them. --- ## 8. Scope of profiles Profiles are allowed to vary **breadth within the grammar surface**, but they are not allowed to cross the product boundary. ### 8.1 `pure-gf` Scope: * generic GF projects * real `.gf` modules * compile and GF-static analysis Not allowed to pull in SemantiK-specific runtime files. ### 8.2 `semantik-grammar-surface` Scope: * native GF grammar files * probe assets * direct grammar-surface tools * grammar-surface acceptance assets Not allowed to include runtime adapters or broader app code. ### 8.3 `semantik-wiki-surface` Scope: * Wiki-language GF files * bio/event-related shared layers * Wiki-specific probe assets * Wiki-specific grammar-surface helper tools * French/English and future language-surface probe cases This is the narrowest SemantiK-specific profile and should be treated as the reference profile for the language-leakage class of issues. --- ## 9. Inclusion rules An artifact may be included only if all of the following are true: 1. it belongs to one of the allowed source kinds 2. it is matched by the active profile’s include rules 3. it is not excluded by this contract 4. its role in the grammar surface is reviewable and explicit For direct grammar-facing helper tools, one additional rule applies: 5. the tool’s primary responsibility must be grammar-surface work, not general runtime behavior If there is doubt, the default decision is **exclude** until the artifact is explicitly added to the SemantiK inventory and profile definition. --- ## 10. Exclusion rules An artifact must be excluded if any of the following are true: 1. its primary purpose is runtime execution or routing 2. its primary purpose is planner, renderer, or API behavior 3. it is only indirectly related to grammar-surface behavior 4. including it would require the auditor to make whole-system claims 5. it belongs more naturally to existing SemantiK troubleshooting tools than to this grammar-surface product The default direction of ambiguity is **narrowing**, not broadening. --- ## 11. Non-goals The following are explicit non-goals of this product: * proving planner correctness * proving runtime path correctness * verifying API payload correctness * validating response metadata * asserting which backend generated a final user-facing string in production * replacing SemantiK’s existing troubleshooting tools * becoming a general GF-adjacent code auditor * auditing every file involved in language generation If a proposed feature would push the tool into any of the above, that feature is out of scope unless the product definition itself is intentionally changed. --- ## 12. Allowed future expansion Future expansion is allowed only if it remains inside the grammar surface. Allowed examples: * new `Wiki*.gf` language concretes * new probe fixture types * new forbidden-literal lists * new constructor coverage manifests * new grammar-surface tool checks * new grammar-surface profiles * richer cross-language parity probes Not allowed without an explicit scope revision: * runtime adapter analyzers * fallback-path analyzers * planner-aware analyzers * API contract analyzers * renderer/debug-metadata analyzers * broad Python code auditing This contract therefore permits deeper grammar-surface rigor, but not broader application ownership. --- ## 13. Decision rule for ambiguous files When a file is ambiguous, classify it by **primary responsibility**, not by file extension, directory, or incidental references. Use this order: 1. Does it directly define grammar realization? If yes, classify as `gf_source`. 2. Does it directly define what grammar behavior must be verified? If yes, classify as `probe_asset`. 3. Does it directly compile, inspect, or verify the grammar surface? If yes, classify as `grammar_surface_tool`. 4. Otherwise, exclude it. This rule exists to prevent accidental expansion by convenience. --- ## 14. Contract with the codebase redesign The redesign of the current codebase must respect this scope contract. That means: * the selector must not become a broad repo crawler * source-kind classification must not include runtime/application kinds * analyzer registration must be limited to grammar-surface concerns * report schemas must not imply whole-system guarantees * profile definitions must not cross into runtime/planner/API territory * tests must prove boundary preservation, not only feature coverage Any implementation that violates this contract is considered architecturally incorrect even if it appears to work. --- ## 15. Required enforcement points This scope contract must be enforced in at least these places: * profile definitions * source-kind classification * file selection rules * analyzer registration * report wording * acceptance tests * change-control review The boundary is not protected by prose alone. It must be reflected in executable selection and test behavior. --- ## 16. Required tests for scope integrity The implementation must include tests that prove the boundary is being respected. At minimum: 1. a test that `semantik-wiki-surface` selects `gf/Wiki*.gf` and relevant probe assets 2. a test that runtime adapter files are excluded from grammar-surface profiles 3. a test that non-`.gf` runtime files are never sent through GF compilation 4. a test that grammar-surface tools are included only when explicitly mapped 5. a test that ambiguous files default to exclusion 6. a test that report output does not claim runtime correctness These tests are not optional quality extras. They are part of the scope contract. --- ## 17. Precedence and change policy This file is subordinate only to `docs/00_main_design.md`. Canonical precedence order: 1. `docs/00_main_design.md` 2. `docs/01_scope_contract.md` 3. `docs/02_analyzer_contract.md` 4. `docs/03_report_contract.md` 5. `docs/04_profiles.md` 6. `docs/05_rulepacks.md` 7. `docs/06_probe_spec.md` 8. `docs/07_semantik_inventory.md` 9. `docs/08_acceptance_contract.md` 10. `docs/09_change_control.md` 11. implementation details Implementation details are subordinate to every normative document in this list. Any future change that expands or narrows included artifact families must update all of the following: * `docs/00_main_design.md` * `docs/01_scope_contract.md` * `docs/04_profiles.md` * `docs/07_semantik_inventory.md` * `docs/08_acceptance_contract.md` * `docs/09_change_control.md` No implementation-level broadening is allowed without corresponding contract updates to those files. --- ## 18. One-line operational summary The SemantiK Grammar Surface Auditor owns **GF grammars, Wiki/bioframework realization, and the probe assets and helper tools that directly verify that surface**. It does **not** own runtime, planner, API, or whole-system language behavior. ================================================================================================ FILE: docs/02_analyzer_contract.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: e8446ced3000bbffa0260a5fded6266b2390a9ef5d4825ae6c83652c3c106cb5 CONTENT_BYTES: 16912 ================================================================================================ # Analyzer Contract ## SemantiK Grammar Surface Auditor **Normative document** This file defines the contract for analyzers in the SemantiK Grammar Surface Auditor. Its purpose is to make analyzer behavior explicit, stable, and reviewable so the app does not drift into ad hoc checks, mixed semantics, incompatible result shapes, or hidden profile behavior. This document is **normative**. Any analyzer added to the app must conform to this contract. If implementation behavior conflicts with this contract, this contract takes precedence unless `docs/00_main_design.md` is intentionally revised and this file is updated accordingly. --- ## 1. Purpose of this contract The SemantiK Grammar Surface Auditor is built around analyzers. An analyzer is a bounded unit of audit behavior that examines one artifact or one probe execution context and emits structured evidence. This contract exists to ensure that analyzers: * stay inside the grammar-surface product boundary * have clear responsibilities * produce compatible outputs * do not blur static, compile, and probe semantics * remain composable under one run model * can be added without weakening the architecture This contract prevents two failure modes: 1. analyzers becoming undocumented one-off checks 2. analyzers producing incompatible evidence that cannot be reliably reported, diffed, aggregated, or enforced --- ## 2. Analyzer definition An **analyzer** is a named audit component that: 1. accepts a defined input artifact or probe context 2. runs one bounded analysis method 3. emits zero or more structured findings 4. may emit analyzer-specific summaries 5. never writes directly to final reports 6. never bypasses the common evidence contract An analyzer is not: * a report generator * a profile * a file selector * a generic script runner * a substitute for end-to-end system validation --- ## 3. Analyzer scope rule An analyzer may only reason about artifacts and behaviors that are inside the product scope defined by `docs/01_scope_contract.md`. That means analyzers may operate only on the following source kinds: * `gf_source` * `probe_asset` * `grammar_surface_tool` * `linearization_probe` No analyzer may be introduced for runtime adapters, planner code, API contracts, or broad application behavior unless the product scope itself is revised. --- ## 4. Analyzer categories Every analyzer must belong to exactly one analyzer category. Allowed categories are: * `static` * `compile` * `probe` * `asset` * `tool` ### 4.1 `static` A static analyzer inspects an artifact without executing GF compilation or probe evaluation. Examples: * literal-leak scans in shared GF modules * constructor coverage scans * dependency-shape scans * language-list consistency scans ### 4.2 `compile` A compile analyzer invokes GF compilation or interprets GF compilation output. Examples: * compile a `.gf` module * compile a nominated root grammar or PGF target * parse compiler stderr/stdout * classify direct vs blocked compilation outcomes ### 4.3 `probe` A probe analyzer evaluates observed grammar behavior using explicit probe cases. Examples: * linearize a probe case in `WikiFre` * check forbidden literal leakage * compare outputs across languages * verify required concretes exist in a compiled grammar surface ### 4.4 `asset` An asset analyzer validates probe assets and expectation artifacts. Examples: * validate a probe catalog * validate a required-constructor manifest * validate an expected-concrete manifest * validate a forbidden-literal list ### 4.5 `tool` A tool analyzer validates a direct grammar-surface helper tool. Examples: * verify a compile helper references the expected root grammar * verify a visualization tool’s language list matches the expected Wiki concretes * verify a grammar-surface helper is aligned with current probe expectations --- ## 5. Analyzer identity Every analyzer must have a stable identity with the following fields: * `analyzer_id` * `analyzer_name` * `analyzer_category` * `supported_source_kinds` * `contract_version` ### 5.1 `analyzer_id` A stable machine-readable identifier. Examples: * `gf_static_scan` * `gf_compile` * `gf_dependency_scan` * `probe_fixture_scan` * `expected_concretes_scan` * `required_constructors_scan` * `forbidden_literals_scan` * `gf_linearization_probe` * `forbidden_literal_probe` * `cross_language_probe` This identifier must remain stable across minor implementation changes. ### 5.2 `analyzer_name` A human-readable label used in reports and logs. ### 5.3 `analyzer_category` Must be one of the allowed analyzer categories defined in Section 4. ### 5.4 `supported_source_kinds` A non-empty list of source kinds the analyzer is allowed to run against. ### 5.5 `contract_version` A version string for the analyzer contract implementation. This exists to support controlled evolution without silently changing analyzer semantics. --- ## 6. Allowed analyzer families The initial app must support analyzers from the following families. ### 6.1 GF source analyzers Required analyzer family for `gf_source`: * `gf_static_scan` * `gf_compile` * `gf_dependency_scan` Optional but expected in the SemantiK profiles: * `wiki_constructor_coverage_scan` * `shared_layer_literal_leak_scan` * `realization_hotspot_scan` These may be implemented as distinct analyzers or as stable rule-pack outputs under `gf_static_scan`, but the externally visible semantics must remain explicit. ### 6.2 Probe asset analyzers Required analyzer family for `probe_asset`: * `probe_fixture_scan` * `expected_concretes_scan` * `required_constructors_scan` * `forbidden_literals_scan` ### 6.3 Grammar-surface tool analyzers Allowed analyzer family for `grammar_surface_tool`: * `tool_contract_scan` * `language_list_consistency_scan` These analyzers must remain narrow and tool-specific. ### 6.4 Linearization probe analyzers Required analyzer family for `linearization_probe`: * `gf_linearization_probe` * `forbidden_literal_probe` * `cross_language_probe` --- ## 7. Required analyzer input contract Every analyzer must receive a normalized input object. That input must include at least: * `target_ref` * `source_kind` * `profile_id` * `project_root` * `run_context` * `artifact_metadata` * `related_artifacts` when available ### 7.1 `target_ref` `target_ref` is the canonical analyzer target identifier. It must be: * an artifact reference for artifact analyzers, or * a probe identifier for probe analyzers This field is required for all analyzers. ### 7.2 Artifact analyzers For analyzers operating on files, the input must also include: * `artifact_path` ### 7.3 Probe analyzers For analyzers operating on probe executions, the input must identify: * `probe_id` * root grammar or PGF target * target concrete or language * probe case * expectation set ### 7.4 Run context `run_context` must expose only the context needed for the analyzer to do its work, such as: * active profile * selected analyzers * configured grammar root * configured probe catalog * GF toolchain configuration when relevant Analyzers must not depend on unrelated global state. --- ## 8. Required analyzer output contract Every analyzer must return a structured analyzer result. That result must include: * `analyzer_id` * `analyzer_category` * `source_kind` * `target_ref` * `execution_outcome` * `findings` * `summary` * `related_refs` * `timing_ms` ### 8.1 `target_ref` A normalized reference to the artifact or probe context being analyzed. Examples: * artifact ref for artifact analyzers * probe id for probe analyzers ### 8.2 `execution_outcome` Must be one of: * `completed` * `failed` * `blocked` * `skipped` This field describes whether the analyzer itself ran successfully. It does not replace artifact status, diagnostic class, or finding severity. ### 8.3 `findings` A list of zero or more structured findings. Every finding must conform to the report contract and include at least: * `finding_id` * `rule_id` * `severity` * `message` * `source_kind` * `target_ref` * `analyzer_id` ### 8.4 `summary` A compact analyzer-specific summary. Examples: * compile exit code and error count * number of constructors checked and missing * number of forbidden literals matched * number of expected concretes found or missing ### 8.5 `related_refs` Optional normalized references to related artifacts or probe assets. ### 8.6 `timing_ms` Elapsed execution time in milliseconds. --- ## 9. Findings rules Analyzers do not determine product truth by narrative text. They do so by emitting structured findings. ### 9.1 Mandatory finding fields Every finding emitted by an analyzer must contain: * `finding_id` * `rule_id` * `severity` * `message` * `source_kind` * `target_ref` * `analyzer_id` * `suggested_fix_kind` * `evidence_excerpt` when available ### 9.2 Allowed severity values Allowed severity values are: * `info` * `warning` * `error` Analyzers may not invent new severities. ### 9.3 Allowed suggested fix kinds Allowed values are: * `code` * `fixture` * `config` * `test` * `investigate` Analyzers may not invent new fix kinds without a contract revision. ### 9.4 Rule namespace Every analyzer must emit rule ids from a stable namespace. Recommended namespace families: * `GF...` for generic GF-source rules * `SKA_WIKI_...` for SemantiK Wiki-surface rules * `SKA_PROBE_...` for probe-related rules * `SKA_TOOL_...` for grammar-surface tool rules Rule ids must be stable and documented in `docs/05_rulepacks.md`. --- ## 10. Analyzer responsibilities and limits Each analyzer must do one bounded kind of work. ### 10.1 What an analyzer may do An analyzer may: * inspect the target artifact or probe context * use normalized run configuration * emit findings * emit analyzer-specific summary data * emit related artifact links * declare itself blocked or skipped when prerequisites are missing ### 10.2 What an analyzer may not do An analyzer may not: * alter scope or selection behavior * change profile definitions * write directly to report files * rewrite findings from other analyzers * claim whole-system runtime correctness * make assertions outside the source kind it is authorized for * bypass the shared evidence model * silently downgrade errors into informational messages without contract support --- ## 11. Static, compile, and probe separation The app must preserve a hard distinction between static, compile, and probe semantics. ### 11.1 Static analyzers Static analyzers inspect structure or text patterns. They must not claim successful grammar behavior merely because no suspicious pattern was found. ### 11.2 Compile analyzers Compile analyzers reason about GF compilation. They must not claim successful language behavior merely because compilation succeeded. ### 11.3 Probe analyzers Probe analyzers reason about observed grammar behavior. They may establish behavior failures even when compilation succeeded. This separation is mandatory and must be reflected in analyzer summaries and final reports. --- ## 12. Blocking and dependency behavior Some analyzers depend on prerequisites. Examples: * a probe analyzer may depend on successful compilation * a constructor coverage analyzer may depend on a required-constructor manifest * a tool analyzer may depend on a known tool mapping for the active profile When prerequisites are missing, the analyzer must return `execution_outcome = blocked` or `execution_outcome = skipped` with an explanatory summary. It must not emit fabricated results. --- ## 13. Determinism requirement Analyzers must be deterministic given the same: * project state * profile * configuration * toolchain inputs * probe assets They must not depend on hidden environment state unless that dependency is explicitly declared in the run context and reportable. This is required so runs can be diffed and trusted. --- ## 14. Logging requirement Analyzers may emit diagnostic logs, but logs are secondary artifacts. The normative result of an analyzer is its structured analyzer result. Logs may support debugging, but they must not be the only place where important evidence exists. --- ## 15. Required analyzer behavior by source kind ### 15.1 `gf_source` Analyzers for `gf_source` must support structural or compile-time reasoning over real GF modules. At least one analyzer in this family must be able to produce: * compile evidence * direct error findings * blocked or related artifact references when compile cascades occur SemantiK-specific analyzers in this family should also be able to produce findings for: * shared-layer literal leakage * missing constructor coverage * suspicious realization hotspots ### 15.2 `probe_asset` Analyzers for `probe_asset` must validate the integrity and completeness of grammar verification assets. They must not perform GF compilation unless explicitly delegated to a probe analyzer as part of a defined probe execution flow. ### 15.3 `grammar_surface_tool` Analyzers for `grammar_surface_tool` must remain narrow. They may validate: * root grammar assumptions * language list assumptions * tool/profile consistency They must not become a generic code linter. ### 15.4 `linearization_probe` Analyzers for `linearization_probe` must reason over observed outputs. They must be able to report: * missing concrete behavior * forbidden literal matches * cross-language mismatches * probe execution blockage when prerequisites fail --- ## 16. Analyzer registration contract All analyzers must be registered through a central analyzer registry. The registry must define for each analyzer: * `analyzer_id` * `analyzer_category` * `supported_source_kinds` * `profile_availability` * `prerequisite_requirements` * `enabled_by_default` No analyzer may exist only as an undocumented internal hook. --- ## 17. Profile interaction contract Profiles determine which analyzers are allowed, enabled, or required. An analyzer may be: * `required` * `enabled` * `disabled` for a given profile. ### 17.1 `required` The profile is considered incomplete or invalid if the analyzer cannot run where expected. ### 17.2 `enabled` The analyzer is part of the normal profile run but may be skipped if the relevant source kind is absent. ### 17.3 `disabled` The analyzer must not run under that profile. This contract prevents analyzer creep across profiles. --- ## 18. Failure semantics An analyzer failure and an audit finding are not the same thing. ### 18.1 Analyzer failure The analyzer itself could not complete its work. Examples: * compile subprocess crashed * probe runner initialization failed * malformed asset prevented parsing This must be expressed through `execution_outcome`. ### 18.2 Audit finding The analyzer completed and found a problem in the target. Examples: * English literal found in a shared Wiki layer * missing `mkBioFull` override * French probe output contains `is a` This must be expressed through `findings`. The implementation must not collapse these two concepts into one. --- ## 19. Compatibility with the report contract Analyzers must emit results that can be composed into the shared artifact result model and run summary. That means analyzer outputs must be compatible with: * artifact-level result aggregation * `artifact_status` derivation * `diagnostic_class` derivation * severity bucketing * diff generation * report rendering * acceptance checks Analyzer-specific summaries are allowed, but only inside the shared result shape. --- ## 20. Required tests for analyzers Every analyzer family must be covered by contract tests. At minimum, the implementation must include tests that verify: 1. the analyzer rejects unsupported source kinds 2. the analyzer emits a valid structured result 3. the analyzer emits findings in the required schema 4. the analyzer uses only allowed severity values 5. blocked prerequisites produce `blocked` or `skipped`, not fabricated findings 6. deterministic input produces deterministic output 7. analyzer registration matches profile availability 8. analyzer output can be consumed by the report layer without special handling These tests are part of the contract, not optional quality extras. --- ## 21. Change policy Any change to analyzer behavior requires review if it affects: * supported source kinds * required fields * severity semantics * rule id namespaces * execution outcome semantics * profile availability * summary field meaning If any of these change, this contract and the relevant rule pack or report contract must be updated. No silent analyzer drift is allowed. --- ## 22. One-line operational summary An analyzer is a bounded, registered, source-kind-aware audit component that emits structured evidence inside the grammar-surface product boundary and never bypasses the shared result contract. ================================================================================================ FILE: docs/03_report_contract.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: c6a81010bdaf964946a2f14f630af64233c4b601aa470c7697e891ca44008a2e CONTENT_BYTES: 26005 ================================================================================================ # Report Contract ## SemantiK Grammar Surface Auditor **Normative document** This file defines the report and result contract for the SemantiK Grammar Surface Auditor. Its purpose is to make output shape, report semantics, and result aggregation stable, machine-readable, and reviewable. This document is **normative**. Any implementation of the auditor must produce outputs that conform to this contract. This document is subordinate only to: 1. `docs/00_main_design.md` 2. `docs/01_scope_contract.md` 3. `docs/02_analyzer_contract.md` This document takes precedence over: 1. `docs/04_profiles.md` 2. `docs/05_rulepacks.md` 3. `docs/06_probe_spec.md` 4. `docs/07_semantik_inventory.md` 5. `docs/08_acceptance_contract.md` 6. `docs/09_change_control.md` 7. implementation details 8. tests that attempt to redefine report meaning If implementation behavior conflicts with this contract, this contract takes precedence unless one of the higher-authority documents listed above is intentionally revised and this file is updated accordingly. --- ## 1. Purpose of this contract The SemantiK Grammar Surface Auditor produces audit results that must be: * structurally stable * semantically clear * analyzable by machines * readable by humans * compatible with diffs and regression checks * honest about what the tool does and does not prove This contract exists to prevent six failure modes: 1. report drift across implementations or refactors 2. incompatible analyzer outputs being forced into ad hoc report text 3. mixed semantics between static findings, compile results, aggregate probe results, and per-execution probe results 4. misleading summaries that imply broader guarantees than the tool provides 5. machine-readable outputs becoming an afterthought instead of the main contract 6. probe-reporting fields being redefined inconsistently across documents The canonical output of the app is the **structured run result**. Human-readable reports are derived from that result. --- ## 2. Reporting principles 1. The machine-readable contract is authoritative. 2. Human-readable reports must be derivable from the machine-readable result. 3. Compile evidence, aggregate probe evidence, per-execution probe evidence, and static findings must remain distinct. 4. Report text must not claim runtime or whole-system correctness. 5. Status aggregation must be deterministic and explainable. 6. Findings must be preserved as structured objects, not flattened into prose. 7. Profiles may vary breadth, but they may not change the meaning of core fields. 8. Report contracts must remain stable enough for golden tests and diffs. 9. `probe_summary` is the aggregate artifact-level probe object. 10. `probe_execution_summary` is the per-execution probe object. 11. `docs/06_probe_spec.md` may define probe behavior and the shape of `probe_execution_summary`, but it must not redefine `probe_summary`. --- ## 3. Output artifact set Each run must produce a report set under a run directory. Required run outputs: * `summary.json` * `summary.md` * `AI_READY.md` * `top_errors.txt` Required conditional outputs: * per-artifact logs when analyzers produce logs * diff artifacts when a previous comparable run exists Optional outputs: * auxiliary detail files * analyzer-specific debug files * cached probe artifacts * normalized intermediate snapshots Optional outputs must not replace the required run outputs. --- ## 4. Canonical report artifact The canonical report artifact is: * `summary.json` All other report outputs must be derivable from `summary.json`. `summary.md`, `AI_READY.md`, and `top_errors.txt` are presentation artifacts. They are important, but they are not the primary contract. If a conflict arises between `summary.json` and a human-readable file, `summary.json` is authoritative. --- ## 5. Top-level run result contract The top-level run result must contain at least the following fields: * `contract_version` * `product_name` * `run_id` * `profile_id` * `project_root` * `started_at` * `finished_at` * `duration_ms` * `selection_summary` * `run_status` * `artifact_results` * `counts` * `severity_totals` * `diagnostic_class_totals` * `analyzers_used` * `diff_summary` * `notes` ### 5.1 `contract_version` Version string for the report contract. This must change only when the meaning or required shape of the report changes. ### 5.2 `product_name` Must identify the app consistently. Recommended value: * `SemantiK Grammar Surface Auditor` ### 5.3 `run_id` Stable unique identifier for the run. ### 5.4 `profile_id` The active profile used for the run. Examples: * `pure-gf` * `semantik-grammar-surface` * `semantik-wiki-surface` ### 5.5 `project_root` Resolved project root used for the run. ### 5.6 `started_at` Start timestamp in a stable machine-readable format. ### 5.7 `finished_at` Finish timestamp in a stable machine-readable format. ### 5.8 `duration_ms` Total run duration in milliseconds. ### 5.9 `selection_summary` Structured summary of what was selected and why. ### 5.10 `run_status` Aggregate status for the run. Allowed values are defined in Section 8. ### 5.11 `artifact_results` List of artifact-level results. This is the core body of the report. ### 5.12 `counts` Structured counts of selected, analyzed, skipped, blocked, and failing artifacts. ### 5.13 `severity_totals` Aggregate counts by severity. ### 5.14 `diagnostic_class_totals` Aggregate counts by diagnostic class. ### 5.15 `analyzers_used` List of analyzer ids that ran or were attempted. ### 5.16 `diff_summary` Summary of changes relative to a comparable previous run when available. ### 5.17 `notes` Optional bounded note field for non-structured run-level commentary. This field must never contain primary evidence. --- ## 6. Selection summary contract `selection_summary` must include at least: * `profile_id` * `source_kinds_enabled` * `candidate_count` * `selected_count` * `excluded_count` * `excluded_by_contract_count` * `selection_roots` * `selection_filters` * `single_file_mode` * `target_file` when applicable This summary exists to make scope and inclusion decisions reviewable. --- ## 7. Artifact result contract Every selected artifact or probe execution represented in the run must produce one artifact result. Each artifact result must include at least: * `artifact_ref` * `artifact_path` * `source_kind` * `selected_by_profile` * `artifact_status` * `diagnostic_class` * `fingerprint` * `analyzers_run` * `blocked_by` * `compile_summary` * `probe_summary` * `probe_execution_summary` * `findings` * `related_artifacts` * `timing_ms` ### 7.1 `artifact_ref` Stable run-local identifier for the artifact result. ### 7.2 `artifact_path` Path to the artifact when applicable. For `linearization_probe`, `artifact_path` may be `null` if `artifact_ref` and probe identity are sufficient. ### 7.3 `source_kind` Must be one of: * `gf_source` * `probe_asset` * `grammar_surface_tool` * `linearization_probe` ### 7.4 `selected_by_profile` Boolean indicating whether the artifact was explicitly selected by the active profile rather than appearing only as a related or blocked dependency. ### 7.5 `artifact_status` The aggregate status for the artifact. Allowed values are defined in Section 8. ### 7.6 `diagnostic_class` High-level classification of the artifact result. Allowed values are defined in Section 9. ### 7.7 `fingerprint` Stable fingerprint for artifact content or probe identity. ### 7.8 `analyzers_run` List of analyzer result headers or analyzer ids that were executed or attempted. ### 7.9 `blocked_by` List of artifact refs or analyzer prerequisites that blocked meaningful evaluation. ### 7.10 `compile_summary` Compile-analysis summary object. For `gf_source`, this field must be present and may be non-null. For `probe_asset` and `grammar_surface_tool`, this field must be `null`. For `linearization_probe`, this field must be `null`. ### 7.11 `probe_summary` Aggregate artifact-level probe summary object. This field is used only to summarize probe coverage or probe outcomes for a non-probe artifact such as a `gf_source` artifact. This field must never be used for per-execution probe detail. For `linearization_probe`, this field must be `null`. ### 7.12 `probe_execution_summary` Per-execution probe detail object. For `linearization_probe`, this field is required and must be non-null. For `gf_source`, `probe_asset`, and `grammar_surface_tool`, this field must be `null`. ### 7.13 `findings` List of structured findings associated with this artifact result. ### 7.14 `related_artifacts` List of related artifact refs or paths. ### 7.15 `timing_ms` Aggregate artifact-level analysis time in milliseconds. --- ## 8. Status contract ### 8.1 Run status enum Allowed `run_status` values: * `clean` * `issues_found` * `blocked` * `failed` #### `clean` The run completed and no warning or error findings were produced. #### `issues_found` The run completed and produced at least one warning or error finding. #### `blocked` The run completed only partially because required analysis paths were blocked, but the run itself did not catastrophically fail. #### `failed` The run could not reliably produce a valid report due to a run-level failure. ### 8.2 Artifact status enum Allowed `artifact_status` values: * `clean` * `info_only` * `warning` * `error` * `blocked` * `failed` * `skipped` #### `clean` No findings and no analyzer-level failures. #### `info_only` Only informational findings were emitted. #### `warning` At least one warning finding and no error finding. #### `error` At least one error finding. #### `blocked` The artifact could not be meaningfully evaluated because prerequisites were missing. #### `failed` One or more analyzers failed in a way that invalidates normal evaluation of the artifact. #### `skipped` The artifact was intentionally not analyzed under the active conditions. No additional status values are allowed. --- ## 9. Diagnostic class contract `diagnostic_class` is a high-level explanation of the dominant issue class for an artifact result. Allowed values: * `none` * `static_issue` * `compile_issue` * `probe_issue` * `asset_issue` * `tool_issue` * `blocked_dependency` * `analyzer_failure` * `mixed` ### 9.1 `none` No meaningful issue class applies. ### 9.2 `static_issue` The dominant issue comes from static scanning or structural analysis. ### 9.3 `compile_issue` The dominant issue comes from GF compilation. ### 9.4 `probe_issue` The dominant issue comes from observed probe behavior. ### 9.5 `asset_issue` The dominant issue comes from malformed or incomplete probe or expectation assets. ### 9.6 `tool_issue` The dominant issue comes from a grammar-surface helper tool. ### 9.7 `blocked_dependency` The artifact could not be evaluated because another required artifact or prerequisite blocked it. ### 9.8 `analyzer_failure` The analyzer machinery itself failed in a way that dominates interpretation. ### 9.9 `mixed` Multiple issue classes materially apply and no single class dominates. --- ## 10. Findings contract Each artifact result may contain zero or more findings. Every finding must include: * `finding_id` * `rule_id` * `severity` * `message` * `source_kind` * `target_ref` * `artifact_path` * `line` * `span` * `related_paths` * `evidence_excerpt` * `suggested_fix_kind` * `analyzer_id` ### 10.1 `finding_id` Stable run-local identifier for the finding. ### 10.2 `rule_id` Stable rule identifier as defined by the rule packs. Examples: * `GF001` * `SKA_WIKI_012` * `SKA_PROBE_003` ### 10.3 `severity` Allowed values: * `info` * `warning` * `error` ### 10.4 `message` Human-readable explanation of the finding. This must be concise, specific, and bounded. ### 10.5 `source_kind` Must match the source kind of the artifact result that contains the finding. ### 10.6 `target_ref` Artifact ref or probe ref to which the finding belongs. ### 10.7 `artifact_path` Path to the underlying artifact when applicable. May be `null` for synthetic probe contexts if `target_ref` is sufficient. ### 10.8 `line` Line number when available. May be `null` when not applicable. ### 10.9 `span` Character or line span when available. May be `null` when not applicable. ### 10.10 `related_paths` Optional list of related file paths or artifact refs. ### 10.11 `evidence_excerpt` Short excerpt or probe output fragment supporting the finding. ### 10.12 `suggested_fix_kind` Allowed values: * `code` * `fixture` * `config` * `test` * `investigate` ### 10.13 `analyzer_id` Analyzer that emitted the finding. --- ## 11. Analyzer result embedding contract Artifact results may embed analyzer-level summaries, but not raw ad hoc payloads. Recommended field: * `analyzer_results` If used, each analyzer result must include at least: * `analyzer_id` * `analyzer_category` * `execution_outcome` * `summary` * `timing_ms` * `finding_ids` Analyzer-level results must remain compatible with the analyzer contract and must not redefine artifact-level semantics. --- ## 12. Compile summary contract `compile_summary` is used only for compile analysis. For `gf_source`, `compile_summary` must be present. For `probe_asset`, `grammar_surface_tool`, and `linearization_probe`, `compile_summary` must be `null`. When non-null, `compile_summary` must include at least: * `applicable` * `attempted` * `execution_outcome` * `compiler` * `compiler_version` * `target_module` * `exit_code` * `error_count` * `warning_count` * `blocked_reason` * `referenced_modules` ### 12.1 `applicable` Boolean indicating whether compile analysis applies to the artifact. ### 12.2 `attempted` Boolean indicating whether compile analysis was actually attempted. ### 12.3 `execution_outcome` Allowed values: * `completed` * `failed` * `blocked` * `skipped` ### 12.4 `compiler` Name of compiler used. Recommended value for GF compile: * `gf` ### 12.5 `compiler_version` Compiler version when available. ### 12.6 `target_module` Resolved GF module or root grammar target. ### 12.7 `exit_code` Compiler exit code when compilation was attempted. ### 12.8 `error_count` Number of compile errors detected. ### 12.9 `warning_count` Number of compile warnings detected. ### 12.10 `blocked_reason` Required when compile analysis is blocked. ### 12.11 `referenced_modules` Modules referenced in compiler diagnostics when available. `compile_summary` must not be used to report aggregate probe outcomes. `compile_summary` must not be used to report per-execution probe outcomes. --- ## 13. Probe summary contract `probe_summary` is the aggregate artifact-level probe object. It summarizes probe coverage or probe outcomes for a non-probe artifact. It does not represent a single probe execution. It must not be used for `linearization_probe` artifact results. For `gf_source`, `probe_summary` must be present and may be non-null when the active profile enables probe coverage for that artifact. For `probe_asset`, `grammar_surface_tool`, and `linearization_probe`, `probe_summary` must be `null`. When non-null, `probe_summary` must include at least: * `applicable` * `attempted` * `execution_outcome` * `probe_catalog_id` * `probe_case_count` * `probe_pass_count` * `probe_fail_count` * `blocked_reason` * `languages_checked` * `forbidden_literal_hits` * `missing_concretes` * `parity_failures` ### 13.1 `applicable` Boolean indicating whether aggregate probe analysis applies to the artifact. ### 13.2 `attempted` Boolean indicating whether aggregate probe analysis was attempted. ### 13.3 `execution_outcome` Allowed values: * `completed` * `failed` * `blocked` * `skipped` ### 13.4 `probe_catalog_id` Identifier of the active probe catalog. ### 13.5 `probe_case_count` Number of probe cases considered for the artifact. ### 13.6 `probe_pass_count` Number of probe cases that passed. ### 13.7 `probe_fail_count` Number of probe cases that failed. ### 13.8 `blocked_reason` Required when aggregate probe analysis is blocked. ### 13.9 `languages_checked` List of languages or concretes checked. ### 13.10 `forbidden_literal_hits` Count of forbidden-literal matches across the aggregate probe set. ### 13.11 `missing_concretes` List of expected concretes not available to the aggregate probe set. ### 13.12 `parity_failures` Count of cross-language parity failures across the aggregate probe set. `probe_summary` must not be used to report compile outcomes. `probe_summary` must not be used to report single-probe execution detail. --- ## 14. Probe execution summary contract `probe_execution_summary` is the per-execution probe object. It is required for `linearization_probe` artifact results. It is forbidden for `gf_source`, `probe_asset`, and `grammar_surface_tool` artifact results. `probe_execution_summary` must include at least: * `applicable` * `attempted` * `execution_outcome` * `probe_id` * `grammar_target` * `expectation_refs` * `findings_count` * `forbidden_literal_match_count` * `related_constructor_families` * `output_excerpt` It must include exactly one of: * `target_concrete` * `target_language` ### 14.1 `applicable` Boolean indicating whether the probe execution applies. ### 14.2 `attempted` Boolean indicating whether the probe execution was attempted. ### 14.3 `execution_outcome` Allowed values: * `completed` * `failed` * `blocked` * `skipped` ### 14.4 `probe_id` Stable identifier of the executed probe case. ### 14.5 `grammar_target` Compiled grammar, PGF, or root target against which the probe executed. ### 14.6 `target_concrete` Concrete grammar checked by the probe execution. This field must be present when the probe is concrete-oriented. ### 14.7 `target_language` Language checked by the probe execution. This field must be present when the probe is language-oriented. ### 14.8 `expectation_refs` List of expectation or fixture references used by the probe execution. ### 14.9 `findings_count` Number of findings emitted by this probe execution. ### 14.10 `forbidden_literal_match_count` Number of forbidden-literal matches emitted by this probe execution. ### 14.11 `related_constructor_families` List of constructor families materially involved in the probe execution. Examples: * `mkBioProf` * `mkBioNat` * `mkBioFull` * `mkEvent` ### 14.12 `output_excerpt` Short, bounded output fragment from the probe execution when available. ### 14.13 Boundary rule `probe_execution_summary` defines per-execution probe detail only. It must not be used as an aggregate probe object. It must not be renamed to `probe_summary` in any subordinate document. --- ## 15. Count summary contract The run-level `counts` object must include at least: * `candidate_count` * `selected_count` * `analyzed_count` * `clean_count` * `info_only_count` * `warning_count` * `error_count` * `blocked_count` * `failed_count` * `skipped_count` This object must be derivable deterministically from `artifact_results`. --- ## 16. Severity totals contract `severity_totals` must include: * `info` * `warning` * `error` These counts refer to findings, not artifacts. --- ## 17. Diagnostic class totals contract `diagnostic_class_totals` must include counts for every diagnostic class used in the run. Absent classes may be omitted or included as zero, but the implementation must be consistent. --- ## 18. Diff summary contract When diffing against a comparable previous run, `diff_summary` must include at least: * `previous_run_id` * `artifact_count_delta` * `finding_count_delta` * `new_errors` * `resolved_errors` * `new_warnings` * `resolved_warnings` * `changed_artifacts` If no comparable run exists, `diff_summary` may be `null`. Diff output must compare structured values, not only free text. --- ## 19. Human-readable report contract ### 19.1 `summary.md` Must provide: * run identity * profile * top-level status * counts * highest-severity findings * affected artifacts * compact compile / aggregate-probe / probe-execution / static breakdown * clear statement of scope It must remain concise at the top and detailed below. ### 19.2 `AI_READY.md` Must provide: * normalized audit summary * main findings grouped by artifact * explicit next-action framing * enough structured detail for handoff * no inflated claims beyond the report contract ### 19.3 `top_errors.txt` Must provide a compact list of the highest-priority error findings. It is a convenience artifact, not a complete representation of the run. --- ## 20. Report wording constraints Human-readable outputs must not claim any of the following unless explicitly proven by another tool outside this product: * whole-system correctness * runtime-path correctness * planner correctness * API correctness * production behavior correctness Allowed phrasing is limited to grammar-surface conclusions such as: * compile failed * probe failed * forbidden literal leakage detected * missing constructor coverage detected * expected concrete missing * probe asset invalid The reports must stay inside product scope. --- ## 21. Aggregation rules Artifact status must be derived from analyzer outcomes and findings using deterministic rules. Recommended precedence for `artifact_status`: 1. `failed` if analyzer failure dominates evaluation 2. `blocked` if evaluation was meaningfully blocked and no stronger artifact finding exists 3. `error` if any error finding exists 4. `warning` if any warning finding exists and no error finding exists 5. `info_only` if only informational findings exist 6. `skipped` if no relevant analyzer ran by design 7. `clean` otherwise Recommended precedence for `run_status`: 1. `failed` if run-level failure prevents reliable reporting 2. `blocked` if blocking dominates and prevents substantial intended analysis 3. `issues_found` if any artifact has warning or error status 4. `clean` otherwise These rules must be implemented consistently. Aggregate probe counts in `probe_summary` may contribute to `artifact_status` for a non-probe artifact. Per-execution probe findings in `probe_execution_summary` may contribute to `artifact_status` for a `linearization_probe` artifact. Neither object may be folded into `compile_summary`. --- ## 22. Nullability and omission rules Required fields must always be present unless explicitly allowed to be `null`. ### Allowed `null` cases * `artifact_path` for `linearization_probe` contexts when `artifact_ref` is sufficient * `compile_summary` for `probe_asset`, `grammar_surface_tool`, and `linearization_probe` * `compile_summary` for `gf_source` when compile analysis is not applicable under the active mode * `probe_summary` for any artifact that does not use aggregate probe reporting * `probe_execution_summary` for any artifact that is not `linearization_probe` * `line` when no source line exists * `span` when no span exists * `diff_summary` when no previous run is available ### Omission rules * `probe_summary` must be present as a field in every artifact result and set to `null` when not used. * `probe_execution_summary` must be present as a field in every artifact result and set to `null` when not used. * `target_concrete` and `target_language` are the only mutually exclusive fields inside `probe_execution_summary`. * Optional fields must not be silently overloaded with multiple meanings. --- ## 23. Compatibility and versioning The report contract must be versioned. Changes require a contract version update if they affect: * required fields * allowed enum values * field semantics * aggregation semantics * nullability rules * analyzer result embedding meaning * the boundary between `probe_summary` and `probe_execution_summary` Minor additive fields may be allowed without a version bump only if they do not change the meaning of existing fields and do not break current consumers. Renaming `probe_execution_summary` back into `probe_summary` is not a minor additive change. Changing aggregate probe fields into per-execution probe fields is not a minor additive change. --- ## 24. Required validation The implementation must validate report outputs against the report contract. At minimum, the implementation must include: 1. tests for required top-level fields 2. tests for artifact result field validity 3. tests for enum validity 4. tests for finding schema validity 5. tests for compile / aggregate-probe / probe-execution separation 6. tests for stable aggregation behavior 7. tests for diff compatibility 8. golden JSON tests for representative profiles 9. tests that `probe_summary` never contains per-execution fields 10. tests that `probe_execution_summary` never contains aggregate-only fields If `schemas/report.schema.json` exists, `summary.json` must validate against it. --- ## 25. Authority and precedence This file is the sole authority for: * report shape * field semantics * artifact-level summary object meanings * run-level aggregation semantics * nullability rules for report fields `docs/06_probe_spec.md` must define: * probe behavior * probe fixtures and expectations * per-execution probe semantics * the `probe_execution_summary` contract `docs/06_probe_spec.md` must not define or redefine: * aggregate `probe_summary` * top-level run result fields * run-level aggregation rules * report nullability semantics outside probe execution detail Any change to aggregate probe reporting requires coordinated updates to: 1. `docs/00_main_design.md` 2. `docs/03_report_contract.md` 3. `docs/06_probe_spec.md` 4. `schemas/report.schema.json` 5. acceptance tests and golden report fixtures --- ## 26. One-line operational summary The report contract defines a stable, machine-readable audit result in which artifact status, findings, compile summaries, aggregate probe summaries, and per-execution probe summaries remain separate, deterministic, and strictly limited to grammar-surface claims. ================================================================================================ FILE: docs/04_profiles.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 3717bf4df57b7987566ff7fd307672eb7b3ba34538c76bffe18f20aa1f123335 CONTENT_BYTES: 19771 ================================================================================================ # Profiles ## SemantiK Grammar Surface Auditor **Normative document** This file defines the supported profiles for the SemantiK Grammar Surface Auditor. Its purpose is to make profile behavior explicit, stable, and reviewable so the product does not drift into ad hoc selection logic, hidden analyzer toggles, or ambiguous run behavior. This document is **normative**. Any implementation of the auditor must treat profiles according to this contract. If implementation behavior conflicts with this contract, this file takes precedence unless `docs/00_main_design.md` is intentionally revised and this file is updated accordingly. --- ## 1. Purpose of profiles A profile is a named operational contract that defines: * what artifact families are in scope for a run * which source kinds are enabled * which analyzers are allowed, enabled, or required * which probe assets and probe behaviors apply * what breadth of grammar-surface auditing is intended Profiles exist to make runs deterministic and reviewable. Profiles are not convenience presets only. They are part of the product contract. A user must be able to understand from the profile name alone what class of audit is being performed and what class of claim the resulting report is allowed to make. --- ## 2. Profile principles 1. Profiles may vary breadth only within the grammar-surface boundary. 2. Profiles must not broaden the product into runtime, planner, API, or whole-system auditing. 3. Profiles must define source-kind inclusion explicitly. 4. Profiles must define analyzer behavior explicitly. 5. Profiles must not rely on undocumented path heuristics. 6. Profiles must support deterministic selection and deterministic reporting. 7. Single-file mode must remain valid under every profile, but within that profile’s scope. 8. The same field names and result semantics must apply across profiles. --- ## 3. Supported profiles The product supports exactly these initial profiles: * `pure-gf` * `semantik-grammar-surface` * `semantik-wiki-surface` No other profile may be treated as official unless it is added to this contract. --- ## 4. Shared profile model Every profile must define the following fields: * `profile_id` * `profile_name` * `purpose` * `scope_boundary` * `included_source_kinds` * `excluded_source_kinds` * `selection_roots` * `selection_rules` * `enabled_analyzers` * `required_analyzers` * `disabled_analyzers` * `probe_policy` * `default_mode` * `single_file_support` * `intended_use` * `non_goals` These fields may be implemented in code or machine-readable profile files, but their meaning must match this contract. --- ## 5. Profile: `pure-gf` ### 5.1 Identity * `profile_id`: `pure-gf` * `profile_name`: `Pure GF` ### 5.2 Purpose This profile preserves the baseline behavior of the original GF-focused auditor for general GF projects. It exists to ensure that the redesign remains backward-compatible with the strong existing `.gf` auditing path. ### 5.3 Scope boundary In scope: * native GF source files * GF compilation * GF static analysis * GF dependency and failure classification Out of scope: * SemantiK-specific grammar-surface probe assets * SemantiK-specific Wiki or bioframework expectations * grammar-surface helper tool checks unless explicitly declared by a GF-project extension * runtime or application artifacts ### 5.4 Included source kinds * `gf_source` ### 5.5 Excluded source kinds * `probe_asset` * `grammar_surface_tool` * `linearization_probe` Probe execution is outside the default `pure-gf` contract. If generic-GF probe support is added in the future, it must be introduced through an explicit profile extension or a revision of this contract. ### 5.6 Selection roots Typical selection root: * `gf/` The implementation may support alternative GF roots, but they must remain GF-source only under this profile. ### 5.7 Selection rules * include real `.gf` modules only * respect include and exclude filters * support project-wide and single-file runs * do not include SemantiK-specific probe assets by default ### 5.8 Enabled analyzers * `gf_static_scan` * `gf_compile` * `gf_dependency_scan` ### 5.9 Required analyzers * `gf_static_scan` * `gf_compile` ### 5.10 Disabled analyzers * `probe_fixture_scan` * `expected_concretes_scan` * `required_constructors_scan` * `forbidden_literals_scan` * `tool_contract_scan` * `language_list_consistency_scan` * `gf_linearization_probe` * `forbidden_literal_probe` * `cross_language_probe` ### 5.11 Probe policy Default probe policy: * `disabled` This profile must not imply grammar-behavior verification beyond compile and GF static analysis. ### 5.12 Default mode * project-wide audit of selected GF modules ### 5.13 Single-file support * supported In single-file mode, the target must be a valid `gf_source` artifact. ### 5.14 Intended use Use this profile when auditing: * a generic GF project * a set of GF modules outside the SemantiK-specific Wiki or bioframework surface * backward-compatible baseline GF behavior after architecture refactors ### 5.15 Non-goals This profile does not: * prove language-surface correctness beyond compile and static evidence * reason about SemantiK-specific bio or event expectations * reason about runtime or API behavior --- ## 6. Profile: `semantik-grammar-surface` ### 6.1 Identity * `profile_id`: `semantik-grammar-surface` * `profile_name`: `SemantiK Grammar Surface` ### 6.2 Purpose This profile audits the SemantiK grammar surface as a product boundary. It exists to verify: * native GF grammar modules used by SemantiK * grammar-surface probe assets * grammar-facing helper tools * language-surface behavior where probe coverage exists This is the broadest SemantiK-specific profile allowed by the scope contract. ### 6.3 Scope boundary In scope: * native GF grammar files participating in the SemantiK grammar surface * grammar-surface probe assets and expectation files * direct grammar-surface helper tools * probe-driven language behavior verification within the grammar surface Out of scope: * runtime adapters * planner code * API contract code * renderer or debug metadata code * general application logic * broad whole-system tests ### 6.4 Included source kinds * `gf_source` * `probe_asset` * `grammar_surface_tool` * `linearization_probe` ### 6.5 Excluded source kinds No source kinds outside the grammar-surface contract are allowed. ### 6.6 Selection roots Typical roots include: * `gf/` * `fixtures/probes/` * approved grammar-surface helper tool locations * narrowly scoped grammar-surface acceptance asset locations The exact paths must be defined in the SemantiK inventory and profile implementation. ### 6.7 Selection rules * include reviewed grammar-surface artifacts only * rely on explicit include roots and mappings * avoid free-form repo crawling * treat ambiguous artifacts as excluded unless inventory-reviewed * allow single-file targeting only for in-scope artifacts ### 6.8 Enabled analyzers * `gf_static_scan` * `gf_compile` * `gf_dependency_scan` * `probe_fixture_scan` * `expected_concretes_scan` * `required_constructors_scan` * `forbidden_literals_scan` * `tool_contract_scan` * `language_list_consistency_scan` * `gf_linearization_probe` * `forbidden_literal_probe` * `cross_language_probe` Optional SemantiK-specific rule packs such as constructor coverage, shared-layer literal leakage, and realization hotspot checks may be surfaced through the enabled GF-source analyzers, but they must remain documented and profile-owned. ### 6.9 Required analyzers * `gf_static_scan` * `gf_compile` * `probe_fixture_scan` * `gf_linearization_probe` A required analyzer may be marked `skipped` when its relevant source kind is absent from a specific run selection, but the profile contract requires support for it. ### 6.10 Disabled analyzers No additional analyzers may run unless they are explicitly documented as grammar-surface analyzers and added to this contract. ### 6.11 Probe policy Default probe policy: * `enabled` This profile is allowed to make grammar-behavior claims only through explicit probe execution and probe summaries. ### 6.12 Default mode * project-wide audit of the reviewed SemantiK grammar surface ### 6.13 Single-file support * supported Single-file mode may target: * a `gf_source` * a `probe_asset` * a `grammar_surface_tool` A `linearization_probe` target may also be selected through probe id or probe asset mapping if the implementation supports it. ### 6.14 Intended use Use this profile when auditing: * the full reviewed SemantiK grammar surface * grammar modules plus their verification assets * consistency between grammar definitions and language-surface expectations * release or regression checks for the grammar-surface product boundary ### 6.15 Non-goals This profile does not: * validate SemantiK runtime path selection * validate planner-first behavior * validate API payload correctness * claim whole-system generation correctness --- ## 7. Profile: `semantik-wiki-surface` ### 7.1 Identity * `profile_id`: `semantik-wiki-surface` * `profile_name`: `SemantiK Wiki Surface` ### 7.2 Purpose This profile is the narrow, high-signal profile for the Wiki and bioframework realization path. It exists to verify: * shared Wiki grammar layers * concrete Wiki language modules * bio and event constructor coverage * literal leakage risks * language-specific probe behavior for the Wiki surface This is the reference profile for the class of issue where a concrete language resolves correctly but still surfaces another language’s literals. ### 7.3 Scope boundary In scope: * `gf/WikiI.gf` * `gf/WikiEng.gf` * `gf/WikiFre.gf` * related `gf/Wiki*.gf` files * shared Wiki or bioframework GF modules * Wiki-specific probe assets * forbidden literal lists * required constructor manifests * Wiki-focused grammar-surface helpers such as bio evaluation helpers when explicitly inventoried Out of scope: * broader SemantiK grammar files not participating in the Wiki surface unless explicitly mapped * runtime adapters * planner and API behavior * general-purpose helper tools ### 7.4 Included source kinds * `gf_source` * `probe_asset` * `grammar_surface_tool` * `linearization_probe` ### 7.5 Excluded source kinds No source kinds outside grammar-surface scope are allowed. ### 7.6 Selection roots Typical roots include: * `gf/` restricted to `Wiki*.gf` and tightly related shared modules * `fixtures/probes/` restricted to Wiki, bio, and event fixtures * explicitly reviewed Wiki-surface helper tools * tightly scoped Wiki acceptance assets ### 7.7 Selection rules * prefer explicit Wiki-surface inventories * include only files participating in the Wiki or bioframework realization path * default to exclusion when a file’s role is ambiguous * keep the profile intentionally tighter than `semantik-grammar-surface` ### 7.8 Enabled analyzers * `gf_static_scan` * `gf_compile` * `gf_dependency_scan` * `probe_fixture_scan` * `expected_concretes_scan` * `required_constructors_scan` * `forbidden_literals_scan` * `tool_contract_scan` * `language_list_consistency_scan` * `gf_linearization_probe` * `forbidden_literal_probe` * `cross_language_probe` In addition, SemantiK-specific Wiki rule packs are expected to be active through these analyzers. ### 7.9 Required analyzers * `gf_static_scan` * `gf_compile` * `required_constructors_scan` * `forbidden_literals_scan` * `gf_linearization_probe` * `forbidden_literal_probe` ### 7.10 Disabled analyzers Any analyzer not explicitly documented as part of the grammar-surface contract remains disabled. ### 7.11 Probe policy Default probe policy: * `required` This means the profile is not complete unless probe infrastructure is available for the selected Wiki-surface target where probe coverage is expected. Compilation alone is not sufficient for this profile’s primary purpose. ### 7.12 Default mode * focused multi-artifact audit of the Wiki or bioframework surface ### 7.13 Single-file support * supported Single-file mode is especially important for: * `gf/WikiI.gf` * `gf/WikiFre.gf` * `gf/WikiEng.gf` * Wiki-specific probe assets * forbidden-literal files * required-constructor manifests ### 7.14 Intended use Use this profile when auditing: * known or suspected Wiki-surface regressions * language leakage across shared and concrete Wiki layers * French and English surface correctness * bio and event constructor parity * regression fixtures derived from prior Wiki failures ### 7.15 Non-goals This profile does not: * validate runtime selection or fallback behavior * prove production generation correctness * validate all SemantiK grammar modules * replace broader SemantiK troubleshooting tools --- ## 8. Profile comparison | Profile | Main purpose | Included source kinds | Probe policy | Breadth | | :------------------------- | :------------------------------------------- | :------------------------------------------------------------------------ | :----------- | :----------------------------------------- | | `pure-gf` | Generic GF compile and static audit | `gf_source` | disabled | narrow, generic | | `semantik-grammar-surface` | Full SemantiK grammar-surface audit | `gf_source`, `probe_asset`, `grammar_surface_tool`, `linearization_probe` | enabled | broadest allowed within grammar surface | | `semantik-wiki-surface` | Wiki and bioframework language-surface audit | `gf_source`, `probe_asset`, `grammar_surface_tool`, `linearization_probe` | required | narrowest, highest-signal SemantiK profile | --- ## 9. Profile-to-source-kind contract The mapping between profiles and source kinds is fixed by this contract. ### 9.1 Allowed combinations * `pure-gf` → `gf_source` * `semantik-grammar-surface` → `gf_source`, `probe_asset`, `grammar_surface_tool`, `linearization_probe` * `semantik-wiki-surface` → `gf_source`, `probe_asset`, `grammar_surface_tool`, `linearization_probe` ### 9.2 Disallowed combinations Any profile-to-source-kind mapping outside the above set is invalid unless this document is revised. --- ## 10. Profile-to-analyzer contract Profiles govern analyzer availability. ### 10.1 `pure-gf` Required: * `gf_static_scan` * `gf_compile` Enabled: * `gf_dependency_scan` Disabled: * all probe-asset analyzers * all grammar-surface tool analyzers * all probe analyzers ### 10.2 `semantik-grammar-surface` Required: * `gf_static_scan` * `gf_compile` * `probe_fixture_scan` * `gf_linearization_probe` Enabled: * `gf_dependency_scan` * `expected_concretes_scan` * `required_constructors_scan` * `forbidden_literals_scan` * `tool_contract_scan` * `language_list_consistency_scan` * `forbidden_literal_probe` * `cross_language_probe` Optional SemantiK-specific GF-source rule-pack behavior may be active inside enabled analyzers, but it must remain documented and must not appear as an undocumented analyzer. ### 10.3 `semantik-wiki-surface` Required: * `gf_static_scan` * `gf_compile` * `required_constructors_scan` * `forbidden_literals_scan` * `gf_linearization_probe` * `forbidden_literal_probe` Enabled: * `gf_dependency_scan` * `probe_fixture_scan` * `expected_concretes_scan` * `tool_contract_scan` * `language_list_consistency_scan` * `cross_language_probe` No profile may enable undocumented analyzers. --- ## 11. Probe behavior by profile ### 11.1 `pure-gf` Probe behavior is outside the default `pure-gf` contract. A run under this profile must not be described as probe-backed grammar-behavior verification. ### 11.2 `semantik-grammar-surface` Probe behavior is enabled where probe assets and probe targets exist. The report must clearly distinguish: * compile success * static findings * probe results ### 11.3 `semantik-wiki-surface` Probe behavior is a central contract element. This profile must support probe-driven checks such as: * expected concrete presence * forbidden literal leakage * bio and event realization path checks * cross-language comparison where defined A run under this profile must not be described as a full Wiki-surface audit if probe execution was expected but not available. --- ## 12. Selection behavior by profile Profiles must drive selection deterministically. ### 12.1 Inventory-first rule for SemantiK profiles For `semantik-grammar-surface` and `semantik-wiki-surface`, selection should prefer: * explicit inventories * explicit include roots * explicit file-family rules * explicit source-kind mappings These profiles must not rely on broad repo crawling as their main mechanism. ### 12.2 Ambiguity rule If a file is ambiguous under a SemantiK profile, it must default to exclusion until explicitly added to the inventory or profile rules. ### 12.3 Single-file rule Single-file mode does not override scope. A file targeted in single-file mode must still be valid under the selected profile. --- ## 13. Reporting behavior by profile Profiles may differ in breadth, but they must not change the meaning of report fields. That means: * `artifact_status` means the same thing in every profile * `diagnostic_class` means the same thing in every profile * findings use the same severity enum in every profile * `compile_summary` and `probe_summary` keep the same meaning in every profile Profiles may change: * which analyzers run * which artifacts are selected * whether probes are disabled, enabled, or required Profiles may not change: * the meaning of core report fields * the scope contract * the analyzer contract * the report contract --- ## 14. Invalid profile behavior The implementation must reject or flag invalid profile states. Examples of invalid states: * `semantik-wiki-surface` without support for required probe analyzers * `pure-gf` selecting runtime or application files * a SemantiK profile including runtime-adapter source kinds * a profile enabling undocumented analyzers * a profile claiming a grammar-surface audit while probe policy required probes that were not available Invalid profile states must not silently degrade into weaker audits without explicit report visibility. --- ## 15. Required tests for profiles The implementation must include tests that prove profile behavior. At minimum: 1. `pure-gf` selects only `gf_source` artifacts 2. `semantik-grammar-surface` selects only reviewed grammar-surface artifacts 3. `semantik-wiki-surface` selects Wiki-surface artifacts and relevant probe assets 4. runtime or application files are excluded from all SemantiK profiles 5. `pure-gf` does not enable SemantiK probe analyzers by default 6. `semantik-wiki-surface` requires its probe path where coverage is expected 7. single-file mode remains constrained by profile scope 8. report semantics remain stable across profiles These tests are part of the contract. --- ## 16. Change policy Any change to profiles requires contract review if it affects: * profile ids * included source kinds * excluded source kinds * required analyzers * probe policy * scope breadth * inventory expectations * intended use or non-goals If any of these change, this file and the relevant scope, analyzer, or acceptance documents must be updated. No silent profile drift is allowed. --- ## 17. One-line operational summary Profiles are named, normative operating contracts that control selection, analyzer activation, and probe behavior within the fixed grammar-surface boundary, without changing the meaning of core report semantics. ================================================================================================ FILE: docs/05_rulepacks.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 24456f5f31a45e8f9ca8d5304317f5030c9eb32d5f9e9701edc6cd84d957fd81 CONTENT_BYTES: 21190 ================================================================================================ # Rule Packs ## SemantiK Grammar Surface Auditor **Normative document** This file defines the rule-pack contract for the SemantiK Grammar Surface Auditor. Its purpose is to make rule namespaces, rule ownership, rule activation, and rule stability explicit and reviewable so the app does not drift into undocumented checks, unstable identifiers, or profile-specific behavior hidden in implementation details. This document is **normative**. Any rule emitted by the auditor must belong to a documented rule pack defined here. If implementation behavior conflicts with this file, this file takes precedence unless `docs/00_main_design.md` is intentionally revised and this contract is updated accordingly. --- ## 1. Purpose of this contract The auditor emits structured findings. Those findings are only reliable if their `rule_id` values are stable, bounded, and documented. This contract exists to ensure that: * every emitted rule id belongs to a known namespace * rule ownership is explicit * profile-specific SemantiK behavior does not leak into the generic core without review * rule meaning remains stable across runs * rule packs can evolve without silent renumbering or semantic drift This contract prevents three failure modes: 1. undocumented rules appearing from ad hoc analyzer logic 2. unstable rule ids that break diffs, tests, and report consumers 3. SemantiK-specific expectations leaking into `pure-gf` behavior without profile control --- ## 2. Rule pack definition A **rule pack** is a named, versioned collection of stable audit rules. A rule pack: 1. owns one or more rule-id ranges or namespace slices 2. defines which source kinds the rules may apply to 3. defines which profiles may activate the rules 4. defines the intended emitting analyzers 5. defines the stable meaning of each rule id 6. does not replace the analyzer contract or report contract A rule pack is not: * a profile * an analyzer * a source-kind classifier * a free-form text guideline * a substitute for probe fixtures or manifests --- ## 3. Scope rule for rule packs Rule packs may only define rules for artifacts and probe contexts inside the grammar-surface scope. That means rule packs may apply only to: * `gf_source` * `probe_asset` * `grammar_surface_tool` * `linearization_probe` No rule pack may define rules for runtime adapters, planner behavior, API contracts, renderer metadata, or broad application behavior unless the product scope itself is revised. --- ## 4. Relationship to analyzers and findings Rule packs define **what a rule means**. Analyzers define **how the app checks for it**. This distinction is mandatory. ### 4.1 Rule packs do Rule packs do: * assign stable `rule_id` values * define the semantic meaning of each rule * define intended severity defaults * define intended source-kind applicability * define profile ownership and activation boundaries ### 4.2 Rule packs do not Rule packs do not: * execute checks * replace analyzer results * alter report schemas * decide run selection * override scope boundaries * create new finding fields ### 4.3 Findings contract compatibility Every finding emitted under a rule pack must remain compatible with the shared findings contract. That means a rule pack may define rule semantics, but it may not redefine: * required finding fields * allowed severities * allowed suggested fix kinds * analyzer result semantics * artifact result semantics --- ## 5. Required metadata for every rule pack Every rule pack must have stable metadata with at least the following fields: * `pack_id` * `pack_name` * `pack_version` * `namespace_prefixes` * `owned_source_kinds` * `profile_availability` * `emitting_analyzers` * `status` ### 5.1 `pack_id` Stable machine-readable identifier for the rule pack. Examples: * `gf-core` * `ska-wiki-surface` * `ska-probe` * `ska-tooling` ### 5.2 `pack_name` Human-readable label used in documentation and reports when needed. ### 5.3 `pack_version` Version string for controlled rule-pack evolution. A rule-pack version may change when rules are added or clarified. It must not be used as a substitute for changing the meaning of an existing `rule_id`. ### 5.4 `namespace_prefixes` The namespace families owned by the rule pack. Only the namespace families defined in this document are allowed. ### 5.5 `owned_source_kinds` Non-empty list of source kinds to which the pack may apply. ### 5.6 `profile_availability` Defines whether the pack is: * `required` * `enabled` * `disabled` for a given profile. ### 5.7 `emitting_analyzers` List of analyzers allowed to emit rules from the pack. ### 5.8 `status` Must be one of: * `active` * `deprecated` * `retired` --- ## 6. Allowed namespace families The auditor supports exactly these rule-id namespace families: * `GF...` * `SKA_WIKI_...` * `SKA_PROBE_...` * `SKA_TOOL_...` No additional namespace family may be introduced without updating this contract and the analyzer contract. --- ## 7. Namespace ownership and meaning ### 7.1 `GF...` The `GF` namespace is for generic GF-source rules. These rules are allowed to apply to: * `gf_source` These rules are profile-safe for: * `pure-gf` * `semantik-grammar-surface` * `semantik-wiki-surface` These rules must remain generic. They must not encode SemantiK Wiki-specific constructor or language assumptions. ### 7.2 `SKA_WIKI_...` The `SKA_WIKI_` namespace is for SemantiK Wiki-surface and shared/concrete grammar-surface rules. These rules are allowed to apply to: * `gf_source` These rules are profile-owned by: * `semantik-grammar-surface` * `semantik-wiki-surface` These rules must not be active under `pure-gf`. ### 7.3 `SKA_PROBE_...` The `SKA_PROBE_` namespace is for probe-related rules. This namespace covers both: * `probe_asset` * `linearization_probe` This family includes rules about: * probe catalog integrity * expected concrete manifests * required constructor manifests * forbidden literal manifests * probe execution outcomes * forbidden literal matches * cross-language probe mismatches * missing concrete behavior observed through probes ### 7.4 `SKA_TOOL_...` The `SKA_TOOL_` namespace is for grammar-surface helper tool rules. These rules are allowed to apply to: * `grammar_surface_tool` These rules are profile-owned by: * `semantik-grammar-surface` * `semantik-wiki-surface` These rules must not become a general code-lint namespace. --- ## 8. Rule-id format and stability rules Rule ids must be stable, human-readable, and deterministic. ### 8.1 Allowed formats Allowed formats are: * `GF001` * `GF010` * `SKA_WIKI_001` * `SKA_PROBE_003` * `SKA_TOOL_002` ### 8.2 Stability requirement Once a rule id is assigned and released, its meaning must remain stable. The implementation must not: * reuse an old id for a new meaning * silently renumber rules * change a rule from generic GF behavior to SemantiK-specific behavior * move a rule to a different namespace without contract review ### 8.3 Deprecation rule A deprecated rule may remain recognized for compatibility, but it must not be reassigned a new meaning. ### 8.4 Retirement rule A retired rule id must never be reused. ### 8.5 Generated ids are forbidden A rule id must not be generated from: * file paths * analyzer names alone * source text hashes * runtime counters * probe output content Rule ids are part of the public audit contract and must be fixed by documentation. --- ## 9. Severity and fix semantics Rule packs may define intended severity defaults and typical fix directions, but they may not invent new allowed values. ### 9.1 Allowed severities Allowed severities remain: * `info` * `warning` * `error` ### 9.2 Allowed suggested fix kinds Allowed suggested fix kinds remain: * `code` * `fixture` * `config` * `test` * `investigate` ### 9.3 Default versus emitted severity A rule pack may define the normal severity for a rule. However, if a rule explicitly allows more than one emitted severity depending on context, that variance must be documented under that rule. Unbounded severity drift is not allowed. --- ## 10. Initial required rule packs The initial product must define the following rule packs. ### 10.1 Rule pack: `gf-core` * `pack_id`: `gf-core` * `pack_name`: `Generic GF Core Rules` * `pack_version`: `1.0.0` * `namespace_prefixes`: `GF` * `owned_source_kinds`: `gf_source` * `status`: `active` This pack owns generic GF scanning, dependency, and compile rules that remain valid outside SemantiK-specific grammar surfaces. #### 10.1.1 Profile availability * `pure-gf`: `required` * `semantik-grammar-surface`: `required` * `semantik-wiki-surface`: `required` #### 10.1.2 Emitting analyzers * `gf_static_scan` * `gf_compile` * `gf_dependency_scan` #### 10.1.3 Namespace range Reserved initial range: * `GF001` to `GF099` #### 10.1.4 Initial rules | Rule id | Rule name | Default severity | Typical fix kind | Meaning | | :-- | :-- | :-- | :-- | :-- | | `GF001` | `gf_compile_failed` | `error` | `code` | GF compilation failed for the target module. | | `GF002` | `gf_compile_blocked` | `error` | `investigate` | GF compilation for the target could not proceed because of a dependency or prerequisite failure. | | `GF010` | `suspicious_lambda_pattern` | `warning` | `code` | A known suspicious lambda-oriented static pattern was detected in GF source. | | `GF011` | `suspicious_table_pattern` | `warning` | `code` | A known suspicious table-oriented static pattern was detected in GF source. | | `GF020` | `dependency_shape_mismatch` | `warning` | `code` | The module dependency shape or naming relationship is inconsistent with expected GF structure. | ### 10.2 Rule pack: `ska-wiki-surface` * `pack_id`: `ska-wiki-surface` * `pack_name`: `SemantiK Wiki Surface Rules` * `pack_version`: `1.0.0` * `namespace_prefixes`: `SKA_WIKI_` * `owned_source_kinds`: `gf_source` * `status`: `active` This pack owns SemantiK-specific GF-source rules for shared and concrete Wiki/bioframework grammar surfaces. #### 10.2.1 Profile availability * `pure-gf`: `disabled` * `semantik-grammar-surface`: `enabled` * `semantik-wiki-surface`: `required` #### 10.2.2 Emitting analyzers * `gf_static_scan` * `gf_dependency_scan` SemantiK-specific checks may also be surfaced through stable GF-source analyzer extensions, but they must still emit documented `SKA_WIKI_...` ids. #### 10.2.3 Namespace range Reserved initial range: * `SKA_WIKI_001` to `SKA_WIKI_099` #### 10.2.4 Initial rules | Rule id | Rule name | Default severity | Typical fix kind | Meaning | | :-- | :-- | :-- | :-- | :-- | | `SKA_WIKI_001` | `shared_layer_literal_leak` | `error` | `code` | A shared or neutral Wiki layer contains an explicit pivot-language literal where a language-neutral realization layer is expected. | | `SKA_WIKI_002` | `missing_required_constructor_override` | `error` | `code` | A concrete is missing required constructor coverage or override behavior for a documented Wiki/bio/event realization family. | | `SKA_WIKI_003` | `constructor_family_parity_drift` | `warning` | `code` | Constructor families expected to remain aligned across Wiki concretes have materially drifted. | | `SKA_WIKI_004` | `realization_hotspot_concat` | `warning` | `code` | A realization hotspot uses suspicious direct string assembly where stronger language-specific realization is expected. | | `SKA_WIKI_005` | `root_or_concrete_naming_mismatch` | `warning` | `config` | A SemantiK Wiki root or concrete naming relationship does not match the documented grammar-surface expectation. | ### 10.3 Rule pack: `ska-probe` * `pack_id`: `ska-probe` * `pack_name`: `SemantiK Probe and Expectation Rules` * `pack_version`: `1.0.0` * `namespace_prefixes`: `SKA_PROBE_` * `owned_source_kinds`: `probe_asset`, `linearization_probe` * `status`: `active` This pack owns both probe-asset integrity rules and probe-execution behavior rules. #### 10.3.1 Profile availability * `pure-gf`: `disabled` * `semantik-grammar-surface`: `enabled` * `semantik-wiki-surface`: `required` #### 10.3.2 Emitting analyzers * `probe_fixture_scan` * `expected_concretes_scan` * `required_constructors_scan` * `forbidden_literals_scan` * `gf_linearization_probe` * `forbidden_literal_probe` * `cross_language_probe` #### 10.3.3 Namespace ranges Reserved initial ranges: * `SKA_PROBE_001` to `SKA_PROBE_099` for probe-asset integrity rules * `SKA_PROBE_100` to `SKA_PROBE_199` for probe-execution behavior rules #### 10.3.4 Initial probe-asset rules | Rule id | Rule name | Default severity | Typical fix kind | Meaning | | :-- | :-- | :-- | :-- | :-- | | `SKA_PROBE_001` | `missing_probe_case` | `error` | `fixture` | Required grammar-surface probe coverage is missing from the probe catalog or related fixtures. | | `SKA_PROBE_002` | `expected_concrete_missing_from_manifest` | `error` | `fixture` | An expected concrete manifest omits a concrete that should be declared for the active grammar surface. | | `SKA_PROBE_003` | `required_constructor_missing_from_manifest` | `error` | `fixture` | A required constructor family is missing from the constructor manifest. | | `SKA_PROBE_004` | `forbidden_literal_list_missing` | `warning` | `fixture` | A non-English or otherwise protected language surface lacks a forbidden-literal list where leakage protection is expected. | | `SKA_PROBE_005` | `probe_asset_shape_invalid` | `error` | `fixture` | A probe asset is malformed or structurally incompatible with the probe contract. | #### 10.3.5 Initial probe-execution rules | Rule id | Rule name | Default severity | Typical fix kind | Meaning | | :-- | :-- | :-- | :-- | :-- | | `SKA_PROBE_101` | `forbidden_literal_matched` | `error` | `code` | Probe output contains a forbidden literal for the target language or concrete. | | `SKA_PROBE_102` | `expected_concrete_unavailable` | `error` | `code` | A probe could not verify the target behavior because a required concrete was not available in the compiled grammar surface. | | `SKA_PROBE_103` | `required_constructor_probe_failed` | `error` | `code` | A probe for a required constructor family failed to realize correctly. | | `SKA_PROBE_104` | `cross_language_probe_mismatch` | `warning` | `investigate` | Cross-language probe comparison found a material mismatch beyond the documented expectation set. | | `SKA_PROBE_105` | `probe_execution_blocked` | `error` | `investigate` | Probe execution was blocked by a required dependency or prerequisite failure. | ### 10.4 Rule pack: `ska-tooling` * `pack_id`: `ska-tooling` * `pack_name`: `SemantiK Grammar-Surface Tool Rules` * `pack_version`: `1.0.0` * `namespace_prefixes`: `SKA_TOOL_` * `owned_source_kinds`: `grammar_surface_tool` * `status`: `active` This pack owns tool-specific consistency rules for grammar-facing helper tools. #### 10.4.1 Profile availability * `pure-gf`: `disabled` * `semantik-grammar-surface`: `enabled` * `semantik-wiki-surface`: `enabled` #### 10.4.2 Emitting analyzers * `tool_contract_scan` * `language_list_consistency_scan` #### 10.4.3 Namespace range Reserved initial range: * `SKA_TOOL_001` to `SKA_TOOL_099` #### 10.4.4 Initial rules | Rule id | Rule name | Default severity | Typical fix kind | Meaning | | :-- | :-- | :-- | :-- | :-- | | `SKA_TOOL_001` | `root_grammar_assumption_mismatch` | `error` | `config` | A grammar-surface helper tool assumes the wrong root grammar or PGF target for the active profile. | | `SKA_TOOL_002` | `language_list_drift` | `warning` | `config` | A grammar-surface helper tool uses a language list inconsistent with the reviewed grammar surface or expected concrete inventory. | | `SKA_TOOL_003` | `invocation_contract_drift` | `warning` | `config` | A grammar-surface helper tool’s expected invocation contract has drifted from the documented grammar-surface contract. | | `SKA_TOOL_004` | `outdated_concrete_inventory` | `warning` | `config` | A grammar-surface helper tool hardcodes an outdated concrete inventory. | --- ## 11. Profile activation rules Profiles decide which rule packs are allowed, enabled, or required. ### 11.1 `pure-gf` The `pure-gf` profile must activate only: * `gf-core` It must not activate: * `ska-wiki-surface` * `ska-probe` * `ska-tooling` This prevents SemantiK-specific semantics from leaking into generic GF auditing. ### 11.2 `semantik-grammar-surface` The `semantik-grammar-surface` profile must activate: * `gf-core` * `ska-probe` It may also activate when relevant source kinds are present: * `ska-wiki-surface` * `ska-tooling` This profile is broad enough to cover the reviewed SemantiK grammar surface without making every Wiki-specific expectation mandatory in every run selection. ### 11.3 `semantik-wiki-surface` The `semantik-wiki-surface` profile must activate: * `gf-core` * `ska-wiki-surface` * `ska-probe` It may activate: * `ska-tooling` when reviewed Wiki-surface helper tools are part of the run selection. This profile is the reference profile for literal leakage, constructor coverage, and language-specific probe behavior. --- ## 12. Applicability rules by source kind ### 12.1 `gf_source` Allowed namespaces: * `GF...` * `SKA_WIKI_...` A `gf_source` finding must not use: * `SKA_PROBE_...` * `SKA_TOOL_...` unless the target is actually a probe context or grammar-surface tool. ### 12.2 `probe_asset` Allowed namespaces: * `SKA_PROBE_...` A `probe_asset` finding must not use: * `GF...` * `SKA_WIKI_...` * `SKA_TOOL_...` ### 12.3 `grammar_surface_tool` Allowed namespaces: * `SKA_TOOL_...` ### 12.4 `linearization_probe` Allowed namespaces: * `SKA_PROBE_...` A probe-execution finding must not be rewritten as a `GF...` compile finding merely because compilation was part of the prerequisite chain. --- ## 13. Rules for adding new rules New rules may be added only when all of the following are true: 1. the rule belongs to an existing documented rule pack 2. the namespace and range assignment are explicit 3. the rule meaning is bounded and testable 4. the intended source kinds are documented 5. the intended profiles are documented 6. at least one analyzer is authorized to emit the rule 7. tests are added for both positive and negative cases where practical Adding a new rule without documenting it here is not allowed. --- ## 14. Rules for changing existing rules An existing rule may be clarified, but not silently redefined. ### 14.1 Allowed changes Allowed changes include: * wording clarification * evidence-quality improvements * tighter implementation of the same semantic rule * narrower false-positive behavior without changing the rule’s meaning ### 14.2 Review-required changes The following changes require coordinated review and contract updates: * changing the meaning of a rule * changing the default severity of a rule * changing source-kind applicability * moving a rule to another namespace * splitting one rule into several new rule ids * merging multiple rules into one rule id * making a profile-owned rule active under `pure-gf` ### 14.3 Forbidden changes Forbidden changes include: * silent renumbering * reusing retired ids * making SemantiK-specific rules appear as generic GF rules * inventing undocumented rule ids in implementation code --- ## 15. Reporting and diffing requirements Rule ids must remain usable across: * report rendering * severity bucketing * artifact aggregation * run-to-run diffs * acceptance fixtures * AI handoff artifacts This means rule identifiers must be: * stable across runs * stable across minor implementation refactors * specific enough to explain the issue class * coarse enough to avoid meaningless id proliferation One textual variation of a message must not cause a new rule id to appear. --- ## 16. Required tests for rule packs The implementation must include tests that verify at least the following: 1. every emitted rule id belongs to a documented namespace 2. undocumented rule ids are rejected or flagged during development 3. `pure-gf` cannot emit `SKA_WIKI_...`, `SKA_PROBE_...`, or `SKA_TOOL_...` 4. `probe_asset` findings use `SKA_PROBE_...` ids only 5. `grammar_surface_tool` findings use `SKA_TOOL_...` ids only 6. `linearization_probe` findings use `SKA_PROBE_...` ids only 7. retired or deprecated ids are not silently reused 8. representative fixture runs emit the expected stable rule ids These tests are part of the rule-pack contract, not optional documentation checks. --- ## 17. Change policy Any change to rule packs requires review if it affects: * namespace families * rule-id stability * default severity * source-kind applicability * profile activation * emitting analyzer ownership * reserved id ranges * compatibility with report diffs or acceptance fixtures If any of these change, the relevant profile contract, analyzer contract, report contract, probe specification, or acceptance contract must be updated as well. No silent rule-pack drift is allowed. --- ## 18. One-line operational summary A rule pack is the stable, documented source of truth for what a finding’s `rule_id` means, where it may appear, and under which profile-owned grammar-surface conditions it may be emitted. ================================================================================================ FILE: docs/06_probe_spec.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: c78fa2cb2e31d135827265d9969e3c769bf326fd08519cdc732d907be3004461 CONTENT_BYTES: 22349 ================================================================================================ # Probe Specification ## SemantiK Grammar Surface Auditor **Normative document** This file defines the probe contract for the SemantiK Grammar Surface Auditor. Its purpose is to make probe behavior, probe assets, probe execution semantics, and probe evidence stable, explicit, and reviewable. This document is **normative**. Any implementation of grammar-surface probes must conform to this contract. This document owns **per-execution probe semantics** and the `probe_execution_summary` object. Aggregate artifact-level probe reporting remains defined by `docs/03_report_contract.md`. If implementation behavior conflicts with this document, higher-order normative contracts take precedence in this order: 1. `docs/00_main_design.md` 2. `docs/01_scope_contract.md` 3. `docs/02_analyzer_contract.md` 4. `docs/03_report_contract.md` This file must be updated whenever those higher contracts intentionally revise probe-related behavior. --- ## 1. Purpose of this contract The SemantiK Grammar Surface Auditor is allowed to make language-behavior claims only through explicit probe behavior defined inside the grammar surface. This contract exists to ensure that probes: * remain inside grammar-surface scope * use explicit, reviewable assets * distinguish compile success from observed language behavior * emit structured evidence instead of informal prose * behave consistently across profiles * can be validated, diffed, and regression-tested This contract prevents four failure modes: 1. treating compile success as proof of language correctness 2. treating ad hoc scripts or hand-run checks as equivalent to probe evidence 3. mixing blocked execution, analyzer failure, and grammar-surface findings 4. letting profile behavior change probe meaning silently --- ## 2. Probe boundary A probe is part of the grammar surface only when it directly verifies authored grammar behavior. This contract therefore covers only: * probe assets that define what the auditor must verify * `linearization_probe` execution contexts created from those assets * grammar outputs produced from in-scope GF roots or PGF targets * language-behavior assertions such as concrete presence, constructor coverage, forbidden-literal absence, and cross-language checks This contract does **not** cover: * runtime routing or planner behavior * production API behavior * fallback-path behavior * whole-system generation tests * generic script execution outside the grammar-surface boundary --- ## 3. Relationship to higher contracts This file is subordinate to the product boundary, analyzer contract, report contract, active profile contract, and documented rule packs. This document must be read consistently with at least: 1. `docs/00_main_design.md` 2. `docs/01_scope_contract.md` 3. `docs/02_analyzer_contract.md` 4. `docs/03_report_contract.md` 5. `docs/04_profiles.md` 6. `docs/05_rulepacks.md` This file defines probe-specific execution requirements that those higher contracts rely on but do not fully spell out. This file does **not** redefine aggregate artifact-level probe reporting. Aggregate artifact-level `probe_summary` is defined only by `docs/03_report_contract.md`. Inventory, acceptance, and change-control documents impose additional constraints on what probe assets exist, what must pass, and how changes are governed: * `docs/07_semantik_inventory.md` * `docs/08_acceptance_contract.md` * `docs/09_change_control.md` --- ## 4. Probe principles 1. Probes are first-class evidence, not optional narrative commentary. 2. Probes verify observed grammar behavior, not runtime system behavior. 3. Probe assets must be explicit, reviewable, and version-controlled. 4. Probe execution must remain separate from compile summaries. 5. A completed probe that finds language defects is more important than compile success for language-surface correctness. 6. A blocked probe is not the same as a failed probe. 7. A failed probe analyzer is not the same as a grammar-surface finding. 8. Probe semantics must remain deterministic for the same project state, profile, toolchain inputs, and probe assets. 9. Aggregate artifact-level probe reporting and per-execution probe reporting must remain separate objects with separate ownership. --- ## 5. Definitions ### 5.1 Probe A **probe** is an explicit grammar-behavior verification unit that evaluates one defined case against one compiled grammar target and one concrete or language. A probe is not an informal manual test and not a broad end-to-end scenario. ### 5.2 Probe asset A **probe asset** is a non-`.gf` artifact that defines what probe behavior must be executed or validated. Examples include: * probe catalogs * expected concrete manifests * required constructor manifests * forbidden-literal lists * language-specific expectation files ### 5.3 Linearization probe A **linearization probe** is a `linearization_probe` source-kind context representing one defined probe case executed against one compiled grammar root or PGF target and one concrete or language. It exists to verify observed outputs such as: * successful linearization * required concrete availability * absence of forbidden literals * constructor realization behavior * cross-language mismatches or parity problems A `linearization_probe` may contribute to two different result layers: * aggregate artifact-level `probe_summary`, defined by `docs/03_report_contract.md` * per-execution `probe_execution_summary`, defined by this document ### 5.4 Probe catalog A **probe catalog** is the canonical asset that defines which probe cases exist, which grammar target they run against, which languages they apply to, and which expectations they bind to. ### 5.5 Probe case A **probe case** is one language-agnostic realization scenario such as a biography or event construction that the auditor must be able to evaluate in one or more concretes. ### 5.6 Expectation set An **expectation set** is the explicit bundle of assertions that applies to a probe case for a given language or concrete. An expectation set may include: * required concrete existence * forbidden literal absence * required constructor coverage * required non-empty realization * expected or forbidden substrings when explicitly justified * cross-language comparison rules when explicitly defined ### 5.7 Forbidden-literal set A **forbidden-literal set** is a language-specific asset listing literals that must not appear in outputs for that language. In the Wiki-surface context, this is a primary guard against inherited English leakage in non-English outputs. --- ## 6. Source kinds and ownership Probe behavior uses exactly these source kinds: * `probe_asset` * `linearization_probe` `probe_asset` owns the authored verification surface. `linearization_probe` owns the observed per-execution surface. A real GF module remains `gf_source`, not `linearization_probe`, even when a probe executes against it. --- ## 7. Profile interaction Profiles govern whether probes are disabled, enabled, or required. ### 7.1 `pure-gf` Probe policy: * `disabled` This profile must not make grammar-behavior claims through SemantiK-specific probe infrastructure. ### 7.2 `semantik-grammar-surface` Probe policy: * `enabled` This profile may execute probes where probe assets and roots are available, but a specific run may remain valid when probe-relevant source kinds are absent from selection. ### 7.3 `semantik-wiki-surface` Probe policy: * `required` Compilation alone is not sufficient for this profile’s primary purpose. Where probe coverage is expected for the selected Wiki-surface target, the run is incomplete unless the relevant probe path is available. --- ## 8. Required probe asset families The implementation must support at least the following asset families. ### 8.1 Probe catalog Canonical path family: * `fixtures/probes/probe_catalog.yaml` Purpose: * define probe cases * define target roots or PGF targets * define applicable languages or concretes * bind cases to expectation assets ### 8.2 Expected concrete manifest Canonical path family: * `fixtures/probes/expected_concretes.yaml` Purpose: * define which concretes are expected for a target grammar surface * provide a reviewable basis for concrete-existence checks ### 8.3 Required constructor manifest Canonical path family: * `fixtures/probes/required_constructors.yaml` Purpose: * define constructor families or realization functions that probe coverage must exercise * provide a reviewable basis for required bio/event coverage ### 8.4 Forbidden-literal files Canonical path family: * `fixtures/probes/forbidden_literals..yaml` Example: * `fixtures/probes/forbidden_literals.fr.yaml` Purpose: * define language-specific literals that must not appear in realized output * provide explicit leakage guards for non-English outputs ### 8.5 Optional language-specific expectation files Additional expectation files are allowed when they remain strictly inside grammar-surface verification. They must not redefine the core semantics of this contract. --- ## 9. Probe execution model A probe execution evaluates one defined case against one grammar target and one concrete or language. The execution model has four layers: 1. resolve probe definition from a probe asset 2. resolve grammar root or PGF target 3. verify prerequisite availability such as required concretes and expectation assets 4. execute the probe analyzers and emit structured evidence Probe execution must be analyzable and repeatable from repository state and run context alone. Per-execution reporting produced from this model belongs in `probe_execution_summary`. Aggregate counting and artifact-level rollup belong in `probe_summary` as defined by `docs/03_report_contract.md`. --- ## 10. Required probe identity Every probe execution context must have a stable identity. At minimum, the normalized probe context must include: * `probe_id` * `target_ref` * `profile_id` * root grammar or PGF target * target concrete or language * probe case identifier * expectation set reference or inline normalized expectation set ### 10.1 `probe_id` `probe_id` is the canonical probe identifier. It must be stable across minor wording or implementation changes. ### 10.2 `target_ref` `target_ref` is the canonical analyzer target for the probe execution. For probe analyzers, it may equal `probe_id` when that is sufficient. ### 10.3 Grammar target identity The probe context must identify exactly one of the following: * a GF root grammar, or * a compiled PGF target The target must be explicit. Implicit default targets are not allowed unless they are first resolved and recorded in normalized run context. ### 10.4 Concrete or language identity The probe context must identify the intended output target as exactly one of: * `target_concrete`, or * `target_language` The implementation may normalize one from the other, but it must not leave the target ambiguous and it must not record both as primary fields for the same execution context. ### 10.5 Probe case identity The probe context must identify the case being executed, such as a biography or event realization scenario. ### 10.6 Expectation identity The probe context must identify which expectation assets or normalized expectation set govern interpretation of the result. --- ## 11. Required probe catalog contract A probe catalog defines the set of valid probe cases. Each probe catalog entry must include at least: * `probe_id` * `probe_case_id` * `grammar_target` * `languages` or `concretes` * `input_kind` * `input_value` * `expectation_refs` ### 11.1 `grammar_target` Must identify the root grammar or PGF target against which the probe runs. ### 11.2 `languages` or `concretes` The catalog must explicitly declare the intended output targets. A probe must not silently expand to unrelated languages. ### 11.3 `input_kind` Allowed values: * `tree` * `canned_expression` Additional input kinds require a contract revision. ### 11.4 `input_value` The executable tree or canned expression used by the probe. ### 11.5 `expectation_refs` A non-empty list of expectation assets or expectation groups that apply to the probe. ### 11.6 Optional metadata Optional catalog metadata may include: * `probe_family` * `constructor_family` * `notes` * `related_paths` Optional metadata must not replace required fields. --- ## 12. Expectation contract Every executable probe must have an expectation set. An expectation set may be assembled from one or more assets, but its normalized semantics must be explicit at execution time. ### 12.1 Required expectation classes The implementation must support at least these expectation classes: * concrete existence * linearization success * forbidden literal absence * constructor coverage relevance * optional cross-language comparison ### 12.2 Concrete existence expectation A probe may require that a nominated concrete exists before execution. If the concrete is absent, the probe is normally `blocked`, not `completed`. ### 12.3 Linearization success expectation A completed probe must be able to state whether linearization produced a usable output. A non-empty output is necessary but is not sufficient for language correctness. ### 12.4 Forbidden literal expectation A completed probe may assert that no literal from the applicable forbidden-literal set appears in output. A forbidden-literal match is a real grammar-surface finding even when compilation succeeded. ### 12.5 Constructor coverage relevance A probe may be declared relevant to a required constructor family such as `mkBioProf`, `mkBioNat`, `mkBioFull`, or `mkEvent`. This does not replace the manifest-level asset check, but it binds execution evidence to required realization coverage. ### 12.6 Cross-language comparison expectation A probe may define a cross-language comparison rule when explicitly justified by the profile or asset set. Cross-language comparison must remain explicit and must not devolve into vague string similarity heuristics. --- ## 13. Probe analyzers The implementation must support these probe analyzers for `linearization_probe`: * `gf_linearization_probe` * `forbidden_literal_probe` * `cross_language_probe` ### 13.1 `gf_linearization_probe` Primary responsibility: * resolve target grammar or PGF * verify required concrete availability * execute the probe case * return observed output or an execution blockage ### 13.2 `forbidden_literal_probe` Primary responsibility: * evaluate the observed output against the applicable forbidden-literal set * emit structured findings when forbidden literals are matched ### 13.3 `cross_language_probe` Primary responsibility: * evaluate explicit cross-language expectations defined by the active expectation set * emit structured findings when the comparison contract fails These analyzers must remain compatible with the analyzer contract and report contract. --- ## 14. Execution outcomes and probe semantics Probe analyzers use analyzer-level execution outcomes defined by the analyzer contract: * `completed` * `failed` * `blocked` * `skipped` These values describe the analyzer execution state, not the truth of the grammar surface. ### 14.1 `completed` The analyzer ran normally and produced interpretable probe evidence. A completed probe may still emit `warning` or `error` findings. ### 14.2 `blocked` The analyzer could not meaningfully execute because a declared prerequisite was missing. Typical examples: * required concrete absent * grammar target unavailable * expectation asset missing * compilation prerequisite not met A blocked probe must not fabricate pass-or-fail behavior. ### 14.3 `failed` The analyzer itself failed to do its work. Typical examples: * probe runner crashed * parser initialization failed * analyzer-internal exception prevented interpretation This is not equivalent to a grammar finding. ### 14.4 `skipped` The analyzer did not run by design under the active conditions. Typical examples: * cross-language comparison not requested * relevant source kind absent * probe policy disabled the analyzer --- ## 15. Probe findings Probe analyzers must emit structured findings using the common finding model. Every probe finding must include at least: * `finding_id` * `rule_id` * `severity` * `message` * `source_kind` * `target_ref` * `analyzer_id` * `suggested_fix_kind` * `evidence_excerpt` when available Probe findings must use rule ids from the documented probe-rule namespace in `docs/05_rulepacks.md`. ### 15.1 Allowed severities Allowed severities are: * `info` * `warning` * `error` ### 15.2 Typical probe findings Typical completed-probe findings include: * forbidden literal found in non-English output * required concrete missing from compiled target * probe output empty or unusable where output is required * constructor-realization behavior missing for a required case * explicit cross-language comparison failure ### 15.3 Suggested fix kinds Probe findings must use only allowed fix kinds: * `code` * `fixture` * `config` * `test` * `investigate` --- ## 16. Required `probe_execution_summary` contract When per-execution probe analysis is applicable, the artifact result must expose a `probe_execution_summary` separate from both `compile_summary` and the aggregate `probe_summary`. Aggregate artifact-level probe reporting is defined only by `docs/03_report_contract.md`. This section defines only the per-execution probe object. `probe_execution_summary` must include at least: * `applicable` * `attempted` * `execution_outcome` * `probe_id` * `grammar_target` * exactly one of `target_concrete` or `target_language` * `expectation_refs` * `findings_count` * `forbidden_literal_match_count` * `related_constructor_families` * `output_excerpt` ### 16.1 `applicable` Boolean indicating whether per-execution probe analysis is relevant for the artifact or probe context. ### 16.2 `attempted` Boolean indicating whether execution was actually attempted. ### 16.3 `execution_outcome` Must use analyzer outcome semantics: * `completed` * `failed` * `blocked` * `skipped` ### 16.4 `grammar_target` The resolved root grammar or PGF target used for the probe. ### 16.5 `expectation_refs` The expectation assets or normalized expectation groups applied to the probe. ### 16.6 `related_constructor_families` A normalized list of constructor families that this probe execution is intended to exercise, such as `mkBioProf`, `mkBioNat`, `mkBioFull`, or `mkEvent`. ### 16.7 `output_excerpt` A short bounded excerpt of observed output when available. This field supports diagnostics and must not be overloaded into a full transcript store. --- ## 17. Separation from compile evidence and aggregate probe reporting Probe evidence must remain separate from compile evidence. This is mandatory. The implementation must not: * merge probe results into `compile_summary` * treat successful compilation as a passed probe * suppress probe findings merely because compilation succeeded * collapse aggregate `probe_summary` and per-execution `probe_execution_summary` into one object * replace probe execution with static heuristics when explicit probe assets exist Compilation is a prerequisite for some probes. It is not a substitute for them. Aggregate artifact-level probe reporting and per-execution probe reporting serve different purposes and must remain separate. --- ## 18. Required blocked-by semantics When a probe is meaningfully blocked, the artifact result must expose the blocking cause through normal result fields such as: * `blocked_by` * analyzer `execution_outcome` * `probe_execution_summary.execution_outcome` * analyzer summary text Typical blockers include: * missing required concrete * missing compiled target * missing probe asset * malformed expectation asset * disabled or unavailable probe infrastructure under a profile where probes are required A blocked probe execution must remain visible as blocked per-execution probe evidence. It must not be rewritten into a passed aggregate summary or omitted from per-execution reporting. --- ## 19. Determinism and reproducibility Probe execution must be deterministic given the same: * project state * active profile * normalized probe assets * grammar root or PGF target * GF toolchain inputs The implementation must not rely on hidden environment state that changes probe interpretation without reportable run-context differences. --- ## 20. Required tests for probes The implementation must include tests that prove probe behavior is correct and stable. At minimum, the test suite must verify: 1. probe catalogs produce normalized probe contexts with stable identities 2. a required concrete absence yields `blocked`, not a fabricated pass or fail 3. forbidden-literal matches produce structured findings 4. probe findings remain separate from compile findings 5. `probe_execution_summary` is emitted when per-execution probe analysis is applicable 6. aggregate `probe_summary` and per-execution `probe_execution_summary` remain distinct and are not collapsed into one object 7. the Wiki-surface profile treats probes as required where coverage is expected 8. completed probe failures can occur even when GF compilation succeeds 9. deterministic inputs produce deterministic probe outputs and summaries These tests are part of the contract. --- ## 21. Change policy Any change to probe behavior requires contract review if it affects: * probe identity fields * allowed input kinds * expectation semantics * probe analyzer responsibilities * blocked vs failed semantics * `probe_execution_summary` meaning * the ownership split between aggregate `probe_summary` and per-execution `probe_execution_summary` * profile probe policy * required probe asset families If any of these change, this document and any affected higher contract must be updated. No silent probe drift is allowed. --- ## 22. One-line operational summary A probe is an explicit, asset-defined, profile-governed verification unit that executes grammar-surface cases against concrete language targets and emits structured per-execution language-behavior evidence that remains separate from compile evidence and from aggregate artifact-level probe reporting. ================================================================================================ FILE: docs/07_semantik_inventory.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: f664d774efe502e482c26eaa132b51df358e8edc63ce146014df4db98f78af37 CONTENT_BYTES: 17628 ================================================================================================ # SemantiK Inventory ## SemantiK Grammar Surface Auditor **Normative document** This file defines the reviewed SemantiK inventory for the SemantiK Grammar Surface Auditor. Its purpose is to make the default SemantiK grammar-surface selection explicit, reviewable, stable, and enforceable. This document is **normative**. It is not a convenience list and it is not a broad repo map. It defines the reviewed artifact families, include roots, source-kind mappings, and default inclusion rules that SemantiK-specific profiles are allowed to use. If implementation behavior, profile definitions, or future documentation conflict with this file, this file takes precedence unless `docs/00_main_design.md` or `docs/01_scope_contract.md` is intentionally revised and this inventory is updated accordingly. --- ## 1. Purpose of this inventory The SemantiK Grammar Surface Auditor must not rely on free-form repo crawling for its SemantiK-specific behavior. The main design requires the first SemantiK profile to start from a **reviewed inventory** rather than broad directory discovery. The scope contract also requires ambiguous artifacts to default to exclusion until they are explicitly added to the reviewed inventory. This file exists to enforce those two architectural decisions. It defines: * the reviewed artifact families that belong to the SemantiK grammar surface * the default include roots for those artifacts * the allowed source-kind mapping for each inventory family * the profile membership of each family * the exclusion rule for ambiguous or non-reviewed artifacts --- ## 2. Inventory principles The inventory must be interpreted using the following principles. ### 2.1 Reviewed, not crawled SemantiK-specific profiles must start from reviewed artifact families and explicit include roots. They must not discover broad SemantiK ownership by recursively scanning unrelated directories and then attempting to classify everything after the fact. ### 2.2 Explicit source-kind mapping Every inventoried artifact family must map to one of the allowed source kinds: * `gf_source` * `probe_asset` * `grammar_surface_tool` * `linearization_probe` No other source kind may be introduced through this inventory. ### 2.3 Narrow by default If an artifact is not explicitly covered by this inventory, it is excluded from SemantiK-specific default selection. ### 2.4 Primary-responsibility classification Artifacts must be inventoried by primary responsibility, not by proximity, file extension alone, or historical debugging usage. ### 2.5 Profile-owned breadth This inventory defines the reviewed SemantiK surface. Profiles may select subsets of this inventory, but they may not expand beyond it without an inventory update. ### 2.6 Probe identity is inventory-backed `linearization_probe` is an allowed source kind, but it is not a free-form file family. Probe identities must come from reviewed probe assets, especially the probe catalog and related expectation manifests. --- ## 3. What this inventory covers This inventory covers only the SemantiK **grammar surface**. That means it covers reviewed artifacts that directly define, verify, or constrain: * GF grammar realization * shared Wiki or bioframework language surface * concrete Wiki-language behavior * probe-driven language verification * narrowly scoped grammar-facing helper tooling * tightly scoped grammar-surface acceptance assets This inventory does **not** cover runtime, planner, API, renderer, or broad application ownership. --- ## 4. Inventory definitions ### 4.1 Inventory entry An **inventory entry** is a reviewed artifact family or explicitly named artifact group that is allowed to participate in SemantiK-specific profile selection. ### 4.2 Include root An **include root** is a reviewed path root under which inventory selection is allowed to occur. An include root is not permission for unrestricted crawling. Selection within a root must still follow the mapped family rules in this file. ### 4.3 Source-kind mapping A **source-kind mapping** assigns an inventory entry to one of the allowed source kinds supported by the product. ### 4.4 Reviewed artifact family A **reviewed artifact family** is a bounded set of files or tool entry points with a stable grammar-surface role. Examples: * Wiki GF modules * probe manifests * forbidden-literal files * reviewed grammar-facing helper tools ### 4.5 Inventory-backed probe An **inventory-backed probe** is a `linearization_probe` context derived from reviewed probe assets rather than created ad hoc at report time. --- ## 5. Inventory usage rules The implementation must use this inventory in at least the following places: * SemantiK profile definitions * selection roots * source-kind classification * analyzer eligibility * acceptance tests * change-control review This inventory is not optional background documentation. It is part of the executable product boundary. --- ## 6. Default include roots The reviewed default include roots for SemantiK-specific profiles are: * `gf/` * `fixtures/probes/` * approved grammar-surface helper tool locations * tightly scoped grammar-surface acceptance asset locations The presence of an include root does not make all descendants in scope. Only reviewed inventory families defined in this document may be selected from these roots. --- ## 7. Reviewed inventory entries The following inventory entries are approved for the initial SemantiK grammar-surface product. ## 7.1 Native GF grammar surface **Inventory id** * `semantik.gf_surface` **Source kind** * `gf_source` **Include root** * `gf/` **Included artifacts** Included by default when they participate in the SemantiK grammar surface: * `gf/SemantikArchitect.gf` * `gf/WikiI.gf` * `gf/WikiEng.gf` * `gf/WikiFre.gf` * related `gf/Wiki*.gf` files * tightly related shared Wiki or bioframework GF modules required to compile or reason about the same realization path **Inclusion rule** A GF file may be selected from this family only if it directly defines: * the shared Wiki surface * a concrete Wiki language surface * the SemantiK root grammar used for the same grammar-surface path * a tightly related shared GF layer required for that path **Exclusion rule** A GF file under `gf/` is excluded if it does not participate in the reviewed grammar surface relevant to the active profile. **Profiles** * `semantik-grammar-surface` * `semantik-wiki-surface` as a narrower subset **Notes** This family is the primary compiled artifact family of the product. --- ## 7.2 Probe catalog **Inventory id** * `semantik.probes.catalog` **Source kind** * `probe_asset` **Include root** * `fixtures/probes/` **Included artifacts** * `fixtures/probes/probe_catalog.yaml` **Purpose** Defines the reviewed probe identities and the probe cases the auditor is allowed to execute or interpret. **Inclusion rule** The probe catalog is included because it defines what grammar-surface behavior must be verified. **Notes** No free-form probe identities should be treated as profile-default SemantiK probes unless they are represented in the reviewed probe catalog or another explicitly reviewed probe asset family added later. --- ## 7.3 Expected concrete manifests **Inventory id** * `semantik.probes.expected_concretes` **Source kind** * `probe_asset` **Include root** * `fixtures/probes/` **Included artifacts** * `fixtures/probes/expected_concretes.yaml` **Purpose** Defines the expected concrete inventory for reviewed grammar-surface probe behavior. **Inclusion rule** This family is included because the auditor must verify that supported language concretes and probe expectations stay aligned. --- ## 7.4 Required constructor manifests **Inventory id** * `semantik.probes.required_constructors` **Source kind** * `probe_asset` **Include root** * `fixtures/probes/` **Included artifacts** * `fixtures/probes/required_constructors.yaml` **Purpose** Defines constructor families that the SemantiK grammar surface is required to realize or cover under the active profile. **Inclusion rule** This family is included because constructor coverage is part of the grammar-surface verification contract, especially for Wiki, bio, and event realization. --- ## 7.5 Forbidden-literal manifests **Inventory id** * `semantik.probes.forbidden_literals` **Source kind** * `probe_asset` **Include root** * `fixtures/probes/` **Included artifacts** Included by reviewed pattern: * `fixtures/probes/forbidden_literals..yaml` Known initial example: * `fixtures/probes/forbidden_literals.fr.yaml` **Purpose** Defines language-specific literal leakage constraints for probe verification. **Inclusion rule** A forbidden-literal file is included only when it directly encodes language-surface expectations for a reviewed SemantiK probe family. **Notes** This family is especially important for the Wiki-language leakage class of defects where a concrete resolves but still surfaces another language’s literals. --- ## 7.6 Grammar-surface helper tools **Inventory id** * `semantik.tools.grammar_surface` **Source kind** * `grammar_surface_tool` **Include root** * approved grammar-surface helper tool locations **Included tools** Examples of approved reviewed families include: * `compile_pgf` * `visualize_ast` * `eval_bios` and any tightly related grammar-surface helpers whose primary function is to: * compile the reviewed grammar surface * inspect the reviewed grammar surface * verify multilingual grammar-surface outputs **Inclusion rule** A helper tool is included only when its primary responsibility is grammar-surface work. **Exclusion rule** A general-purpose helper, runtime adapter, or broad QA script is excluded even if it mentions GF or languages. **Notes** This inventory family must remain small and explicit. Tool inclusion is by review, not by naming convention alone. --- ## 7.7 Grammar-surface acceptance assets **Inventory id** * `semantik.acceptance.grammar_surface` **Source kind** * `probe_asset` **Include root** * tightly scoped grammar-surface acceptance asset locations **Included artifacts** Known reviewed example: * `docs/testing/EN_FR_bio_acceptance.md` Additional assets may be included only when they materially define expected grammar-surface behavior rather than broad prose discussion. **Purpose** Defines tightly scoped acceptance expectations for reviewed grammar-surface regressions or release checks. **Inclusion rule** An acceptance artifact is included only if it encodes concrete grammar-surface expectations, acceptance evidence, or reviewable behavior constraints for the SemantiK Wiki or bioframework surface. --- ## 7.8 Inventory-backed linearization probes **Inventory id** * `semantik.probes.linearization` **Source kind** * `linearization_probe` **Backing assets** This source kind is backed by reviewed probe assets, including: * the probe catalog * expected concrete manifests * required constructor manifests * forbidden-literal manifests * tightly scoped grammar-surface acceptance assets when they define probe expectations **Purpose** Represents executed or evaluated probe cases against the reviewed grammar surface. **Inclusion rule** A `linearization_probe` may appear in a run only if its identity is derived from reviewed inventory-backed probe definitions. **Exclusion rule** Ad hoc probe execution contexts must not silently become part of profile-default SemantiK inventory behavior. --- ## 8. Initial profile mapping This inventory is the reviewed source of truth for SemantiK-specific profile breadth. ### 8.1 `semantik-grammar-surface` This profile may include: * the full `semantik.gf_surface` family * all reviewed `probe_asset` families in `fixtures/probes/` * reviewed grammar-surface helper tools * tightly scoped grammar-surface acceptance assets * inventory-backed `linearization_probe` contexts derived from those assets ### 8.2 `semantik-wiki-surface` This profile must be a narrower subset of the same inventory. It may include only artifacts participating in the Wiki or bioframework realization path, including: * `gf/WikiI.gf` * `gf/WikiEng.gf` * `gf/WikiFre.gf` * related `gf/Wiki*.gf` files * tightly related shared Wiki or bioframework GF modules * Wiki-specific probe assets * forbidden-literal files * required-constructor manifests * reviewed Wiki-surface helper tools * tightly scoped Wiki acceptance assets ### 8.3 `pure-gf` `pure-gf` does not depend on this SemantiK inventory for its generic behavior. This inventory applies only when SemantiK-specific profile behavior is enabled. --- ## 9. Inventory exclusion rules The following artifacts are excluded from this inventory unless this file is intentionally revised: * runtime adapters such as `gf_wrapper.py`, `gf_engine.py`, or similar runtime bridge code * planner or routing code * API contract and response-shaping code * renderer or debug-metadata code * general application logic * broad whole-system tests * general-purpose helper tooling * artifacts that are merely adjacent to the grammar surface * artifacts whose role is ambiguous and not yet reviewed The direction of ambiguity is always **exclude**. --- ## 10. Ambiguous artifact rule When an artifact is ambiguous, classify it by primary responsibility using this order: 1. If it directly defines grammar realization, include it as `gf_source`. 2. If it directly defines what grammar behavior must be verified, include it as `probe_asset`. 3. If it directly compiles, inspects, or verifies the grammar surface, include it as `grammar_surface_tool`. 4. If it represents an inventory-backed executed probe, include it as `linearization_probe`. 5. Otherwise, exclude it. No artifact may be included merely because it is useful in a debugging workflow. --- ## 11. Inventory entry requirements Any future inventory addition must define at least: * `inventory_id` * artifact family description * `source_kind` * include root * inclusion rule * exclusion rule when needed * profile membership * rationale for grammar-surface ownership If these are not defined, the addition is incomplete and must not be treated as part of the reviewed SemantiK inventory. --- ## 12. Required implementation behavior The implementation must satisfy the following requirements: 1. SemantiK-specific profile selection must be derived from reviewed inventory families rather than broad repo crawling. 2. Source-kind classification must remain consistent with the inventory mappings in this file. 3. Non-reviewed artifacts under an approved root must still be excluded. 4. `linearization_probe` identities must be derived from reviewed probe assets. 5. Helper-tool inclusion must remain explicit and reviewable. 6. Reporting must not imply ownership of non-inventoried SemantiK surfaces. --- ## 13. Required tests for inventory integrity The implementation must include tests that prove this inventory is being respected. At minimum: 1. a test that reviewed Wiki GF files are selected by the appropriate SemantiK profile 2. a test that reviewed probe assets under `fixtures/probes/` are selected and correctly classified 3. a test that `docs/testing/EN_FR_bio_acceptance.md` is included only when grammar-surface acceptance assets are enabled 4. a test that non-reviewed files under `gf/` or other approved roots are excluded 5. a test that runtime adapters are excluded even when located near grammar artifacts 6. a test that helper tools are included only when explicitly inventoried 7. a test that `linearization_probe` contexts originate from reviewed probe assets rather than ad hoc defaults These tests are part of the product contract. --- ## 14. Relationship to profiles, acceptance, and change control This inventory does not replace profile definitions, acceptance contracts, or change control. It constrains them. That means: * profiles must select from this reviewed inventory * acceptance behavior must be explainable in terms of inventoried artifacts * change-control review must update this inventory whenever SemantiK grammar-surface ownership changes materially No SemantiK profile broadening is valid unless this inventory is updated first or in the same change set. --- ## 15. Change triggers This inventory must be updated when any of the following occur: * a new `Wiki*.gf` language concrete is added to the reviewed surface * a new shared GF module becomes part of the reviewed Wiki or bioframework realization path * a new probe manifest family is introduced * a new forbidden-literal or expectation asset family is introduced * a new grammar-surface helper tool is approved * a grammar-surface acceptance asset becomes normative for release or regression checks * a profile begins selecting artifacts not currently covered by this file No silent inventory drift is allowed. --- ## 16. Precedence Precedence order for SemantiK inventory behavior is: 1. `docs/00_main_design.md` 2. `docs/01_scope_contract.md` 3. `docs/07_semantik_inventory.md` 4. profile definitions 5. analyzer and report contracts 6. acceptance contract 7. implementation details If implementation or profile behavior conflicts with this inventory, the implementation is architecturally incorrect unless the higher-order contracts are intentionally revised. --- ## 17. One-line operational summary The SemantiK inventory is the reviewed, explicit, profile-owned map of the SemantiK grammar surface: GF grammars, probe assets, narrowly scoped grammar-facing tools, and inventory-backed probes only. ================================================================================================ FILE: docs/08_acceptance_contract.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 89ef63e7305725d2b5e7fe3db1df649401fb4d3fa90182a5ea1014b58950fbaa CONTENT_BYTES: 19318 ================================================================================================ # Acceptance Contract ## SemantiK Grammar Surface Auditor **Normative document** This file defines the acceptance contract for the SemantiK Grammar Surface Auditor. Its purpose is to make acceptance criteria, acceptance evidence, and release-gate expectations explicit, stable, and reviewable so the product does not drift into informal sign-off, partial contract compliance, or silent weakening of grammar-surface guarantees. This document is **normative**. Any implementation, release candidate, or materially changed profile/configuration of the auditor must satisfy this contract before it is considered accepted. If implementation behavior conflicts with this contract, this contract takes precedence unless `docs/00_main_design.md` is intentionally revised and this file is updated accordingly. --- ## 1. Purpose of this contract The SemantiK Grammar Surface Auditor is accepted only when there is explicit evidence that it satisfies the grammar-surface product definition and the contracts that govern scope, analyzers, reports, profiles, probes, and inventories. This contract exists to prevent five failure modes: 1. informal “looks good” approval without contract-backed evidence 2. acceptance based on compile success alone 3. silent weakening of probe-backed language-surface verification 4. partial implementation being treated as a complete grammar-surface audit 5. release drift where contracts remain nominally present but are no longer enforced by tests and run artifacts Acceptance in this document is therefore not a general quality impression. It is a bounded, evidence-backed decision that the implementation satisfies the required grammar-surface obligations. --- ## 2. Acceptance definition A candidate implementation is **accepted** only when all required acceptance gates defined by this document have passed for the affected profiles, source kinds, analyzers, report outputs, schemas, fixtures, and probe paths. Acceptance applies to: * implementation changes * profile definitions * analyzer registration and behavior * report generation behavior * schema-backed outputs * rule packs * probe assets and fixtures * reviewed SemantiK inventory changes Acceptance does **not** mean: * whole-system runtime correctness * planner correctness * API correctness * renderer correctness * production-language perfection * end-to-end SemantiK validation This contract accepts only the grammar-surface auditor within its defined product boundary. --- ## 3. Acceptance principles 1. Acceptance is evidence-based, not impression-based. 2. Acceptance is contract-first, not implementation-first. 3. Acceptance must preserve scope boundaries. 4. Acceptance must preserve static, compile, and probe separation. 5. Acceptance must be deterministic and regression-testable. 6. Acceptance must be profile-aware. 7. Acceptance must include both positive and negative evidence. 8. Acceptance must not be granted when required evidence is blocked, missing, or silently downgraded. --- ## 4. Acceptance object model Acceptance is evaluated at the level of an **acceptance candidate**. An acceptance candidate may be: * the product implementation as a whole * a specific release candidate * a materially changed profile set * a materially changed analyzer set * a materially changed report schema or report generator * a materially changed probe fixture set * a materially changed SemantiK inventory or source-kind mapping The candidate under review determines which gates and regression suites are mandatory, but no candidate may bypass the scope, analyzer, report, or profile contracts. --- ## 5. Required evidence families An acceptance decision must be based on explicit evidence from the following families. ### 5.1 Contract alignment evidence There must be evidence that the implementation remains aligned with: * `docs/01_scope_contract.md` * `docs/02_analyzer_contract.md` * `docs/03_report_contract.md` * `docs/04_profiles.md` * `docs/05_rulepacks.md` * `docs/06_probe_spec.md` * `docs/07_semantik_inventory.md` Contract alignment may be shown through tests, schema validation, deterministic fixture runs, and reviewable configuration/state. ### 5.2 Automated test evidence Required acceptance checks must be encoded in executable tests. Manual review may supplement acceptance, but it may not replace required automated checks. ### 5.3 Representative run evidence Acceptance must include representative auditor runs whose outputs can be inspected and compared against expected outcomes. These runs must include both: * runs expected to be clean * runs expected to surface known issue classes ### 5.4 Schema validation evidence Where a required schema exists, the corresponding output must validate against it. ### 5.5 Golden output evidence At least representative `summary.json` outputs must be validated through golden or equivalent stable comparison tests. ### 5.6 Inventory and fixture evidence For SemantiK-specific profiles, acceptance must demonstrate that reviewed inventories and probe assets match the intended grammar surface rather than relying on broad repo crawling or undocumented assumptions. --- ## 6. Mandatory acceptance dimensions Every accepted candidate must satisfy all applicable dimensions in this section. ### 6.1 Scope integrity The candidate must respect the product boundary. Required evidence includes proof that: * SemantiK grammar-surface profiles select only in-scope artifact families * runtime adapters and broader application files remain excluded * non-`.gf` runtime files are never treated as GF compile targets * ambiguous files default to exclusion until explicitly admitted by contract-owned inventory or profile rules A candidate that broadens scope by implementation convenience is not acceptable. ### 6.2 Profile integrity The candidate must satisfy profile behavior as a normative operating contract. Required evidence includes proof that: * `pure-gf` remains bounded to GF-source behavior * `semantik-grammar-surface` selects reviewed grammar-surface artifacts only * `semantik-wiki-surface` selects Wiki-surface artifacts and relevant probe assets * single-file mode remains constrained by profile scope * profile-required analyzers and probe paths are actually available where required * invalid profile states are rejected or surfaced explicitly rather than silently degraded ### 6.3 Analyzer integrity The candidate must preserve analyzer registration, analyzer/result shape, source-kind compatibility, and failure semantics. Required evidence includes proof that: * analyzers reject unsupported source kinds * analyzers emit valid structured results * blocked prerequisites produce `blocked` or `skipped`, not fabricated findings * analyzer failures remain distinct from audit findings * analyzer outputs remain compatible with artifact aggregation and acceptance checks ### 6.4 Report integrity The candidate must preserve the shared report contract. Required evidence includes proof that: * `summary.json` remains the canonical machine-readable output * required top-level fields remain present * artifact result fields remain valid * enum values remain valid * artifact and run aggregation remain deterministic * compile summaries and probe summaries remain semantically separate * report wording does not imply runtime or whole-system guarantees ### 6.5 Schema integrity The candidate must preserve schema-backed validity. Required evidence includes proof that: * `summary.json` validates against `schemas/report.schema.json` when that schema exists * probe or fixture catalogs validate against their corresponding schemas when those schemas exist * additive changes do not silently change the meaning of existing fields ### 6.6 Rule-pack and finding integrity The candidate must preserve stable, reviewable rule-driven evidence. Required evidence includes proof that: * rule ids remain stable and documented * findings use only allowed severity values * findings use only allowed suggested-fix kinds * SemantiK-specific issue classes are emitted as structured findings rather than hidden in logs ### 6.7 Probe-asset integrity The candidate must preserve the verification surface for grammar behavior. Required evidence includes proof that: * probe catalogs are structurally valid * expected concrete manifests are valid and complete for the reviewed inventory * required constructor manifests are valid and complete for the reviewed inventory * forbidden-literal lists are valid and language-specific where needed ### 6.8 Probe-path integrity Where probe behavior is enabled or required, the candidate must preserve probe-backed language verification. Required evidence includes proof that: * required concretes can be resolved where expected * probe execution is blocked only when genuine prerequisites are missing * forbidden-literal checks operate on observed outputs rather than static approximations * cross-language comparisons are used where defined by profile or fixture * probe failures are reported as probe evidence rather than compile evidence ### 6.9 Single-file diagnostic integrity The candidate must preserve strong single-file diagnosis within profile scope. Required evidence includes proof that: * single-file GF diagnosis still supports compile and static evidence * single-file probe/expectation assets still produce meaningful asset findings * single-file mode never bypasses scope restrictions ### 6.10 Backward-compatibility integrity for `pure-gf` The candidate must preserve the existing useful behavior of the GF-specialist core. Required evidence includes proof that `pure-gf` retains expected compile, scan, classification, diffing, and reporting behavior without SemantiK-specific scope leakage. --- ## 7. Required acceptance gates by profile Acceptance must be applied per affected profile. ### 7.1 `pure-gf` A candidate affecting `pure-gf` is accepted only if all of the following are true: 1. only `gf_source` artifacts are selected 2. compile and GF-static analysis still work for real `.gf` targets 3. report fields and aggregation remain contract-valid 4. SemantiK-specific runtime files are not selected 5. SemantiK probe analyzers are not enabled by default 6. representative golden outputs remain valid ### 7.2 `semantik-grammar-surface` A candidate affecting `semantik-grammar-surface` is accepted only if all of the following are true: 1. reviewed grammar-surface artifacts are selected deterministically 2. runtime/application artifacts remain excluded 3. probe assets are validated as first-class verification artifacts 4. report outputs distinguish static, compile, and probe evidence 5. schema-backed outputs validate where schemas exist 6. representative grammar-surface fixture runs match expected outcomes ### 7.3 `semantik-wiki-surface` A candidate affecting `semantik-wiki-surface` is accepted only if all of the following are true: 1. required probe analyzers are available and functioning 2. probe-driven checks can verify expected concrete presence and forbidden literal leakage 3. the French Wiki-surface leakage class is represented by fixture and detected automatically 4. shared-layer English literals in a neutral layer produce structured findings 5. missing required bio/event constructor coverage produces a structured finding or probe failure 6. a run is not presented as a full Wiki-surface audit when required probe execution was unavailable --- ## 8. Required acceptance test suites The implementation must include acceptance tests that cover the following suites. ### 8.1 Scope acceptance suite At minimum, this suite must prove: 1. `semantik-wiki-surface` selects `gf/Wiki*.gf` and relevant probe assets 2. runtime adapter files are excluded from grammar-surface profiles 3. non-`.gf` runtime files are never sent through GF compilation 4. grammar-surface tools are included only when explicitly mapped 5. ambiguous files default to exclusion 6. report output does not claim runtime correctness ### 8.2 Profile acceptance suite At minimum, this suite must prove: 1. `pure-gf` selects only `gf_source` artifacts 2. `semantik-grammar-surface` selects only reviewed grammar-surface artifacts 3. `semantik-wiki-surface` selects Wiki-surface artifacts and relevant probe assets 4. runtime or application files are excluded from all SemantiK profiles 5. `pure-gf` does not enable SemantiK probe analyzers by default 6. `semantik-wiki-surface` requires its probe path where coverage is expected 7. single-file mode remains constrained by profile scope 8. report semantics remain stable across profiles ### 8.3 Analyzer acceptance suite At minimum, this suite must prove: 1. analyzers reject unsupported source kinds 2. analyzers emit valid structured results 3. analyzers emit findings in the required schema 4. analyzers use only allowed severity values 5. blocked prerequisites produce `blocked` or `skipped`, not fabricated findings 6. deterministic input produces deterministic output 7. analyzer registration matches profile availability 8. analyzer output can be consumed by the report layer without special handling ### 8.4 Report acceptance suite At minimum, this suite must prove: 1. required top-level run fields exist 2. artifact result fields are valid 3. enum values are valid 4. finding objects are valid 5. compile/probe separation is preserved 6. aggregation behavior is stable 7. diff behavior remains compatible 8. representative profiles have golden `summary.json` coverage ### 8.5 Probe-asset acceptance suite At minimum, this suite must prove: 1. valid probe catalogs are accepted 2. malformed probe catalogs are rejected or surfaced as asset issues 3. expected concrete manifests are validated against the reviewed inventory 4. required constructor manifests are validated against the reviewed inventory 5. forbidden-literal lists are structurally valid and language-scoped as intended ### 8.6 Probe execution acceptance suite At minimum, this suite must prove: 1. required concretes are checked through probe execution 2. forbidden literals are checked on observed outputs 3. cross-language comparison works where defined 4. blocked probe prerequisites yield blocked execution rather than fabricated success 5. probe failures surface as `probe_issue` or `mixed`, not as compile-only outcomes --- ## 9. Required representative fixtures Acceptance must include fixtures that cover the issue classes the product explicitly claims to detect. At minimum, the fixture set must include: 1. a known French Wiki-surface leakage fixture 2. a shared-layer English literal leakage fixture 3. a missing bio/event constructor coverage fixture 4. a missing expected concrete fixture 5. a malformed probe asset fixture 6. a blocked probe prerequisite fixture 7. at least one clean representative run fixture for each supported profile under acceptance The fixture set may expand over time, but it must not shrink in a way that weakens claimed product coverage without coordinated contract review. --- ## 10. Acceptance of expected failures Acceptance does not require every representative run to have `run_status = clean`. Some acceptance fixtures are intentionally negative. Their purpose is to prove that the auditor detects and classifies the issue classes it claims to detect. A negative fixture run is accepted only when: * the expected issue is detected * the expected status or diagnostic class is produced * the expected structured findings are present * the result is stable and reviewable A clean fixture run is accepted only when no unexpected warning or error findings appear. --- ## 11. Blocking and missing-evidence rule Blocked or missing evidence is not acceptable when the blocked path is required by the affected profile or acceptance gate. That means: * a required probe path may not be treated as optional during acceptance * a missing schema validation step may not be ignored when the schema exists * a missing required analyzer may not be silently downgraded to a weaker audit * incomplete representative coverage may not be described as full acceptance If a gate cannot be evaluated because required evidence is missing, the candidate is not accepted. --- ## 12. Acceptance decision rule An acceptance candidate is accepted only when all required gates for the affected surface have passed. The decision rule is: 1. **accepted** when all required gates pass with complete evidence 2. **not accepted** when any required gate fails 3. **not accepted** when any required evidence family is missing for the affected surface 4. **not accepted** when blocked prerequisites prevent evaluation of a required gate This contract intentionally does not define a softer acceptance state that can hide incomplete implementation under narrative approval. --- ## 13. Required acceptance artifacts An acceptance review must produce reviewable artifacts. At minimum, these must include: * test results for the required suites * representative run outputs * `summary.json` for representative runs * human-readable derived outputs for representative runs * schema-validation results where schemas exist * a bounded record of any accepted contract update accompanying the change Acceptance evidence must be reviewable after the fact. It must not exist only in transient console output. --- ## 14. Re-acceptance triggers Re-acceptance is required when a change materially affects any of the following: * scope behavior * profile selection behavior * analyzer registration or semantics * rule ids or rule namespaces * report fields, enums, or aggregation semantics * schema shapes or schema meanings * probe fixtures, probe catalogs, or expectation manifests * reviewed SemantiK inventory * required probe behavior A materially affected surface must be re-accepted for all impacted profiles and gates. --- ## 15. Precedence and relationship to other contracts This contract depends on the main design and the lower-level product contracts. Precedence order: 1. `docs/00_main_design.md` 2. `docs/01_scope_contract.md` 3. `docs/02_analyzer_contract.md` 4. `docs/03_report_contract.md` 5. `docs/04_profiles.md` 6. `docs/05_rulepacks.md` 7. `docs/06_probe_spec.md` 8. `docs/07_semantik_inventory.md` 9. `docs/08_acceptance_contract.md` 10. implementation details `docs/08_acceptance_contract.md` does not redefine scope, analyzer semantics, report semantics, or profile semantics. It defines the evidence required to accept that those contracts are being satisfied. --- ## 16. Required contract update linkage Any change that materially affects acceptance behavior must update this file and any governing contract whose meaning is changed. At minimum, coordinated updates are required when: * acceptance gates change * required suites change * representative fixture obligations change * a profile’s required acceptance evidence changes * schema-backed validation obligations change No silent acceptance drift is allowed. --- ## 17. One-line operational summary The acceptance contract defines the evidence, gates, fixtures, and decision rules required to approve the SemantiK Grammar Surface Auditor as a grammar-surface product without silent weakening of scope, probes, schemas, or report semantics. ================================================================================================ FILE: docs/09_change_control.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 94dd862dae55308fbc9e3e585f223eca38d3814d04e18ea8468f4b4e7dd92970 CONTENT_BYTES: 19498 ================================================================================================ # Change Control ## SemantiK Grammar Surface Auditor **Normative document** This file defines the change-control contract for the SemantiK Grammar Surface Auditor. Its purpose is to make architectural change, contract revision, compatibility review, and required follow-up updates explicit and enforceable so the product does not drift through undocumented implementation changes. This document is **normative**. Any material change to the auditor, its contracts, its schemas, its fixtures, its inventories, its acceptance gates, or its profile-owned behavior must conform to this file. If implementation behavior conflicts with this contract, this contract takes precedence for change procedure and update requirements unless `docs/00_main_design.md` is intentionally revised and this file is updated accordingly. --- ## 1. Purpose of this contract The SemantiK Grammar Surface Auditor is a contract-driven product. That means the implementation is not allowed to evolve by silent behavior drift, convenience exceptions, or undocumented re-interpretation of the grammar surface. This contract exists to prevent five failure modes: 1. implementation-level broadening without scope review 2. analyzer or profile drift without contract updates 3. report or schema drift without compatibility review 4. fixture changes that silently weaken probe rigor 5. inconsistent updates across documentation, schemas, inventory, acceptance, tests, and code This file governs how change is classified, what follow-up updates are mandatory, and what compatibility claims are allowed. --- ## 2. Change-control principles 1. No silent drift is allowed. 2. No implementation-level broadening is allowed without corresponding contract updates. 3. No profile may change meaning by undocumented analyzer, fixture, or inventory changes. 4. No schema may change meaning without an explicit compatibility review. 5. No probe or acceptance asset may be weakened without visible contract review. 6. Editorial clarification is allowed, but it must not silently alter product semantics. 7. When in doubt, the required direction is explicit review and synchronized updates. 8. Ambiguity must resolve toward preserving the existing boundary, not broadening it. 9. Probe reporting, report semantics, schema semantics, and acceptance behavior must remain synchronized. 10. A document that repeats a precedence ladder must repeat the canonical ladder in this file verbatim. --- ## 3. What this contract governs This file governs changes to all normative and operational layers of the product, including: * product boundary * source kinds * profiles * analyzer behavior * rule packs and rule namespaces * probe specification * SemantiK inventory * report semantics * schemas * fixtures * acceptance gates * implementation behavior that changes any of the above This file does not redefine the technical meaning of scope, analyzers, reports, probes, inventories, or profiles. Those meanings remain owned by their respective contracts. This file defines the required procedure when those meanings change or are at risk of changing. --- ## 4. Authority and precedence This file is procedural. It does not authorize the implementation to bypass existing technical contracts. The canonical precedence order for the SemantiK Grammar Surface Auditor is: 1. `docs/00_main_design.md` 2. `docs/01_scope_contract.md` 3. `docs/02_analyzer_contract.md` 4. `docs/03_report_contract.md` 5. `docs/04_profiles.md` 6. `docs/05_rulepacks.md` 7. `docs/06_probe_spec.md` 8. `docs/07_semantik_inventory.md` 9. `docs/08_acceptance_contract.md` 10. `docs/09_change_control.md` 11. implementation details, tests, and convenience tooling The following rules apply: 1. `docs/00_main_design.md` remains the top-level design authority. 2. `docs/01_scope_contract.md` remains authoritative for product boundary. 3. `docs/02_analyzer_contract.md` remains authoritative for analyzer semantics. 4. `docs/03_report_contract.md` remains authoritative for result and report semantics. 5. `docs/04_profiles.md` remains authoritative for profile semantics. 6. `docs/05_rulepacks.md` remains authoritative for stable rule ids and rule-pack meaning. 7. `docs/06_probe_spec.md` remains authoritative for probe structure, probe behavior, and per-execution probe evidence. 8. `docs/07_semantik_inventory.md` remains authoritative for reviewed SemantiK inventory and source mapping. 9. `docs/08_acceptance_contract.md` remains authoritative for release and acceptance gates. 10. `docs/09_change_control.md` defines when and how coordinated revision across those files is mandatory. Any normative document that includes a precedence section must reproduce the canonical precedence order in this section verbatim. If a change would contradict a higher-precedence technical contract, the change is invalid until that technical contract is intentionally revised. --- ## 5. Definition of a controlled change A **controlled change** is a change that: 1. is classified explicitly 2. states whether it is editorial, compatible, or breaking 3. identifies all affected contracts, schemas, fixtures, inventories, and tests 4. updates all required companion artifacts 5. preserves or intentionally revises acceptance behavior 6. leaves a reviewable audit trail in docs and implementation A change that modifies behavior without satisfying these conditions is uncontrolled and therefore non-compliant. --- ## 6. Change classes Every material change must be classified into exactly one primary change class. ### 6.1 Editorial clarification An editorial clarification improves wording, structure, examples, or explanation without changing: * scope * required fields * allowed enum values * analyzer behavior * rule meaning * probe semantics * profile semantics * schema meaning * acceptance behavior Editorial clarification does not require a compatibility change label, but it must remain truly non-semantic. ### 6.2 Compatible additive change A compatible additive change adds capability without changing the meaning of existing contracts. Examples: * adding a new documented rule id * adding a new optional schema field that does not alter existing semantics * adding new probe cases under an existing probe contract * adding a reviewed inventory entry within the existing scope boundary * adding a new grammar-surface helper tool mapping within existing contract rules This class requires synchronized updates where the new capability is documented, validated, and tested. ### 6.3 Compatible behavioral tightening A compatible behavioral tightening makes the product stricter or more complete while preserving existing contract meaning. Examples: * strengthening acceptance coverage * adding missing required tests already implied by contract * extending probe coverage for an already-supported language * improving detection for an already-documented rule family * marking a previously-enabled analyzer as required when the profile contract is revised accordingly This class requires explicit review because it may change pass/fail outcomes even if it does not redefine product scope. ### 6.4 Breaking contract change A breaking contract change alters the meaning of an existing contract, schema, field, enum, rule, probe behavior, profile behavior, or evidence model. Examples: * changing the meaning of `artifact_status` * changing allowed severity values * changing probe outcome semantics * renaming or removing stable rule ids * changing required analyzer behavior * changing schema field meaning or nullability * changing profile requirements in a way that invalidates existing expectations * splitting aggregate probe reporting and per-execution probe reporting into different fields, such as keeping aggregate counts in `probe_summary` and moving per-execution detail to `probe_execution_summary` This class requires explicit contract revision, compatibility review, test revision, and acceptance review. ### 6.5 Scope boundary change A scope boundary change expands or narrows what the product is allowed to audit. Examples: * adding a new included artifact family * removing an existing included artifact family * introducing a new source kind * allowing new categories of helper tools * broadening toward runtime, planner, API, renderer, or whole-system concerns This is the most sensitive change class. It requires revision of the main design or explicit consistency with it, followed by synchronized updates to scope, profiles, inventory, and acceptance. --- ## 7. Compatibility labels Every non-editorial change must be labeled as one of the following: * `patch` * `minor` * `major` ### 7.1 `patch` Use `patch` only when the change is editorial or implementation-internal and does not change visible contract behavior. ### 7.2 `minor` Use `minor` for compatible additive change or compatible behavioral tightening that preserves existing contract meaning. ### 7.3 `major` Use `major` for any breaking contract change or scope boundary change. A change must not be labeled `minor` merely because it is convenient to merge. The label must reflect the effect on contract consumers, profile semantics, acceptance outcomes, and audit interpretation. --- ## 8. Mandatory coordinated updates by change trigger A controlled change is not complete until all required companion artifacts are updated. ### 8.1 Scope change trigger If a change affects included artifact families, excluded artifact families, allowed source kinds, or grammar-surface breadth, the following must be reviewed and updated: * `docs/00_main_design.md` * `docs/01_scope_contract.md` * `docs/04_profiles.md` * `docs/07_semantik_inventory.md` * `docs/08_acceptance_contract.md` * `docs/09_change_control.md` If new rule families, probe assets, or schemas are introduced, update the corresponding technical contracts as well. ### 8.2 Analyzer change trigger If a change affects analyzer ids, analyzer categories, supported source kinds, execution semantics, required fields, profile availability, or summary meaning, the following must be reviewed and updated: * `docs/02_analyzer_contract.md` * `docs/04_profiles.md` * `docs/05_rulepacks.md` * `docs/08_acceptance_contract.md` * `docs/09_change_control.md` If analyzer outputs affect report semantics or schemas, update those too. ### 8.3 Report or schema change trigger If a change affects report fields, enums, aggregation semantics, nullability, diff behavior, or validation expectations, the following must be reviewed and updated: * `docs/00_main_design.md` * `docs/03_report_contract.md` * `schemas/report.schema.json` * `docs/08_acceptance_contract.md` * `docs/09_change_control.md` If the change affects probe-reporting structure, blocked semantics, or the meaning of probe evidence fields, the following must also be reviewed and updated: * `docs/06_probe_spec.md` * related probe fixtures and validation expectations If `schemas/report.schema.json` exists, validation expectations must remain explicit and current. ### 8.4 Profile change trigger If a change affects profile ids, source-kind inclusion, required analyzers, disabled analyzers, probe policy, intended use, or non-goals, the following must be reviewed and updated: * `docs/04_profiles.md` * `docs/07_semantik_inventory.md` * `docs/08_acceptance_contract.md` * `docs/09_change_control.md` If the profile change alters analyzer behavior, rule packs, or probe behavior, update those contracts too. ### 8.5 Rule-pack change trigger If a change affects rule ids, rule namespaces, severity expectations, rule meaning, or profile-owned rule-pack activation, the following must be reviewed and updated: * `docs/05_rulepacks.md` * `docs/02_analyzer_contract.md` * `docs/04_profiles.md` * `docs/08_acceptance_contract.md` * `docs/09_change_control.md` Stable rule ids must not be reinterpreted silently. ### 8.6 Probe change trigger If a change affects probe input shape, probe identity, expected outcomes, forbidden-literal behavior, cross-language checks, required constructor expectations, or per-execution probe evidence shape, the following must be reviewed and updated: * `docs/00_main_design.md` * `docs/03_report_contract.md` * `docs/06_probe_spec.md` * `schemas/report.schema.json` * `schemas/probe_catalog.schema.json` * `fixtures/probes/probe_catalog.yaml` * `fixtures/probes/expected_concretes.yaml` * `fixtures/probes/required_constructors.yaml` * `fixtures/probes/forbidden_literals.fr.yaml` * `docs/08_acceptance_contract.md` * `docs/09_change_control.md` Probe rigor must not be weakened by fixture edits alone. ### 8.7 Inventory change trigger If a change affects which reviewed artifacts belong to the SemantiK grammar surface, the following must be reviewed and updated: * `docs/07_semantik_inventory.md` * `docs/04_profiles.md` * `docs/08_acceptance_contract.md` * `docs/09_change_control.md` If the inventory change reflects a scope change rather than a reviewed addition inside current scope, update the scope contract as well. ### 8.8 Acceptance change trigger If a change affects what counts as an acceptable run, required validation, golden fixtures, release gates, or failure thresholds, the following must be reviewed and updated: * `docs/08_acceptance_contract.md` * the relevant technical contract that justifies the gate * relevant schemas and fixtures * relevant report or probe contracts * test expectations * `docs/09_change_control.md` Acceptance policy must derive from the contracts, not from convenience. --- ## 9. Required review questions Every material change must be reviewed against the following questions: 1. Does the change broaden or narrow the grammar-surface boundary? 2. Does the change alter profile behavior or analyzer availability? 3. Does the change alter report meaning, schema meaning, or diff behavior? 4. Does the change alter probe rigor, forbidden-literal coverage, constructor expectations, or per-execution probe evidence shape? 5. Does the change add, remove, or reinterpret stable rule ids? 6. Does the change require new inventory review? 7. Does the change alter acceptance outcomes or release gating? 8. Does the change require a compatibility label above `patch`? 9. Does the change require schema revision or fixture revision? 10. Does the change require new or updated contract tests? If any answer is yes, the corresponding companion artifacts must be updated before the change is considered complete. --- ## 10. Forbidden change patterns The following change patterns are explicitly forbidden: * broadening scope through implementation alone * adding undocumented analyzers * changing profile meaning through hidden toggles * changing rule meaning without updating rule-pack documentation * weakening probe fixtures without visible probe-contract review * changing schema meaning without versioning review * changing report semantics across profiles * changing aggregate probe reporting and per-execution probe reporting independently * allowing ambiguous artifacts to enter scope by convenience * silently reclassifying runtime artifacts as grammar-surface artifacts * merging breaking behavior under a compatible change label These are architectural violations even if the code appears to function. --- ## 11. Required validation after change A controlled change must leave the product in a validated state. At minimum, post-change validation must include the relevant subset of: 1. contract tests for the affected document or component 2. profile tests for affected selection behavior 3. analyzer tests for affected analyzer semantics 4. schema validation tests for affected machine-readable outputs 5. fixture validation tests for affected probe assets 6. acceptance tests for affected release gates 7. golden output refresh and review when report semantics or expected results changed 8. explicit review that the product still makes only grammar-surface claims 9. explicit review that aggregate probe reporting, per-execution probe evidence, and acceptance behavior remain synchronized Validation must be proportional to the change class. A `major` change requires broader revalidation than a `patch` change. --- ## 12. Change review record requirements Every `minor` or `major` change must leave a reviewable record that states: * change summary * primary change class * compatibility label * affected contracts * affected schemas * affected fixtures * affected inventories * affected tests * acceptance impact * migration or consumer impact when applicable This record may live in commit history, pull-request description, or equivalent review artifacts, but it must be explicit. --- ## 13. Migration expectations for breaking change A `major` change must include a migration path or explicit break statement. That statement must identify at least: * what changed * why the old interpretation is no longer valid * which contracts or schemas were revised * which fixtures, inventories, or tests must be updated * whether old golden outputs or downstream consumers must be regenerated A breaking change without migration guidance is incomplete. --- ## 14. Relationship to implementation Implementation details may evolve freely only while remaining inside the current contracts. The following are not sufficient justifications for semantic change: * cleaner code * easier implementation * fewer conditionals * reduced fixture maintenance * temporary test convenience * local repo realities If implementation convenience conflicts with contract meaning, the implementation must change or the contract must be intentionally revised through controlled change. --- ## 15. Required tests for change control itself The implementation and documentation set must include checks that make uncontrolled drift harder. At minimum, the product must include review or test coverage for: 1. scope changes requiring scope/profile/inventory/acceptance updates 2. analyzer changes requiring analyzer and related contract review 3. profile changes requiring profile and acceptance review 4. report changes requiring schema and validation review 5. probe changes requiring probe-contract, report-contract, and fixture review 6. breaking changes requiring explicit compatibility labeling 7. unchanged profile semantics preserving report-field meaning 8. contract-governed artifacts remaining synchronized 9. precedence sections matching the canonical ladder in this document 10. aggregate probe reporting and per-execution probe evidence remaining distinct and synchronized These checks may be implemented through tests, lint rules, review templates, or release gates, but they must be real enforcement mechanisms. --- ## 16. Operational decision rule When a proposed change is ambiguous, use the following rule: 1. preserve the existing product boundary 2. preserve the existing meaning of stable contracts 3. require explicit review for any semantic broadening, tightening, or reinterpretation 4. update every affected companion artifact before treating the change as complete The default direction of ambiguity is controlled preservation, not silent expansion. --- ## 17. One-line operational summary Change in the SemantiK Grammar Surface Auditor is valid only when it is explicitly classified, compatibility-reviewed, synchronized across the affected contracts, schemas, fixtures, inventory, and acceptance gates, and never allowed to drift silently through implementation alone. ================================================================================================ FILE: docs/10_gui_contract.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: c84b37d357fb31fa061df7775b31c1a0873e1cc2e710b50463f90f88e2044fd1 CONTENT_BYTES: 17935 ================================================================================================ # GUI Contract ## SemantiK Grammar Surface Auditor **Normative document** This file defines the GUI contract for the SemantiK Grammar Surface Auditor. Its purpose is to make the GUI an explicit, reviewable, and bounded operator surface over the documented grammar-surface contracts so the product does not drift into ad hoc selection logic, silent profile weakening, ambiguous probe behavior, or report reinterpretation. This document is **normative**. Any GUI implementation of the auditor must conform to this contract. The GUI is subordinate to the product boundary, analyzer, report, profile, probe, inventory, acceptance, and change-control contracts. It must render those contracts faithfully. It must not redefine them. If GUI implementation behavior conflicts with a higher-order normative contract, the higher-order contract takes precedence and the GUI is architecturally incorrect until updated. --- ## 1. Purpose of this contract The SemantiK Grammar Surface Auditor may be operated through a GUI. That GUI is not a separate product. It is a bounded operator surface for the same grammar-surface auditor defined by the existing contracts. This contract exists to prevent six failure modes: 1. a GUI broadening the product into runtime, planner, API, or whole-system auditing 2. a GUI replacing profile-owned selection with ad hoc folder, glob, or regex behavior 3. a GUI collapsing compile evidence, aggregate probe evidence, and per-execution probe evidence into one undifferentiated status view 4. a GUI allowing analyzer weakening or probe weakening through undocumented convenience toggles 5. a GUI hiding excluded artifacts, blocked execution, or profile-owned scope decisions 6. a GUI treating transient logs as sufficient acceptance evidence The GUI must therefore behave as a strict, reviewable surface over the grammar-surface contracts. --- ## 2. Non-goals This contract does not define: * product boundary * source-kind semantics * analyzer semantics * rule-id semantics * report field semantics * schema semantics * probe behavior * acceptance gates * implementation internals below the GUI boundary Those meanings remain owned by their governing contracts. This file also does not authorize: * broad repo browsing as a substitute for profile selection * whole-system testing through the GUI * runtime-path validation * planner validation * API validation * ad hoc probe authoring as part of the default operator workflow --- ## 3. Relationship to higher contracts This file must be read consistently with at least: 1. `docs/00_main_design.md` 2. `docs/01_scope_contract.md` 3. `docs/02_analyzer_contract.md` 4. `docs/03_report_contract.md` 5. `docs/04_profiles.md` 6. `docs/05_rulepacks.md` 7. `docs/06_probe_spec.md` 8. `docs/07_semantik_inventory.md` 9. `docs/08_acceptance_contract.md` 10. `docs/09_change_control.md` This file does not redefine those documents. It defines how a GUI must expose and preserve their meaning. The GUI must not: * reinterpret profile breadth * reinterpret reviewed SemantiK inventory * reinterpret analyzer applicability * reinterpret report object meanings * reinterpret blocked versus failed semantics * reinterpret acceptance evidence obligations --- ## 4. GUI principles The GUI must satisfy all of the following principles: 1. **Profile-first operation** Every run begins from an explicit `profile_id`. 2. **Deterministic selection** Selection must be explainable in terms of profile scope and reviewed inventory. 3. **Reviewable scope** The operator must be able to see what is included, what is excluded, and why. 4. **Source-kind visibility** The GUI must preserve the distinction between: * `gf_source` * `probe_asset` * `grammar_surface_tool` * `linearization_probe` 5. **Evidence separation** The GUI must preserve the distinction between: * findings * `compile_summary` * aggregate `probe_summary` * per-execution `probe_execution_summary` 6. **No silent weakening** The GUI must not offer convenience controls that weaken scope, analyzers, probes, schemas, or acceptance obligations without explicit contract support. 7. **Acceptance-oriented output** The GUI must produce reviewable outputs and must not rely on transient visual state alone. 8. **Accessibility and inspectability** The GUI must remain usable for bounded audit review, not just for visual monitoring. --- ## 5. Required operator workflow The GUI must expose the following operator workflow in order: 1. choose profile and run inputs 2. preview selection and inventory-backed scope 3. review analyzer and probe plan 4. execute the run 5. inspect structured results 6. review acceptance evidence and export outputs The GUI may allow navigation back to earlier stages before execution. The GUI must not start an audit run until the operator has selected a profile and the GUI has computed a valid selection preview. --- ## 6. Required top-level layout The GUI must provide a persistent top-level workspace with: * active product name * active `profile_id` * active project root * current run id when a run exists * current run status when a run exists * export actions for generated outputs The GUI must provide persistent navigation for these required sections: 1. Run Setup 2. Selection Preview 3. Analyzer and Probe Plan 4. Execution Monitor 5. Results Explorer 6. Acceptance Evidence The GUI may use a left rail, stepper, or other structured navigation model. It must not reduce these sections into a single uncontrolled form or a log-only window. --- ## 7. Run Setup contract The Run Setup section must expose the bounded inputs required to create a run. At minimum, it must expose: * `profile_id` * `project_root` * output root or output destination * optional previous-run baseline for diff behavior * single-file mode * single target selector * implementation-required toolchain paths only where applicable The Run Setup section must satisfy all of the following: 1. `profile_id` is mandatory. 2. Single-file mode must remain within active profile scope. 3. The target selector must not admit out-of-scope artifacts. 4. Raw regex include/exclude controls must not be the primary scope mechanism. 5. Raw glob scanning must not be the primary SemantiK scope mechanism. 6. SemantiK-specific runs must be inventory-backed. 7. Invalid or incomplete setup must block run start with an explicit reason. The GUI may expose advanced settings only when those settings do not alter product meaning and do not weaken profile-owned behavior. --- ## 8. Selection Preview contract The Selection Preview section is mandatory. It must show the computed run selection before execution. At minimum, it must present: * selected artifacts grouped by `source_kind` * excluded artifacts or excluded candidate classes where relevant * inclusion reason * exclusion reason * profile ownership * inventory backing where applicable For SemantiK-specific profiles, the Selection Preview must make it clear that selection comes from reviewed inventory rather than free-form crawling. For `linearization_probe` contexts, the preview must show that each probe identity is derived from reviewed probe assets or tightly scoped acceptance assets. Ambiguous artifacts must appear as excluded. They must not silently disappear. The GUI must not present a SemantiK run as valid when selection cannot be explained in terms of reviewed inventory and active profile behavior. --- ## 9. Analyzer and Probe Plan contract The Analyzer and Probe Plan section must show the bounded execution plan implied by the chosen profile and computed selection. At minimum, it must show: * enabled source kinds * analyzers that will run * analyzers that are required but not applicable for the current selection * analyzers that are blocked * active probe assets * probe families or probe cases to be evaluated * target languages or target concretes where applicable * known blocked-by conditions before run start where detectable This section must be primarily explanatory. It must not allow undocumented per-run weakening of required analyzer or probe behavior. The GUI may allow inspection of analyzer details. It must not permit profile-owned analyzer semantics to drift through convenience toggles. --- ## 10. Execution Monitor contract The Execution Monitor section must show structured run progress. It must not reduce execution to an unstructured console stream. At minimum, it must show: * artifact ref or probe execution ref * `source_kind` * current analyzer or current execution phase * execution outcome * artifact status when known * diagnostic class when known * blocked-by information where present * timing information when available The Execution Monitor must preserve separate visibility for: * static analysis activity * compile analysis activity * probe execution activity * report generation activity * schema validation activity where applicable Blocked execution and failed execution must remain visibly distinct. Probe activity must remain visibly distinct from compile activity. A successful compile phase must not be presented as proof of language correctness. --- ## 11. Results Explorer contract The Results Explorer section is mandatory. It must render the structured report model rather than an undocumented GUI-only summary. At minimum, it must provide the following coordinated views: ### 11.1 Run Summary This view must render top-level run outputs, including at least: * `run_status` * top-level counts * severity totals * diagnostic-class totals * analyzers used * diff summary when present ### 11.2 Artifact Table This view must list artifact results in a structured, filterable form. At minimum, each row must expose: * `artifact_ref` * `artifact_path` * `source_kind` * `artifact_status` * `diagnostic_class` * timing * findings count ### 11.3 Artifact Detail This view must show the full detail for one selected artifact result. It must preserve separate sections for: * findings * `compile_summary` * aggregate `probe_summary` * per-execution `probe_execution_summary` * related artifacts * analyzer results when present ### 11.4 Findings Explorer This view must present findings in a searchable and filterable form. At minimum, each finding display must expose: * `finding_id` * `rule_id` * severity * message * `source_kind` * target ref * evidence excerpt * suggested fix kind * analyzer id The Results Explorer must never merge aggregate `probe_summary` fields into `probe_execution_summary`, and must never merge `probe_execution_summary` fields into aggregate `probe_summary`. The Results Explorer must never present `compile_summary` as a substitute for probe evidence. --- ## 12. Acceptance Evidence contract The Acceptance Evidence section is mandatory for representative runs and acceptance-oriented workflows. It must expose reviewable evidence artifacts rather than transient success messaging. At minimum, it must surface: * generated `summary.json` * human-readable derived outputs * schema-validation result where schemas exist * representative run outputs * required test result summaries where connected to the run * baseline or diff information where applicable * explicit gate state for acceptance-relevant checks The Acceptance Evidence section must make missing or blocked evidence explicit. It must not present a run as acceptance-ready when required evidence is missing, blocked, or failed. --- ## 13. Export and reviewability contract The GUI must support exporting or opening the generated reviewable outputs of a run. At minimum, the operator must be able to access: * `summary.json` * generated human-readable report artifacts * validation outputs where produced * diff outputs where produced The GUI must not make the visual state of the application the sole record of a run. A closed GUI session must not destroy the only usable representation of acceptance evidence. --- ## 14. Allowed convenience features The GUI may include convenience features only when they do not alter contract meaning. Allowed examples include: * recent-project history * recent output destinations * saved window layout * column visibility and sorting * search and filter controls over rendered report data * copy actions for ids, file paths, and evidence excerpts * direct open actions for generated report files * direct navigation from findings to referenced artifacts * progress notifications * non-semantic visual themes Allowed convenience features must remain subordinate to the contracts. They must not silently change scope, analyzer ownership, probe meaning, report semantics, or acceptance obligations. --- ## 15. Forbidden GUI behaviors The GUI must not do any of the following: 1. broaden scope beyond the grammar-surface boundary 2. treat runtime adapters, planner code, API code, or whole-system tests as in-scope by default 3. replace profile selection with raw filesystem selection as the primary workflow 4. admit ambiguous artifacts without reviewed inventory support 5. hide blocked execution behind generic failure messaging 6. collapse findings, compile evidence, aggregate probe evidence, and per-execution probe evidence into one status field 7. permit undocumented disabling of required analyzers 8. permit undocumented disabling of required probe behavior 9. present compile success as proof of language correctness 10. rely on transient logs as the only acceptance evidence 11. invent GUI-only statuses or summaries that contradict the report contract 12. claim product acceptance based on GUI messaging alone Any GUI behavior in this list is architecturally invalid. --- ## 16. State persistence rules The GUI may persist operator convenience state. It must not persist hidden product semantics. Persisted state may include: * recent project roots * recent output roots * window geometry * panel layout * recently used profile id * recent baseline selection * column preferences * non-semantic view preferences Persisted state must not silently override: * active profile semantics * reviewed inventory behavior * required analyzers * required probes * report field meanings * acceptance gates A persisted state file must be treated as convenience state only. It must not become an undocumented product contract. --- ## 17. Accessibility and inspectability requirements The GUI must remain usable for real audit review. At minimum, it must support: * keyboard-reachable primary workflow * readable status labels * stable rendering of long ids and paths * copyable text for findings and evidence * clear differentiation between blocked, failed, warning, and clean states * inspection of excluded artifacts or excluded classes where the selection preview presents exclusions * review of report-backed detail without requiring console access The GUI must prioritize inspectability over decorative compression. --- ## 18. Required GUI tests The implementation must include GUI-focused tests sufficient to prove contract compliance. At minimum, these must include: 1. tests that a profile is required before run start 2. tests that single-file targeting is constrained by active profile scope 3. tests that SemantiK selection preview reflects reviewed inventory-backed inclusion 4. tests that ambiguous artifacts are rendered as excluded rather than silently admitted 5. tests that source-kind grouping remains visible 6. tests that blocked and failed states remain distinct in the execution monitor 7. tests that `compile_summary`, `probe_summary`, and `probe_execution_summary` remain separate in results rendering 8. tests that `probe_summary` views never show per-execution-only fields 9. tests that `probe_execution_summary` views never show aggregate-only fields 10. tests that `summary.json` and derived outputs remain reachable from the GUI 11. tests that acceptance evidence is presented as persisted outputs rather than transient success messages 12. tests that convenience-state restoration does not alter profile-owned run semantics Representative golden GUI tests may be implemented through structured state assertions, rendered model assertions, screenshot regression tests, or a bounded combination of those techniques. --- ## 19. Change policy Any change to the GUI requires coordinated contract review when it affects: * profile setup behavior * selection preview meaning * source-kind visibility * analyzer visibility or control semantics * probe visibility or control semantics * result rendering semantics * acceptance evidence rendering * persisted-state meaning * accessibility of required evidence * the relationship between GUI views and generated report artifacts Changes that alter scope meaning, analyzer meaning, probe meaning, report meaning, schema meaning, or acceptance meaning are not GUI-only changes. They require synchronized updates to the governing higher-order contracts. No silent GUI drift is allowed. --- ## 20. Precedence and relationship to implementation details For GUI behavior, precedence order is: 1. `docs/00_main_design.md` 2. `docs/01_scope_contract.md` 3. `docs/02_analyzer_contract.md` 4. `docs/03_report_contract.md` 5. `docs/04_profiles.md` 6. `docs/05_rulepacks.md` 7. `docs/06_probe_spec.md` 8. `docs/07_semantik_inventory.md` 9. `docs/08_acceptance_contract.md` 10. `docs/09_change_control.md` 11. `docs/10_gui_contract.md` 12. implementation details This file is the governing contract for GUI behavior only. It does not override higher-order product semantics. --- ## 21. One-line operational summary The GUI contract defines a profile-first, inventory-backed, evidence-preserving operator surface for the SemantiK Grammar Surface Auditor in which setup, selection, probes, reports, and acceptance remain reviewable and cannot silently weaken the documented grammar-surface product. ================================================================================================ FILE: README.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 0e9aeb7a8abe4a9f60ae7ac2f53c19eb222d638ef0278cb285a32a046f1ed303 CONTENT_BYTES: 16216 ================================================================================================ # SemantiK GF-Zone Auditor A source-kind aware audit platform for the **GF zone** of SemantiK: real `gf/*.gf` grammars, GF-adjacent runtime adapters, and GF-facing build and QA tooling. This project is the planned evolution of `gf-audit`. The goal is **not** to widen a GF-only scanner with patches. The goal is to build a rigorous auditor that treats each kind of source as what it actually is: - **GF source files** are compiled, scanned, and probed as linguistic artifacts. - **GF-adjacent Python/runtime files** are audited with SemantiK-specific static analyzers. - **GF tooling and QA scripts** are audited for invocation drift, language coverage drift, and verification gaps. The result is a focused engineering tool for language work in SemantiK without conflating grammar correctness, runtime integration, and full-system QA. --- ## Status This repository defines the **target application** and implementation direction. It is based on the existing `gf-audit` foundation, but the new application is intentionally broader in architecture and narrower in scope than a whole-system test harness: - broader than `gf-audit` because it covers the **SemantiK GF zone**, not only `.gf` files - narrower than end-to-end QA because it does **not** attempt to validate planners, APIs, business logic, or runtime performance as a whole Until implementation is complete, treat this README as the **product contract and engineering direction** for the new app. --- ## Why this exists A multilingual failure in SemantiK can come from different layers: - a real grammar issue in `gf/Wiki*.gf` - a shared GF layer that leaks pivot-language literals - a runtime adapter that hardcodes a concrete or silently falls back to English - a build or QA script that stopped validating the right language surface A plain GF compiler run is not enough, and a whole-system runtime test is too broad for source-level diagnosis. This tool exists to answer a narrower, harder, and more useful question: > **Are the source files that define, route, compile, load, and verify GF behavior in SemantiK correct as a language implementation surface?** --- ## Design goals - Be **straight and robust**, not patch-based. - Preserve the strongest parts of `gf-audit` instead of discarding them. - Keep **compile evidence**, **static findings**, and **probe evidence** separate. - Model artifacts by **source kind**, not only by file extension. - Produce outputs that are useful for both developers and AI-assisted debugging. - Support both **single-file diagnosis** and **profile-driven multi-file audits**. - Catch language-surface regressions that compile cleanly. --- ## What the app audits The app targets the **SemantiK GF zone**. ### Included by default #### Tier A — Native GF source Examples: - `gf/SemantikArchitect.gf` - `gf/WikiI.gf` - `gf/WikiEng.gf` - `gf/WikiFre.gf` - related `gf/Wiki*.gf` modules These are audited as real GF modules. #### Tier B — GF-adjacent runtime adapters Examples: - `app/adapters/engines/gf_wrapper.py` - `app/adapters/engines/gf_engine.py` - `app/adapters/engines/gf_construction_adapter.py` - related GF-loading, concrete-routing, fallback, and surface-assembly code These are **not** forced through `gf.exe`. They are audited with SemantiK-specific analyzers. #### Tier C — GF build and QA tooling Examples: - `compile_pgf` - `language_health` - `visualize_ast` - `test_gf_dynamic` - `test_multilingual_generation` - `eval_bios` - related low-level GF validation tooling These are audited for consistency, coverage, and language-verification quality. ### Explicitly out of scope #### Tier D — Whole-system runtime and planner logic Examples: - planner internals - unrelated API routes - general semantic frame logic - performance instrumentation - end-to-end product behavior beyond the GF zone This app is **not** a replacement for integration tests, acceptance tests, or planner validation. --- ## Core idea: source kinds The new app is built around **source kinds**. Every selected artifact is classified before analysis. The analyzer pipeline is then chosen based on that classification. ### Supported source kinds - `gf_source` - `gf_runtime_adapter` - `gf_tooling` - `gf_test_asset` (optional profile-dependent class) This avoids the main failure mode of weak generalization: making the tool run on more files while giving less trustworthy results. --- ## Analyzer model Each source kind gets analyzers that match its nature. ### `gf_source` Primary analyzers: - GF static scan - GF compile analyzer - GF linearization probe analyzer Typical failures: - syntax or type errors - missing concrete - inherited pivot-language literals - language realization functions not overridden where required - a concrete that compiles but still surfaces the wrong language ### `gf_runtime_adapter` Primary analyzers: - Python static contract analyzer - literal leak scan - routing and fallback scan - artifact path and PGF reference checks Typical failures: - hardcoded concrete names - implicit default-to-English behavior - legacy fallback remaining nominal instead of explicit - string assembly that bypasses GF language-specific realization - drift between reported metadata and actual backend behavior ### `gf_tooling` Primary analyzers: - command contract scan - invocation consistency scan - language-list consistency scan - QA expectation quality scan Typical failures: - tooling that omits an available language - health checks that disagree with compile helpers - low-value multilingual tests that only assert non-empty output - probes and evaluators that no longer match the grammar surface they claim to validate --- ## Probe-based language verification Compile success is necessary, but it is **not sufficient** for multilingual correctness. The app therefore includes an optional **probe phase** for selected GF profiles. A probe run can: - compile a designated root grammar or PGF - verify that required concretes exist - linearize selected trees or canned expressions in target languages - apply language-specific expectations - apply forbidden-literal checks ### Example A French wiki-surface probe can explicitly reject English literals such as: - `is a` - `is` - `participated in` That means the tool can catch a concrete that technically compiles but still leaks English surface strings in French output. This is one of the main reasons the new app exists. --- ## Profiles The app is profile-driven. Profiles define: - artifact roots - source-kind mappings - analyzer sets - rule packs - probe fixtures - output emphasis ### Planned profiles #### `pure-gf` Use this when auditing a normal GF project. Behavior: - close to current `gf-audit` - real `.gf` files only - scan + optional compile + current-style reporting #### `semantik-gf-zone` Use this when auditing the full SemantiK GF zone. Behavior: - native GF files - GF-adjacent runtime adapters - GF-facing tooling and QA assets - unified evidence model across source kinds #### `semantik-wiki-surface` Use this for focused work on the wiki grammars and their immediate integration surface. Behavior: - `gf/Wiki*.gf` - direct GF adapters - bio/event rule packs - language-surface probes for EN/FR and related fixtures --- ## Outputs The app keeps the best output model from `gf-audit` and extends it. Each run creates a timestamped run directory under the configured output root. ### Expected top-level outputs ```text _gf_zone_audit/ run_YYYYMMDD_HHMMSS/ summary.json summary.md AI_READY.md top_errors.txt details/ raw/ ``` ### Main report files #### `summary.json` Canonical machine-readable output for automation and downstream tools. #### `summary.md` Human-readable audit summary. #### `AI_READY.md` Top-level handoff artifact for AI-assisted debugging. #### `top_errors.txt` Compact grouped first-error view. ### Evidence model Each artifact result is expected to include fields such as: - `artifact_path` - `source_kind` - `selected_by_profile` - `fingerprint` - `analyzers_run` - `status` - `diagnostic_class` - `blocked_by` - `compile_summary` (when relevant) - `probe_summary` (when relevant) - `findings[]` - `related_artifacts[]` ### Finding schema Each finding should carry structured evidence, including: - `rule_id` - `source_kind` - `severity` - `message` - `artifact_path` - `line` or `span` - `related_paths` - `evidence_excerpt` - `suggested_fix_kind` This is the basis for stable summaries, diffs, and future UI extensions. --- ## What makes this different from `gf-audit` `gf-audit` is a strong GF project auditor. This new app keeps that foundation, but changes the architecture in a decisive way: | Area | `gf-audit` | SemantiK GF-Zone Auditor | |---|---|---| | Target | generic GF project | SemantiK GF zone | | Selection basis | mostly GF files | source-kind aware profiles | | Scanner model | GF-specific | multiple analyzer families | | Compile path | GF only | GF compile only where valid | | Non-GF files | out of scope | first-class audit targets | | Language validation | compile-focused | compile + probe-focused | | Scope | grammar-centric | grammar + adapters + tooling | This is a structural evolution, not a widened file filter. --- ## Architecture overview ```text selection layer -> source-kind classification -> analyzer registry -> evidence model -> result synthesis -> reports + diffs + AI handoff ``` ### Planned internal split ```text gf-zone-audit/ app/ selection/ kinds/ analyzers/ gf_source/ gf_adapter/ gf_tooling/ evidence/ reports/ profiles/ cli/ gui/ ``` ### Migration strategy The implementation should proceed in phases: 1. preserve current pure-GF behavior with regression tests 2. introduce `source_kind` and normalized `findings[]` 3. move current GF scanner/compiler behind analyzer interfaces 4. add SemantiK profiles and source classification 5. add GF-adapter and tooling analyzers 6. add the probe engine 7. stabilize outputs and diff behavior This sequencing is deliberate. The architecture must change **before** SemantiK-specific rules are added, or the project will collapse into special cases. --- ## Installation target The final installation story may evolve, but the intended baseline is: - Python 3.11+ - local access to the target repository - a working GF installation for GF-source compilation and probing - access to required RGL resources when compiling GF grammars The current `gf-audit` baseline is Windows-oriented and includes both GUI and CLI entry points. The new app is expected to preserve a similar developer workflow where it adds value, while keeping the core architecture tool-agnostic. --- ## Planned CLI shape The exact executable name can still be finalized. The examples below show the intended workflow. ### Audit a normal GF project ```bash gf-zone-audit --profile pure-gf --project-root ``` ### Audit the full SemantiK GF zone ```bash gf-zone-audit --profile semantik-gf-zone --project-root ``` ### Audit one wiki grammar in focused mode ```bash gf-zone-audit \ --profile semantik-wiki-surface \ --mode file \ --target-file gf/WikiFre.gf \ --project-root ``` ### Run probe-based language verification ```bash gf-zone-audit \ --profile semantik-wiki-surface \ --project-root \ --run-probes ``` These commands describe the intended interface contract. They should be treated as target behavior until implementation lands. --- ## Typical workflow ### For grammar work 1. run the wiki-surface or pure-GF profile 2. inspect `summary.md` 3. inspect `AI_READY.md` if you want an AI handoff packet 4. inspect `probe_summary` and per-artifact logs when language output is suspicious ### For integration work 1. run the SemantiK GF-zone profile 2. review adapter and tooling findings separately from GF compile outcomes 3. use the structured findings to isolate whether the issue is in grammar, adapter, or tooling ### For regression control 1. keep representative snapshots and fixtures 2. diff against the previous run 3. use probe fixtures for language-surface regressions --- ## Testing strategy The app should be validated at three levels. ### Unit tests Targets: - selector rules - source-kind classification - analyzer behavior - evidence schema - diff behavior - report generation Purpose: - prevent architecture drift - keep profile boundaries precise - keep evidence normalization stable ### Fixture integration tests Targets: - small synthetic GF repos - adapter fixtures with intentional fallback bugs - tooling fixtures with language-list drift - probe fixtures with forbidden-literal checks Purpose: - prove that analyzers cooperate correctly under one profile ### Real-repo regression tests Targets: - SemantiK snapshots - known French wiki-surface regression fixtures - language-health and compile-path drift cases Purpose: - guard against the actual failure modes this tool is meant to catch --- ## Design principles - Do not fake generality. - Do not treat non-GF files as if they were GF files. - Do not merge compile failures and static findings into one vague bucket. - Do not use compile success as a proxy for language correctness. - Do not bury SemantiK-specific logic inside generic core modules. - Do preserve deterministic outputs, typed result models, and top-level handoff reports. - Do make evidence first-class. - Do keep the single-file diagnosis path strong. --- ## Non-goals This app is not intended to: - replace end-to-end runtime tests - validate planner behavior - certify API correctness for the whole product - measure latency or runtime performance - substitute for manual linguistic review when deeper naturalness work is needed It is a **source auditor for the GF zone**, not a universal test system. --- ## Initial SemantiK inventory The first SemantiK profile should start from an explicit inventory rather than uncontrolled directory crawling. ### Native GF surface - `gf/SemantikArchitect.gf` - `gf/WikiI.gf` - `gf/WikiEng.gf` - `gf/WikiFre.gf` - related `gf/Wiki*.gf` modules ### Runtime adapters - `app/adapters/engines/construction_realizer.py` - `app/adapters/engines/family_construction_adapter.py` - `app/adapters/engines/gf_construction_adapter.py` - `app/adapters/engines/safe_mode_construction_adapter.py` - `app/adapters/engines/gf_wrapper.py` - `app/adapters/engines/gf_engine.py` - `app/adapters/engines/python_engine_wrapper.py` ### GF-facing tooling and QA - `compile_pgf` - `language_health` - `test_gf_dynamic` - `test_multilingual_generation` - `eval_bios` - `diagnostic_audit` - `visualize_ast` ### Tests and acceptance artifacts - `tests/core/test_use_cases.py` - `docs/testing/EN_FR_bio_acceptance.md` - future probe fixture catalogs --- ## Roadmap ### Phase 1 — Core refactor - preserve current pure-GF behavior - introduce `source_kind` - introduce normalized `findings[]` - move current GF logic behind analyzer interfaces ### Phase 2 — SemantiK profiles - define explicit artifact inventories - add profile-owned source-kind maps - stabilize profile selection behavior ### Phase 3 — Adapter and tooling analyzers - add SemantiK-specific rule packs - surface structured findings for non-GF artifacts ### Phase 4 — Probe engine - compile nominated roots - verify expected concretes - linearize probe fixtures - fail on forbidden-literal leaks and language-surface mismatches ### Phase 5 — Stabilization - finalize output schema - finalize diff behavior - finalize AI handoff packet quality - promote the tool to a real language-surface engineering gate --- ## Guiding statement Build this app as a **source-kind aware audit platform** for the SemantiK GF zone. Do not widen the current GF-only tool with patches. Do not hide source differences behind a generic status flag. Do not claim runtime certainty from static evidence. Treat grammar files, adapters, and tooling as distinct artifacts with first-class analyzers, and make probe-based language verification part of the foundation.