From 75cccee8217f367e41d29bd85168e914c136cec9 Mon Sep 17 00:00:00 2001 From: J Date: Sat, 17 Oct 2026 15:02:16 +0530 Subject: [PATCH 1/4] test(docs): require usable quickstart, documentation map and valid internal links --- tests/test_docs_navigation.py | 55 +++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 tests/test_docs_navigation.py diff --git a/tests/test_docs_navigation.py b/tests/test_docs_navigation.py new file mode 100644 index 0000000..2bda217 --- /dev/null +++ b/tests/test_docs_navigation.py @@ -0,0 +1,55 @@ +"""Documentation navigation stays valid and describes the integrated state.""" +from pathlib import Path +import re +import unittest +from urllib.parse import unquote + +ROOT = Path(__file__).resolve().parents[1] +ENTRYPOINTS = ( + ROOT / "README.md", + ROOT / "docs" / "README.md", + ROOT / "docs" / "audits" / "README.md", + ROOT / "skills" / "freview" / "references" / "configuration.md", + ROOT / "skills" / "freview" / "references" / "optional-ops.md", + ROOT / "skills" / "freview" / "references" / "mutation-autonomy.md", +) +LINK = re.compile(r"(?") + if not destination or destination.startswith( + ("#", "http:", "https:", "mailto:", "data:") + ): + continue + # A link can include a title after its relative path. + relative = unquote(destination.split(" \"", 1)[0].split("#")[0]) + target = (source.parent / relative).resolve() + with self.subTest(path=relative): + self.assertTrue(target.is_relative_to(ROOT.resolve())) + self.assertTrue(target.exists(), f"{source}: {relative}") + + def test_documentation_index_explains_both_configs(self): + doc = (ROOT / "docs" / "README.md").read_text(encoding="utf-8") + self.assertIn(".freview.json", doc) + self.assertIn(".freview-ops.json", doc) + self.assertIn("Historical", doc) + self.assertIn("read-only", doc.lower()) + + def test_readme_has_an_actionable_quickstart(self): + readme = (ROOT / "README.md").read_text(encoding="utf-8") + self.assertIn("## Quick start", readme) + self.assertIn("## Features at a glance", readme) + self.assertIn("docs/README.md", readme) + self.assertNotIn("Pre-release read-only preview", readme) + self.assertIn("no version has been tagged", readme.lower()) + + +if __name__ == "__main__": + unittest.main() From 0b5953e2d7d1401ddd21ede5a368b895538244c2 Mon Sep 17 00:00:00 2001 From: J Date: Sat, 17 Oct 2026 15:03:19 +0530 Subject: [PATCH 2/4] docs: central documentation index and current source-readiness boundaries --- docs/README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..da410e9 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,40 @@ +# freview documentation + +Start with the [README](../README.md) for installation, everyday usage and feature overview. freview is an **evidence-first repository auditor**: the default skill is read-only. Its separately configured operations companion can run tools only after explicit authorization. + +## Where to go + +| Goal | Documentation | +| --- | --- | +| Install into Claude Code, Codex, OpenCode or Antigravity | [Installation and quick start](../README.md#quick-start), [agent discovery and limitations](../skills/freview/references/agent-discovery.md) | +| Understand Quick, Standard and Full | [Review modes](../skills/freview/references/modes.md), [freview skill](../skills/freview/SKILL.md) | +| Interpret local Git status versus remotely observable facts | [Local state and worktrees](../skills/freview/references/local-state.md), [Git analysis](../skills/freview/references/git.md) | +| Check spec completeness and independent verification evidence | [Evidence reconciliation](../skills/freview/references/evidence-reconciliation.md), [verification ground truth](testing/evidence-ground-truth.md) | +| Configure a normal read-only audit | [Project configuration](../skills/freview/references/configuration.md), [audit policy schema](../schemas/freview-config.schema.json) | +| Configure explicitly authorized automated operations | [Operations manual](../skills/freview/references/optional-ops.md), [operations policy schema](../schemas/freview-ops.schema.json), [default-safe example](../examples/freview-ops.example.json) | +| Understand adversarial review claims and interruption recovery | [Reviewer verdict and checkpoints](../skills/freview/references/review-verdict-protocol.md) | +| Use mutation quality, repair budgets and quality gates | [Mutation and autonomy guide](../skills/freview/references/mutation-autonomy.md) | +| Generate or interpret review findings | [Report format](../skills/freview/references/report.md), [remediation](../skills/freview/references/remediation.md) | +| Configure daily, optional checks | [Automation](../skills/freview/references/automation.md) | +| Diagnose installation/agent discovery | [Agent doctor and paths](../skills/freview/references/agent-discovery.md), [native activation acceptance checklist](testing/agent-activation-acceptance.md), [support](../SUPPORT.md) | +| Contribute or report a problem | [Contributing](../CONTRIBUTING.md), [support](../SUPPORT.md), [security reporting](../SECURITY.md) | +| See the evidence and historical development record | [Audit archive](audits/README.md), [historical roadmaps](roadmap/) | + +## Two different configurations + +**`.freview.json`** is optional, non-executable audit preference data. It can help choose the scope and branches for a normal read-only review. It never grants permission to run project scripts. + +**`.freview-ops.json`** is an entirely separate, versioned policy for *opt-in* operations: trusted worker and reviewer commands, tests, mutation tools, local hooks and a shipping **handoff**. Every execution-capable module is disabled by default. Enabling a module in a file alone cannot grant execution permission; runtime execution requires explicit user authorization, a clean exact-SHA checkout and caller-selected scratch storage. Never assume that copying the example turns autonomy on. + +## Current readiness and limitations + +- **Usable from source now:** the skill, reference documents and Python 3/Git helpers are on `main`. No versioned GitHub release has been published. Use the [installation instructions](../README.md#quick-start) and verify native skill discovery in the actual client. +- **Verified in CI:** the bundled assets, schema contracts, deterministic helper tests and isolated fake-agent workflows have passed Ubuntu and macOS matrix checks for the integrated `main` branch. +- **Not established by CI:** live Claude/Codex/OpenCode/Antigravity invocation for every supported client, real Stryker/mutmut workloads, arbitrary external tool safety, production deployment and physical Mac/SSD acceptance. They remain **acceptance gates for claims about those environments**, not evidence that the default read-only skill has failed. +- **Security boundary:** scratch copies are not operating-system sandboxes; a configured executable may still access other files and the network. Keep untrusted code outside optional execution unless separately sandboxed. + +## Historical documents versus current state + +The [audit archive](audits/README.md) and `docs/roadmap/` are **Historical** records. A dated entry that says a PR was a draft or unmerged describes its state *at that checkpoint*, not its current GitHub state. Feature PRs [#16](https://github.com/raiseCatError/freview/pull/16) through [#20](https://github.com/raiseCatError/freview/pull/20), plus the configuration-standardization [#21](https://github.com/raiseCatError/freview/pull/21), have since merged into `main`. + +Do not silently rewrite source-level audit findings, past SHAs or test evidence. Verify current Git refs and CI separately when making a present-day claim. From 39a1a7dab19f89ff25d55d0a89f63a465bb7fb8d Mon Sep 17 00:00:00 2001 From: J Date: Sat, 17 Oct 2026 15:04:13 +0530 Subject: [PATCH 3/4] docs: concise Quick start, feature matrix, accurate integrated readiness and docs navigation --- README.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9e6a401..342a286 100644 --- a/README.md +++ b/README.md @@ -10,12 +10,37 @@ freview is a portable, evidence-first [Agent Skill](https://agentskills.io/) for It produces a review, not a cleanup script. Default operations are **read-only**. -> **Status:** Pre-release read-only preview for trusted repositories; **no version has been tagged or published**. Installation and native discovery depend on agent/runtime configuration. A Full review is not a security certification or physical-device verification. +> **Status:** Usable from source; **pre-release, no version has been tagged or published**. Standard/Full repository audits are **read-only by default**; optional execution, mutation testing and repair workflows require separate explicit authorization. The bundled tests pass on Ubuntu/macOS, but native skill activation and real provider or mutation workloads must be checked in the target environment. -**Integrated on `main`:** [evidence reconciliation #16](https://github.com/raiseCatError/freview/pull/16), [optional operations #17](https://github.com/raiseCatError/freview/pull/17), [structured adversarial verdicts #18](https://github.com/raiseCatError/freview/pull/18), [verification isolation #19](https://github.com/raiseCatError/freview/pull/19), and [mutation quality / bounded autonomy #20](https://github.com/raiseCatError/freview/pull/20). All five have been merged with their development history retained; [the integrated CI run](https://github.com/raiseCatError/freview/actions/runs/39019289770) passed on Ubuntu and macOS. **This is still pre-release:** real provider, mutation workload and physical-host acceptance are separate from synthetic CI. +**Integrated on `main`:** evidence reconciliation, isolated operations, structured adversarial reviews, mutation scoring and bounded autonomy. All six development/standardization PRs [#16–#21](https://github.com/raiseCatError/freview/pulls?q=is%3Apr+is%3Amerged) are merged. [Final integration CI](https://github.com/raiseCatError/freview/actions/runs/39019711917) passed on Ubuntu and macOS. The implementation is **not** a production sandbox or a guarantee of correct agent reviews. **Dogfooding:** [final pre-release freview-on-freview review](docs/audits/2026-10-17-final-pre-release-self-review.md) · [historical original audit](docs/freview-reviews-freview.md). The newer source review is a bounded, hosted-evidence **partial-audit**, not native invocation in the author's agent session. +## Quick start + +Install the skill into the coding-agent environment where you want to use it: + +```sh +npx skills add raiseCatError/freview --skill freview +``` + +Open or reload your agent in the target repository, verify freview appears in its **native skill list**, then invoke `/freview` where the client supports that syntax, or ask for **“freview standard”**. The skill defaults to a **read-only Standard repository check**. `freview` here is an agent skill, **not a new shell executable**. Check your agent's specific discovery behavior in [Installation](#install) and the [acceptance checklist](docs/testing/agent-activation-acceptance.md). + +For an overview of documentation, configuration, optional mutation/autonomy and troubleshooting, see the [documentation index](docs/README.md). + +## Features at a glance + +| What you want | freview capability | Default behavior | +| --- | --- | --- | +| A factual repository health check | Quick / Standard: Git state, PRs/issues, release readiness, docs, CI and duplicate work items | **Read-only**, Standard | +| A deeper source review | Full: examine implementation reachability, quality, tests and evidence gaps | Read-only; Full only when requested | +| Check whether “done” is supported | Reconcile exact-SHA CI, requirements, claims and missing evidence | Claims never become proof automatically | +| Compare automated review results | Bounded structured adversarial findings and repair stages | **Off** until explicitly configured | +| Evaluate test strength | Optional Stryker/mutmut mutation reports and regression sensitivity | **Off**; optional quality gates | +| Coordinate implementation | Bounded worker/reviewer loops and recovery checkpoints | **Off**; scratch copies, no automatic merge or release | + +Read the [mode guide](skills/freview/references/modes.md) for scope and the [operations guide](skills/freview/references/optional-ops.md) for explicit permissions. Optional execution in a scratch copy **does not** constitute an OS sandbox. + ## Install One portable skill: `skills/freview/SKILL.md`, with references and an optional Python-standard-library snapshot helper. From ba550942e99a4f2fc6d6295514c09ab39c2ae812 Mon Sep 17 00:00:00 2001 From: J Date: Sat, 17 Oct 2026 15:04:43 +0530 Subject: [PATCH 4/4] docs: distinguish historical draft audit records from merged main state --- docs/audits/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/audits/README.md b/docs/audits/README.md index f40e587..f48111c 100644 --- a/docs/audits/README.md +++ b/docs/audits/README.md @@ -2,6 +2,8 @@ An evidence log, **not a list of software features or an endorsement of any agent report**. +> **Current-state note (2026-10-17):** This table is a chronological archive. References to "draft", "unmerged", or an unfinished gate refer to the **historical checkpoint**, not today's branch or PR status. Feature PRs [#16–#20](https://github.com/raiseCatError/freview/pulls?q=is%3Apr+is%3Amerged), plus standardization PR [#21](https://github.com/raiseCatError/freview/pull/21), have now merged into `main`. The [final integrated main CI](https://github.com/raiseCatError/freview/actions/runs/39019711917) succeeded on Ubuntu and macOS. This does **not** retroactively turn any earlier partial audit into a completed live-agent or mutation-engine validation. See the [current documentation map](../README.md). + | Audit | Observation | Scope and caveats | | --- | --- | --- | | [Historical freview-on-freview audit (draft PR #8)](https://github.com/raiseCatError/freview/pull/8) | AGY 1.4.0 / Gemini 3.8 Flash High | Full-mode native source review, verified local helper execution; **manual SKILL.md activation**, not native AGY injection; agent audit marked `partial-audit`. Preserve original baseline and later tested SHA. |