From c4ca79491a7f554433c37b822a5dacd5961e387a Mon Sep 17 00:00:00 2001 From: -LAN- Date: Wed, 9 Sep 2026 01:11:17 +0800 Subject: [PATCH 1/2] ci(knowledge): enforce document metadata and seven-day reviews Define shared last_checked metadata for maintained knowledge documents and initialize timestamps from review evidence. Require valid UTC timestamp strings and reject documents whose oldest review is more than seven days old. Run knowledge checks on all pull requests, main pushes, daily schedules, and manual dispatch. Document review scope and timestamp maintenance, and correct guide inaccuracies found during metadata initialization. Refs #284 --- .github/workflows/knowledge.yml | 32 ++++++ AGENTS.md | 3 + ARCHITECTURE.md | 3 + CONTRIBUTING.md | 17 ++- MIGRATION.md | 9 +- README.md | 13 ++- docs/README.md | 17 ++- docs/development.md | 3 + docs/maintenance.md | 58 +++++++++- docs/plans/execution-file-runtime.md | 3 + docs/plans/graph-validation.md | 3 + docs/plans/snapshot-eligibility.md | 3 + docs/technical-debt.md | 3 + examples/slim_llm/README.md | 9 +- src/graphon/engine/command/README.md | 3 + src/graphon/engine/layer/README.md | 3 + src/graphon/model_runtime/README.md | 3 + tests/test_repository_docs.py | 165 ++++++++++++++++++++++++++- 18 files changed, 323 insertions(+), 27 deletions(-) create mode 100644 .github/workflows/knowledge.yml diff --git a/.github/workflows/knowledge.yml b/.github/workflows/knowledge.yml new file mode 100644 index 00000000..9ec03343 --- /dev/null +++ b/.github/workflows/knowledge.yml @@ -0,0 +1,32 @@ +name: Knowledge checks + +on: + pull_request: + push: + branches: + - main + schedule: + - cron: "17 3 * * *" + workflow_dispatch: + +permissions: {} + +jobs: + knowledge: + name: Knowledge metadata and freshness + runs-on: depot-ubuntu-24.04 + permissions: + contents: read + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Setup uv and Python + uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + with: + python-version: "3.12" + + - name: Check all knowledge documents + run: uv run pytest -n 0 tests/test_repository_docs.py diff --git a/AGENTS.md b/AGENTS.md index 85b1d114..8880cd0e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,6 @@ + # AGENTS All agents working in this repository must follow the guidance in diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 57eca1b3..50d5bc0a 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,3 +1,6 @@ + # Architecture Current implementation, verified against source and tests on 2026-09-08. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47147a23..f1ab142a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,6 @@ + # Contributing to Graphon This guide reflects the repository's current local tooling and GitHub Actions @@ -207,6 +210,11 @@ Pull requests targeting `main` currently run three kinds of checks: 2. `just check` including `uv.lock` freshness validation 3. `uv run pytest` on Python 3.12 and 3.13 +The separate [Knowledge checks workflow](.github/workflows/knowledge.yml) runs +on all pull requests (including stacked branches), pushes to `main`, daily on the +default branch, and manual dispatch. It checks document links, required metadata, +and the [seven-day review deadline](docs/maintenance.md#document-metadata-and-review-deadline). + Keep local workflow aligned with those checks. A green local `just test` plus `just check` is useful, but it is not a complete substitute for the exact CI flow because CI also validates PR titles and a Python version matrix. @@ -218,14 +226,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 diff --git a/MIGRATION.md b/MIGRATION.md index 7671541f..e1707a54 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,3 +1,6 @@ + # 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 diff --git a/README.md b/README.md index 04e5e8ae..4c2c9bf6 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,6 @@ + # 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. @@ -162,6 +165,10 @@ CI currently validates pull request titles, runs `just check` including 3.13. Python 3.14 is currently excluded because `unstructured` does not yet support it. +The [knowledge checks](.github/workflows/knowledge.yml) also check document links +and the [seven-day review deadline](docs/maintenance.md#document-metadata-and-review-deadline) +on every pull request, pushes to `main`, and a daily schedule. + ## License Apache-2.0. See [LICENSE](LICENSE). diff --git a/docs/README.md b/docs/README.md index 768f81bd..267b583c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,6 @@ + # 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 +in pytest and the dedicated knowledge CI workflow. Recorded timestamps do not prove that prose matches behavior; review source and tests when updating a page. ## Related work diff --git a/docs/development.md b/docs/development.md index e6e8a5fc..7b810f60 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,3 +1,6 @@ + # Development navigation At the start of every development workflow, read and follow diff --git a/docs/maintenance.md b/docs/maintenance.md index ba5ba7d1..ba789c9e 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -1,3 +1,6 @@ + # Maintaining repository knowledge The [knowledge index](README.md) is the entry point for durable context. @@ -39,16 +42,59 @@ 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 + +# 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 [Knowledge checks workflow](../.github/workflows/knowledge.yml) runs on all +pull requests, pushes to `main`, daily on the default branch, and manual dispatch. +It scans the full scope without changed-file filters. The same check runs in +the normal pytest suite and with the focused command above. 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 @@ -95,5 +141,5 @@ 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. +This is an ordinary contribution workflow. The scheduled check enforces recorded +review age; it does not review or rewrite prose automatically. diff --git a/docs/plans/execution-file-runtime.md b/docs/plans/execution-file-runtime.md index 1615e672..9011ca8f 100644 --- a/docs/plans/execution-file-runtime.md +++ b/docs/plans/execution-file-runtime.md @@ -1,3 +1,6 @@ + # Execution-scoped file runtime **Status:** implementation, independent reviews, final naming pass, and checks diff --git a/docs/plans/graph-validation.md b/docs/plans/graph-validation.md index aabc9b2d..47de6a2c 100644 --- a/docs/plans/graph-validation.md +++ b/docs/plans/graph-validation.md @@ -1,3 +1,6 @@ + # TD-02: Reject invalid graphs before execution **Status:** completed locally; implementation, independent reviews, and checks complete. diff --git a/docs/plans/snapshot-eligibility.md b/docs/plans/snapshot-eligibility.md index c304dd15..2104a481 100644 --- a/docs/plans/snapshot-eligibility.md +++ b/docs/plans/snapshot-eligibility.md @@ -1,3 +1,6 @@ + # Snapshot eligibility (TD-03) **Status:** implementation and reviews complete locally, 2026-09-08. diff --git a/docs/technical-debt.md b/docs/technical-debt.md index 6a3e64b0..8050b235 100644 --- a/docs/technical-debt.md +++ b/docs/technical-debt.md @@ -1,3 +1,6 @@ + # Architecture review and technical debt **Reviewed:** 2026-09-08, Graphon 0.7.0, commit diff --git a/examples/slim_llm/README.md b/examples/slim_llm/README.md index dfb1d182..1969dca7 100644 --- a/examples/slim_llm/README.md +++ b/examples/slim_llm/README.md @@ -1,3 +1,6 @@ + # 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`. diff --git a/src/graphon/engine/command/README.md b/src/graphon/engine/command/README.md index 063c76e5..c4ac1c92 100644 --- a/src/graphon/engine/command/README.md +++ b/src/graphon/engine/command/README.md @@ -1,3 +1,6 @@ + # Commands Command processing and channels for external workflow control. diff --git a/src/graphon/engine/layer/README.md b/src/graphon/engine/layer/README.md index 4af4e124..70b43c29 100644 --- a/src/graphon/engine/layer/README.md +++ b/src/graphon/engine/layer/README.md @@ -1,3 +1,6 @@ + # Layers Pluggable middleware for engine extensions. diff --git a/src/graphon/model_runtime/README.md b/src/graphon/model_runtime/README.md index 20ef133b..cc4622ab 100644 --- a/src/graphon/model_runtime/README.md +++ b/src/graphon/model_runtime/README.md @@ -1,3 +1,6 @@ + # Model Runtime This package defines provider schemas, credential validation, capability-specific diff --git a/tests/test_repository_docs.py b/tests/test_repository_docs.py index e4a406c0..355839dd 100644 --- a/tests/test_repository_docs.py +++ b/tests/test_repository_docs.py @@ -1,4 +1,4 @@ -"""Check simple inline [label](relative/path) links and knowledge discoverability. +"""Check knowledge links, discoverability, and recorded review age. Fenced code, external URLs, and fragments are ignored. Reference links, HTML, link titles, and paths containing spaces or parentheses are outside this check; @@ -6,16 +6,173 @@ """ import re +from datetime import UTC, datetime, timedelta from pathlib import Path from urllib.parse import unquote, urlsplit +import pytest +import yaml + + +def find_repository_documents(root: Path) -> set[Path]: + return ( + set(root.glob("*.md")) + | set(root.glob("docs/**/*.md")) + | set(root.glob("src/**/*.md")) + | set(root.glob("examples/**/*.md")) + ) + + +def check_document_reviews(root: Path, now: datetime) -> None: + """Require valid metadata and no review older than seven days.""" + documents = find_repository_documents(root) - { + root / "CLA.md", + root / "CHANGELOG.md", + } + reviews: list[tuple[datetime, Path]] = [] + for document in sorted(documents): + path = document.relative_to(root) + header = re.match( + r"\A(?:\n|$)", + document.read_text(encoding="utf-8"), + re.DOTALL, + ) + assert header, f"{path}: missing leading knowledge metadata with last_checked" + error = ( + f"{path}: last_checked must be a UTC timestamp string: " + '"YYYY-MM-DDTHH:MM:SSZ"' + ) + try: + metadata = yaml.safe_load(header[1]) + except yaml.YAMLError as exc: + raise AssertionError(error) from exc + assert isinstance(metadata, dict), error + timestamp = metadata.get("last_checked") + assert isinstance(timestamp, str), error + assert re.fullmatch( + r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z", timestamp + ), error + try: + checked_at = datetime.fromisoformat(timestamp) + except ValueError as exc: + raise AssertionError(error) from exc + assert checked_at <= now, f"{path}: last_checked {timestamp} is in the future" + reviews.append((checked_at, path)) + + assert reviews, "No knowledge documents found" + checked_at, oldest_document = min(reviews) + assert now - checked_at <= timedelta(days=7), ( + f"{oldest_document}: last_checked {checked_at.strftime('%Y-%m-%dT%H:%M:%SZ')} " + "is more than seven days old; review the document and update its metadata" + ) + + +def test_repository_documentation_reviews() -> None: + check_document_reviews(Path(__file__).resolve().parents[1], datetime.now(UTC)) + + +@pytest.mark.parametrize( + "age", + [timedelta(0), timedelta(days=7), timedelta(days=7, seconds=1), timedelta(days=8)], +) +def test_document_review_deadline(tmp_path: Path, age: timedelta) -> None: + now = datetime(2026, 9, 9, 12, tzinfo=UTC) + (tmp_path / "README.md").write_text( + '\n# Index\n', + encoding="utf-8", + ) + oldest_document = tmp_path / "docs" / "guide.md" + oldest_document.parent.mkdir() + timestamp = (now - age).strftime("%Y-%m-%dT%H:%M:%SZ") + oldest_document.write_text( + f'\n# Guide\n', + encoding="utf-8", + ) + if age == timedelta(days=8): + (oldest_document.parent / "a-newer.md").write_text( + '\n# Newer\n', + encoding="utf-8", + ) + + if age > timedelta(days=7): + with pytest.raises( + AssertionError, match=rf"docs/guide.md.*{re.escape(timestamp)}" + ): + check_document_reviews(tmp_path, now) + else: + check_document_reviews(tmp_path, now) + + +@pytest.mark.parametrize( + "path", + [ + "GUIDE.md", + "docs/nested/guide.md", + "docs/plans/done.md", + "docs/CHANGELOG.md", + "src/component/guide.md", + "examples/demo/README.md", + "examples/demo/guide.md", + ], +) +def test_every_knowledge_document_requires_metadata(tmp_path: Path, path: str) -> None: + document = tmp_path / path + document.parent.mkdir(parents=True, exist_ok=True) + document.write_text("# Guide\n", encoding="utf-8") + with pytest.raises(AssertionError, match=re.escape(path)): + check_document_reviews(tmp_path, datetime(2026, 9, 9, tzinfo=UTC)) + + +@pytest.mark.parametrize( + "metadata", + [ + "last_checked: [", + "[]", + "title: Guide", + "last_checked: null", + "last_checked: 2026-09-08T00:00:00Z", + 'last_checked: "2026-09-08"', + 'last_checked: "2026-09-08T00:00:00"', + 'last_checked: "2026-09-08T08:00:00+08:00"', + 'last_checked: "2026-02-30T00:00:00Z"', + 'last_checked: "2026-09-09T00:00:01Z"', + ], +) +def test_invalid_document_review_metadata(tmp_path: Path, metadata: str) -> None: + (tmp_path / "README.md").write_text( + f"\n# Guide\n", encoding="utf-8" + ) + with pytest.raises(AssertionError, match=r"README.md.*last_checked"): + check_document_reviews(tmp_path, datetime(2026, 9, 9, tzinfo=UTC)) + + +def test_review_metadata_must_start_document(tmp_path: Path) -> None: + (tmp_path / "README.md").write_text( + '# Guide\n\n', + encoding="utf-8", + ) + with pytest.raises(AssertionError, match=r"README.md"): + check_document_reviews(tmp_path, datetime(2026, 9, 9, tzinfo=UTC)) + + +def test_legal_release_and_template_files_do_not_require_reviews( + tmp_path: Path, +) -> None: + (tmp_path / "README.md").write_text( + '\n# Index\n', + encoding="utf-8", + ) + for path in ("CLA.md", "CHANGELOG.md", ".github/pull_request_template.md"): + document = tmp_path / path + document.parent.mkdir(parents=True, exist_ok=True) + document.write_text("# Historical or template content\n", encoding="utf-8") + check_document_reviews(tmp_path, datetime(2026, 9, 9, tzinfo=UTC)) + def test_repository_documentation_links() -> None: root = Path(__file__).resolve().parents[1] knowledge = set(root.glob("docs/**/*.md")) | {root / "ARCHITECTURE.md"} - documents = set(root.glob("*.md")) | set(root.glob("docs/**/*.md")) - documents |= set(root.glob("src/**/README.md")) - documents |= set(root.glob("examples/**/README.md")) + documents = find_repository_documents(root) links: dict[Path, set[Path]] = {document: set() for document in documents} for document in sorted(documents): From 71ada7ab535555aaf43a471b748ab56deec91132 Mon Sep 17 00:00:00 2001 From: -LAN- Date: Wed, 9 Sep 2026 01:22:20 +0800 Subject: [PATCH 2/2] ci(knowledge): remove redundant documentation workflow Use the existing pytest jobs to enforce knowledge metadata and review freshness. Remove the duplicate workflow and its additional triggers, and update contributor documentation to describe the existing PR-to-main and release coverage. Refs #284 --- .github/workflows/knowledge.yml | 32 -------------------------------- CONTRIBUTING.md | 5 ----- README.md | 4 ---- docs/README.md | 2 +- docs/maintenance.md | 14 +++++--------- 5 files changed, 6 insertions(+), 51 deletions(-) delete mode 100644 .github/workflows/knowledge.yml diff --git a/.github/workflows/knowledge.yml b/.github/workflows/knowledge.yml deleted file mode 100644 index 9ec03343..00000000 --- a/.github/workflows/knowledge.yml +++ /dev/null @@ -1,32 +0,0 @@ -name: Knowledge checks - -on: - pull_request: - push: - branches: - - main - schedule: - - cron: "17 3 * * *" - workflow_dispatch: - -permissions: {} - -jobs: - knowledge: - name: Knowledge metadata and freshness - runs-on: depot-ubuntu-24.04 - permissions: - contents: read - steps: - - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Setup uv and Python - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 - with: - python-version: "3.12" - - - name: Check all knowledge documents - run: uv run pytest -n 0 tests/test_repository_docs.py diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f1ab142a..e9e15dfe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -210,11 +210,6 @@ Pull requests targeting `main` currently run three kinds of checks: 2. `just check` including `uv.lock` freshness validation 3. `uv run pytest` on Python 3.12 and 3.13 -The separate [Knowledge checks workflow](.github/workflows/knowledge.yml) runs -on all pull requests (including stacked branches), pushes to `main`, daily on the -default branch, and manual dispatch. It checks document links, required metadata, -and the [seven-day review deadline](docs/maintenance.md#document-metadata-and-review-deadline). - Keep local workflow aligned with those checks. A green local `just test` plus `just check` is useful, but it is not a complete substitute for the exact CI flow because CI also validates PR titles and a Python version matrix. diff --git a/README.md b/README.md index 4c2c9bf6..9be81056 100644 --- a/README.md +++ b/README.md @@ -165,10 +165,6 @@ CI currently validates pull request titles, runs `just check` including 3.13. Python 3.14 is currently excluded because `unstructured` does not yet support it. -The [knowledge checks](.github/workflows/knowledge.yml) also check document links -and the [seven-day review deadline](docs/maintenance.md#document-metadata-and-review-deadline) -on every pull request, pushes to `main`, and a daily schedule. - ## License Apache-2.0. See [LICENSE](LICENSE). diff --git a/docs/README.md b/docs/README.md index 267b583c..9d3fe9ec 100644 --- a/docs/README.md +++ b/docs/README.md @@ -50,7 +50,7 @@ exercised. Linked tests show where to verify a change; The [documentation test](../tests/test_repository_docs.py) checks local file 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 -in pytest and the dedicated knowledge CI workflow. Recorded timestamps do not +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 diff --git a/docs/maintenance.md b/docs/maintenance.md index ba789c9e..8f14a44a 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -89,12 +89,11 @@ compares the earliest `last_checked` across the entire scope with the current UT 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 [Knowledge checks workflow](../.github/workflows/knowledge.yml) runs on all -pull requests, pushes to `main`, daily on the default branch, and manual dispatch. -It scans the full scope without changed-file filters. The same check runs in -the normal pytest suite and with the focused command above. 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. +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 @@ -140,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. The scheduled check enforces recorded -review age; it does not review or rewrite prose automatically.