ci(knowledge): enforce document metadata and seven-day reviews

AGENTS.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T17:06:45Z"
+-->
 # AGENTS
 
 All agents working in this repository must follow the guidance in

ARCHITECTURE.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T00:00:00Z"
+-->
 # Architecture
 
 Current implementation, verified against source and tests on 2026-09-08.

CONTRIBUTING.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T17:06:45Z"
+-->
 # Contributing to Graphon
 
 This guide reflects the repository's current local tooling and GitHub Actions
@@ -218,14 +221,17 @@ and the tests relevant to a change. Keep affected documentation and source/test
 links current in the same change. See [Knowledge maintenance](docs/maintenance.md)
 for document placement, review, and plans for work that spans sessions.
 
-The normal pytest suite includes a local documentation link and reachability
-check. To run it alone:
+The normal pytest suite checks local documentation links, reachability, and
+review metadata, failing if the oldest review is more than seven days old.
+To run these checks alone:
 
 ```bash
 uv run pytest -n 0 tests/test_repository_docs.py
 ```
 
-This check verifies navigation, not whether prose still describes the code.
+These checks verify navigation and recorded review age. Review the page's claims
+before updating its `last_checked` timestamp; see the
+[metadata format and scope](docs/maintenance.md#document-metadata-and-review-deadline).
 
 ## Git Commits
 

MIGRATION.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T17:06:16Z"
+-->
 # Migration guide
 
 ## 0.7.x to 0.8.0 (Unreleased)
@@ -170,9 +173,9 @@ fallback to later parent-pool changes.
 
 An abort or fatal failure now wins over a concurrent pause. Persist resumable state
 only after the engine emits `GraphRunPausedEvent` and its run iterator has been
-fully consumed; do not infer a pause from a queued command. Loop handlers write
-only their configured selectors back to the parent, while iteration frame state
-remains isolated.
+fully consumed; do not infer a pause from a queued command. Loop variable-update
+events write back to existing parent-pool variables; propagation continues
+through nested Loops and stops at isolated Iteration pools.
 
 ### Graph validation
 

README.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T17:06:16Z"
+-->
 # Graphon
 
 Graphon is a Python graph execution engine for agentic AI workflows.
@@ -88,9 +91,9 @@ For the exact credential shape and runtime notes, see
 
 At a high level, direct Graphon usage looks like this:
 
-1. Build or load a graph and instantiate nodes into a `Graph`.
-2. Prepare `RuntimeState` with the workflow ID and seed the `VariablePool`.
-3. Configure model, file, HTTP, tool, or human-input adapters as needed.
+1. Prepare `RuntimeState` with the workflow ID and seed the `VariablePool`.
+2. Configure model, file, HTTP, tool, or human-input adapters as needed.
+3. Instantiate nodes with that state and build them into a `Graph`.
 4. Run `Engine` and consume emitted engine events; a local command channel is
    created automatically unless an external channel is supplied.
 5. Read final outputs from runtime state.

docs/README.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T17:06:45Z"
+-->
 # Repository knowledge
 
 Start with the question you need to answer, then follow the links to code and
@@ -38,14 +41,16 @@ Keep detailed component knowledge next to its implementation and link it here.
 
 ## Evidence and review
 
-The architecture and development guides were checked against source and test
-definitions on **2026-09-08**. This is a review date, not a claim that all behavior
-or external integrations have been exercised. Their linked tests show where to
-verify a change; [Contributing](../CONTRIBUTING.md) defines the validation workflow.
+Each page records its review timestamp using the shared
+[document metadata format](maintenance.md#document-metadata-and-review-deadline).
+This is not a claim that all behavior or external integrations have been
+exercised. Linked tests show where to verify a change;
+[Contributing](../CONTRIBUTING.md) defines the validation workflow.
 
 The [documentation test](../tests/test_repository_docs.py) checks local file
-links and whether this knowledge base is reachable from
-[AGENTS.md](../AGENTS.md). It runs in the existing pytest CI job. It does not
+links, whether this knowledge base is reachable from [AGENTS.md](../AGENTS.md),
+and whether every maintained page has been checked within seven days. It runs
+as part of the normal pytest suite in CI. Recorded timestamps do not
 prove that prose matches behavior; review source and tests when updating a page.
 
 ## Related work

docs/development.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T00:00:00Z"
+-->
 # Development navigation
 
 At the start of every development workflow, read and follow

docs/maintenance.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T17:06:45Z"
+-->
 # Maintaining repository knowledge
 
 The [knowledge index](README.md) is the entry point for durable context.
@@ -39,16 +42,58 @@ before starting overlapping work.
 
 Use relative inline Markdown links for repository files, including evidence in
 tables. Keep examples inside fenced code blocks. The existing test suite checks
-links in root Markdown files, this directory, and component/example READMEs:
+links in root Markdown files and every Markdown file under `docs/`, `src/`, and
+`examples/`:
 
 ```bash
 uv run pytest -n 0 tests/test_repository_docs.py
 ```
 
 The check catches missing local paths and knowledge pages unreachable from
-`AGENTS.md`. It does not validate heading anchors, external URLs, reference-style
-links, prose accuracy, or review dates. When it fails, repair the link or add a
-route from an indexed page; do not weaken the check to hide obsolete knowledge.
+`AGENTS.md`, and enforces the review metadata below. It does not validate heading
+anchors, external URLs, reference-style links, or prose accuracy. When it fails,
+repair the link, add a route from an indexed page, or review the overdue document;
+do not weaken the check to hide obsolete knowledge.
+
+## Document metadata and review deadline
+
+Every maintained knowledge document starts with this YAML metadata in an HTML
+comment, before its title. The comment stays hidden in rendered Markdown,
+including the package README:
+
+```markdown
+<!-- knowledge
+last_checked: "2026-09-08T00:00:00Z"
+-->
+# Document title
+```
+
+`last_checked` is required: a UTC timestamp in `YYYY-MM-DDTHH:MM:SSZ` format,
+stored as a YAML string. Use quotes as shown above to prevent YAML from converting
+it to a timestamp value. It records when the page's claims were last checked
+against their source and evidence, not the file modification time or proof that
+every linked test was executed. Advance it only after reviewing the page,
+correcting stale claims, and checking its links. A partial edit does not renew
+an entire page's review. Other descriptive YAML fields may be added when needed;
+CI requires only `last_checked`.
+
+The same format applies to all root Markdown files except `CLA.md` (the legal
+agreement) and `CHANGELOG.md` (the release ledger), and every Markdown file under
+`docs/`, `src/`, and `examples/`. New nested knowledge bases and non-README guides
+are included automatically. Completed plans remain in scope: review their
+historical accuracy and links without rewriting them as current API guidance.
+Templates under `.github/` are outside the knowledge scope.
+
+The documentation check rejects missing, malformed, or future timestamps. It
+compares the earliest `last_checked` across the entire scope with the current UTC
+time and fails when its age exceeds seven 24-hour days; exactly seven days passes.
+The failure identifies the oldest file and its timestamp.
+
+The check runs in the normal pytest suite, including the existing CI jobs for
+pull requests targeting `main` and release tags, and with the focused command
+above. It scans the full scope without changed-file filters. Date-only review
+evidence imported during the initial rollout uses midnight UTC on that date as
+a conservative lower bound, rather than claiming a new review at migration time.
 
 ## Plans for work that needs durable context
 
@@ -94,6 +139,3 @@ produce a cleanup diff.
 After editing, repair affected links and run the documentation check above.
 Report the changes made, or that no relevant cleanup was needed. Keep review
 dates limited to claims actually checked. Broader audits remain outside this step.
-
-This is an ordinary contribution workflow. There is no scheduled maintenance
-agent or semantic freshness checker configured by these documents.

docs/plans/execution-file-runtime.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T00:00:00Z"
+-->
 # Execution-scoped file runtime
 
 **Status:** implementation, independent reviews, final naming pass, and checks

docs/plans/graph-validation.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T00:00:00Z"
+-->
 # TD-02: Reject invalid graphs before execution
 
 **Status:** completed locally; implementation, independent reviews, and checks complete.

docs/plans/snapshot-eligibility.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T00:00:00Z"
+-->
 # Snapshot eligibility (TD-03)
 
 **Status:** implementation and reviews complete locally, 2026-09-08.

docs/technical-debt.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T00:00:00Z"
+-->
 # Architecture review and technical debt
 
 **Reviewed:** 2026-09-08, Graphon 0.7.0, commit

examples/slim_llm/README.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T17:04:02Z"
+-->
 # Slim LLM Example
 
 This directory has two versions of the same LLM workflow:
@@ -43,8 +46,10 @@ Slim-backed LLM runtime. Configure it with the Slim client settings, plugin ID,
 provider, model name, and credentials. Optional completion parameters can be
 supplied by the Python construction when needed.
 
-For local mode, keep `slim.mode` as `local`. Put `dify-plugin-daemon-slim` in
-`PATH`, set `SLIM_BINARY_PATH`, or place a `slim` binary in this directory.
+Both modes require the Slim client binary. Put `dify-plugin-daemon-slim` in
+`PATH`, set `SLIM_BINARY_PATH`, or place an executable `slim` binary in this directory.
+
+For local mode, keep `slim.mode` as `local`.
 
 For remote mode, set `slim.mode` to `remote`, then fill in `daemon_addr` and
 `daemon_key`.

src/graphon/engine/command/README.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T17:04:02Z"
+-->
 # Commands
 
 Command processing and channels for external workflow control.

src/graphon/engine/layer/README.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T17:04:02Z"
+-->
 # Layers
 
 Pluggable middleware for engine extensions.

src/graphon/model_runtime/README.md

@@ -1,3 +1,6 @@
+<!-- knowledge
+last_checked: "2026-09-08T17:04:02Z"
+-->
 # Model Runtime
 
 This package defines provider schemas, credential validation, capability-specific