Skip to content

docs: add review-and-recall Blueprints and documentation ownership - #151

Merged
timeleft-- merged 4 commits into
mainfrom
automation/fava-trails.org-32-blueprint
Oct 24, 2026
Merged

timeleft-- merged 4 commits into
mainfrom
automation/fava-trails.org-32-blueprint

Conversation

@yia-mw-agent

Copy link
Copy Markdown
Contributor

What this adds

Design records and an ownership map for the review-and-recall lifecycle, so an engineer can follow draft → review → approved recall → correction and a contributor can find the authoritative explanation for each behavior.

  • blueprints/ with a short guide: the lifecycle feature, the review-gate module, a proposed local-review-default feature, and a codebase map of src/fava_trails.
  • docs/documentation-ownership.md: one owner per fact, approved and avoided wording (replaces "crash-proof" and "no contradictory memories" with accurate statements), and the separation of approved design, implementation and release evidence.
  • docs/governed-recall.md: states which writes use the before-image journal and what an interrupted save_thought/update_thought can leave behind.
  • CONTRIBUTING.md: one line pointing contributors at the ownership map and Blueprints.

No runtime code changes. Docs only, so the version policy requires no bump (scripts/mw-version.py check --base origin/main passes: repo stays 0.8.5-rc.1).

Evidence

  • Source inspected at 0f7c01f. Existing fixture tests for configuration, the review gate, governed visibility, local-only sync and navigation: 236 passed (jj 0.45.1). These use fixture servers; no real model was run, and the documents say so.
  • Configuration resolution in the local-default design was observed by loading GlobalConfig for each case, not inferred.
  • Two independent agent reviews checked the documents against source. Round one found six blocking errors (a proposed rule that would have broken the documented Laya and hosted llm-oneshot forms, a bootstrap path that could send text to hosted OpenAI, unspecified handling of the shared per-machine config, "sync never publishes" being false under push_strategy: immediate, and two lifecycle recovery claims). Round two confirmed those resolved and found further gaps in the new bootstrap and check design; those revisions are in the head. The final revision after round two was not re-reviewed.
  • All relative links resolve.

Needs the coordinator

Blueprint design status is draft. Approval is the delivery coordinator's to record under the delegated authority; this PR does not claim it. A status-only commit should pin the reviewed revision after merge.

Not changed here (reconciliation list for the later tickets)

  • Summaries that still say sync never publishes: AGENTS_SETUP_INSTRUCTIONS.md:285, AGENTS_USAGE_INSTRUCTIONS.md:111, the sync and propose_truth tool descriptions in server.py, and the data-repo template guides.
  • llm-oneshot ignores trust_gate_timeout_secs per request (60 s per attempt), yet the setup guide recommends 240 s for slow local models.
  • The website's AGENTS.md/CLAUDE.md stale claims are handled in the companion fava-trails.org PR; page components carrying the same wording are website-journey work.

@timeleft-- timeleft-- left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent Captain source review of this exact head is consolidated in the formal REQUEST_CHANGES review on companion site PR MachineWisdomAI/fava-trails.org#39, the canonical PR for the existing child #32 root. The lifecycle failure table must distinguish outer timeout (draft unchanged) from provider timeout returned as an error verdict (record becomes error; author cannot re-propose). The local-default Blueprint already has that distinction. Repair through the existing child task on these same PRs; do not create another root or repair relay. The proposed compatibility-preserving bootstrap contract otherwise fits the delegated scope. Final design acceptance will be recorded after corrected-head review, without a human-attention gate.

@timeleft-- timeleft-- left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent Captain review of exact head dc7085a. The lifecycle table now correctly distinguishes outer timeout from a recorded provider error, resolving the companion review finding. Reused the unchanged source/Blueprint assessment from d1b2d0e and inspected the complete changed table against tools/navigation.py, trust_gate.py and trail.py. The compatibility-preserving local bootstrap design, ownership boundaries, governed lifecycle and scoped failure claims fit issue #32. Local version-policy check and whitespace validation pass; hosted runtime tests are still pending and are not claimed passed here. This is documentation/design approval, not evidence of a new default, real-model quality or package publication. Under the user's delegated coordinator authority I accept the three feature/module designs at this reviewed revision; their status/evidence fields must be updated in the already-planned implementation and contributor changes, without a new human approval gate. Merge this companion before site PR #39 once all actual required checks pass.

@timeleft--
timeleft-- merged commit 5b75a21 into main Oct 24, 2026
12 checks passed
@timeleft--
timeleft-- deleted the automation/fava-trails.org-32-blueprint branch October 24, 2026 19:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants