Docs

AGENTS.md

@@ -21,6 +21,44 @@ Do not spend context window or analysis on those files unless explicitly request
 When asked to change or move an API, import path, command, feature, or behavior, do not add or keep compatibility layers, aliases, shims, fallback paths, or legacy entrypoints unless explicitly requested. A requested change means the old behavior should be removed.
 When updating tests, remove obsolete tests that only assert removed/old implementation behavior does not exist. Do not preserve rejection or absence checks for API/features that were intentionally removed unless explicitly requested.
 
+Treat tests as evidence for a named invariant, not as specifications merely
+because they already exist. Add or retain automated tests when they protect at
+least one of the following:
+
+- externally observable behavior or a public API;
+- a documented diagnostic or serialized/generated format;
+- ABI, ownership, lifetime, memory-safety, build, or release behavior;
+- a stage handoff or architectural boundary whose violation would allow a
+  downstream stage to make an upstream decision; or
+- repository structure that is directly consumed by tooling.
+
+Do not add tests whose only purpose is to freeze prose, wording, heading or
+section order, private class or function names, complete file inventories,
+dataclass field inventories, exact internal call order, preferred inheritance,
+or incidental directory/module layout. Those are recommendations for
+contributor review unless the user explicitly promotes one to a maintained
+contract. Unit tests may construct internal models when their behavior or
+completed state is the invariant, but they should not assert implementation
+shape just to prevent refactoring.
+
+When an existing test fails after an intentional change, identify the behavior
+or risk it was meant to protect before changing production code. Keep or
+rewrite the test when that invariant remains a contract; remove it when it only
+records the previous implementation or a recommendation. Do not change correct
+behavior solely to satisfy a brittle test.
+
+The agent owns the review work that is not delegated to rigid tests. Before and
+after a refactor, compare the affected public behavior and stage outputs. When
+editing documentation, examples, diagnostics, or generated text, preserve the
+existing meaning, behavior, and wording as much as the request permits; inspect
+the diff and run the affected example or focused command when practical. Treat
+illustrative wording and demonstration output as review recommendations unless
+they are explicitly documented as stable formats. A command/result pair shown
+in a package guide must remain factual: run the command and compare stable
+output with the page, or validate only the displayed invariant when the output
+is an excerpt or depends on the active target. Do not duplicate that expected
+output in a separate test inventory.
+
 Before wrapper planning begins in `prik/planning/planner.py`, the
 post-IR policy stage must have completed every semantic decision needed by
 wrapper generation, including object kind, ownership, transfer, destruction,
@@ -85,4 +123,8 @@ pull-request verification:
 - `python3 -m radon cc prik -n C -s --total-average`
 - `python3 -m radon mi prik -s`
 Treat Ruff, Bandit, Vulture, and the Radon policy as blocking. The full Radon complexity and maintainability reports are advisory but must still be run. If a command cannot run because a dependency, network service, or CI-only environment value is unavailable, state that explicitly in the final response.
+
+The codegen complexity checker is also advisory: review and report its findings,
+but do not change correct behavior or fail the task solely to satisfy its
+structural recommendations.
 When you create a commit add this prefix to the message to know that you did push the commit "codex: ..."

CHANGELOG.md

@@ -13,14 +13,60 @@ release tags add a leading `v` to the package version.
   and one canonical page per production package, with local structures,
   important objects, runnable examples, expected outputs, test owners, change
   routes, and invariants.
-- Consolidated cross-stage concepts and contributor workflows, retained future
-  and deferred designs explicitly, and removed TODO-only pages, duplicate
-  architecture maps, and completed migration ledgers.
+- Consolidated contributor workflows and removed nonessential concept and
+  design drafts, TODO-only pages, duplicate architecture maps, and completed
+  migration ledgers.
 - Added Zenodo version and concept DOI links to the citation metadata, README,
   and About page.
 
 ### Changed
 
+- Marked the contributor Architecture and Codebase Map as reviewed for
+  publication; the renamed map now focuses on package and cross-stage module
+  ownership.
+- Clarified the Feature-to-Code Map as the capability-to-owner and evidence
+  index, linking reviewed user documentation and retaining only planned
+  contributor-documentation paths before their review.
+- Revised the Feature-to-Code Map with visible draft documentation markers,
+  stage-ordered change routes, narrower focused evidence, and separate array,
+  callback, and error routes.
+- Condensed the contributor Testing Strategy around test ownership, stage
+  evidence, stable contracts, end-to-end evidence, fixture placement, and
+  verification scope.
+- Clarified contributor workflows for changing PRIK, local verification, pull
+  request checks, and documentation maintenance.
+- Linked the Contributing workflow to the Feature-to-Code Map and Testing
+  Strategy, explained its pre-push hook setup, and normalized its editable
+  checkout test commands.
+- Clarified that pull-request validation requires the performance benchmark and
+  identified its workflow implementation.
+- Renamed the Package Guides section to Architecture Components and grouped its
+  build stages separately from its supporting components, distinguishing
+  cross-build pipeline orchestration from sequential stages.
+- Ordered the Developer Documentation sidebar by the architecture reading path,
+  with build stages before supporting components.
+- Reviewed the Pipeline Component guide around the source-build handoff,
+  independent contract and inspection workflows, and build-result ownership.
+- Reviewed the Preprocessing Stage guide around its Fortran source route,
+  compiler-derived target probes, module navigation, and executable examples.
+- Added Pipeline Component and source-level navigation for contract loading,
+  wrapper generation, build-manifest replay, and `build.py` orchestration.
+- Removed empty package-marker entries from the Pipeline Component and Compiler
+  Stage guides.
+- Added a brief Developer Documentation overview that routes readers to
+  Architecture, then Architecture Components, and linked it from the website
+  home page.
+- Replaced the contributor architecture's text-only build path with a rendered
+  diagram of its two input routes and shared pipeline.
+- Reduced documentation tests to enforce publication, link integrity,
+  executable examples, and public-reference contracts without freezing prose,
+  headings, page inventories, private names, or source-tree layout.
+- Reclassified implementation-structure and codegen-complexity checks as
+  contributor recommendations, while retaining hard behavioral, safety, ABI,
+  publication, and architectural-boundary contracts.
+- Moved contributor package-guide execution checks into the documentation
+  suite, using each guide's displayed result instead of a duplicate exact-
+  output inventory.
 - Reduced the root `prik` API to its version and normal-user build entrypoints;
   parser, semantic, probe, runtime, and planning tools now use their owning
   package import paths.
@@ -29,16 +75,10 @@ release tags add a leading `v` to the package version.
 - Made `prik` an import-only package boundary by removing its direct-script
   demonstration; command and stage-value examples remain available from their
   owning modules.
-- Expanded the contributor architecture and package guides into a complete
-  stage-by-stage tutorial, with every supported Python module, runnable example
-  result, focused test purpose, and change route recorded and checked against
-  the source tree.
+- Expanded the contributor architecture and package guides with concrete stage
+  handoffs, runnable example results, focused test purposes, and change routes.
 - Moved generated documentation and distribution output under the hidden
   `.artifacts/` directory in local commands and CI workflows.
-- Centralized every production-file execution-example output contract in one
-  contributor-architecture test inventory with one named test per file.
-- Renamed the central infrastructure owner to `execution_examples/` so its
-  responsibility is explicit in the test tree.
 - Consolidated developer and maintainer material under one Contributor
   Documentation tree and removed the separate maintainer documentation lane.
 - Moved the bundled header-only binding runtime from the package root into
@@ -52,9 +92,7 @@ release tags add a leading `v` to the package version.
   the former `prik.compiling`, `prik.probes`, parser-local C preprocessor, and
   pipeline-local preprocessing import paths were removed.
 - Replaced the public semantic-to-NumPy helper API with stage-owned semantic,
-  contract-runtime, and code-generation datatype catalogues, and documented the
-  complete internal datatype lifecycle from compiler probing to runtime
-  validation.
+  contract-runtime, and code-generation datatype catalogues.
 - Separated post-IR policy and wrapper planning into `prik.policy` and
   `prik.planning`; code generation now renders plan-driven docstrings, and the
   former maintainer import paths were removed.

CONTRIBUTING.md

@@ -13,7 +13,7 @@ python3 -m pip install -e ".[qa]"
 Run the smallest relevant test while you work:
 
 ```bash
-PYTHONPATH=. python3 -m pytest -q path/to/tests
+python3 -m pytest -q path/to/tests
 ```
 
 ## Before opening a pull request
@@ -26,7 +26,7 @@ PYTHONPATH=. python3 -m pytest -q path/to/tests
 ```bash
 python3 -m ruff check .
 python3 -m ruff format --check .
-PYTHONPATH=. python3 -m pytest -q path/to/tests
+python3 -m pytest -q path/to/tests
 ```
 
 Keep the pull request easy to review: explain the problem, the solution, and