From 57de8bacf1002c289326f3581f0a75de6d8abf11 Mon Sep 17 00:00:00 2001 From: Yaacov Date: Fri, 28 Aug 2026 16:27:56 +0300 Subject: [PATCH] docs: promote documentation governance --- AGENTS.md | 18 +++++ docs/README.md | 1 + docs/documentation-policy.md | 72 +++++++++++++++++++ docs/operations/team-contribution-protocol.md | 21 +++++- ...ent-documentation-system-and-publishing.md | 9 +++ 5 files changed, 119 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f825342..e379004 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -106,6 +106,13 @@ Optimize for long-term quality. Prefer the correct, maintainable solution even w Place documentation deliberately. Before creating a new document, decide where the information belongs in the existing documentation structure. Prefer updating the canonical existing document over creating a duplicate. If a new document is needed, give it the required metadata and link it from the relevant index. +Use the nearest authoritative repository and classify the fact by the question +it answers: Help, Capabilities, Architecture, Development, Operations, +Upstream, Product/Planning/Research, or Records. These are logical roles, not a +requirement to rename inherited folders. Current app Help belongs in +`scient-desktop/docs/user/`; the website renders approved, version-aware Scient +Docs from that source instead of owning a second prose copy. + Capture durable future context, not documentation volume. Preserve consequential decisions, constraints, interfaces, evidence, hard-won lessons, and repeated explanations. Do not promote every chat, meeting, transcript, or generated summary into repository knowledge. AI may draft documentation, but it is not the accountable owner and cannot confer acceptance. Preserve uncertainty and specific reasoning for human review. When authoritative sources conflict, surface the contradiction and route it to the owning person or document instead of smoothing it into false agreement. @@ -118,6 +125,10 @@ Current important documents: - `docs/README.md` - documentation map and current repo structure. - `docs/documentation-policy.md` - rules for creating, updating, and classifying documentation. +- `docs/planning/scient-documentation-system-and-publishing.md` - accepted + documentation-system decisions, implementation sequence, pilot gates, and + deferred choices; durable recurring rules live in the policy and repository- + local guidance rather than in that plan. - `docs/product/PRD.md` - product direction, core capabilities, user experience principles, and technical requirements. - `docs/product/skills-system.md` - draft product model, trust boundaries, candidate catalog, and validation order for reusable scientific skills; the @@ -167,6 +178,13 @@ Be honest about the repo's maturity. Do not describe planned architecture as imp When adding documentation, prefer clear current-state wording over polished but vague language. +For the same capability, update existing durable owners as implementation lands +gradually. Keep scratch, transcripts, temporary checklists, and handoffs outside +the worktree or in the owning GitHub item. Create a new durable file only when +it answers a distinct lasting question with a clear owner, evidence boundary, +update trigger, and index route. In every pull request, include the concise +`Documentation impact` declaration defined by the team contribution protocol. + If a document is useful now but does not yet have an obvious permanent home, it may be left in the repo temporarily. Later, as the repo architecture settles, documents should be moved into the right structure. When moving or reorganizing documents, preserve their intent and history. Do not delete planning material just because it is rough. diff --git a/docs/README.md b/docs/README.md index 400b883..c9abc51 100644 --- a/docs/README.md +++ b/docs/README.md @@ -26,6 +26,7 @@ Start here: - [Collaborator onboarding](onboarding.md) - ordered project journey, repository tour, and contribution-area reading routes. - [Documentation policy](documentation-policy.md) - documentation rules, metadata, statuses, and placement policy. +- [Scient documentation system and publishing](planning/scient-documentation-system-and-publishing.md) - accepted repository-family authority, public Docs direction, implementation sequence, pilot gates, and deferred choices; recurring rules are promoted into the documentation policy and repository-local guidance. - [Product requirements](product/PRD.md) - canonical product direction. - [Scient skills system](product/skills-system.md) - draft product model, trust boundaries, candidate catalog, and validation order for reusable scientific diff --git a/docs/documentation-policy.md b/docs/documentation-policy.md index eed2b69..459809c 100644 --- a/docs/documentation-policy.md +++ b/docs/documentation-policy.md @@ -118,6 +118,60 @@ A broader company memory may connect to Scient through links and shared conventi The current scope recommendation and unresolved structural choices live in `docs/planning/repository-scope-and-company-memory.md`. +## Repository-Family Authority + +Scient documentation uses the nearest authoritative owner across independent +repositories: + +- `Scient` owns product truth, philosophy, cross-product architecture and + decisions, roadmaps, cross-repository operations, research, and this family + policy; +- `scient-desktop` owns current desktop Help, implementation capability and + architecture records, development guidance, runbooks, and T3 divergence; +- the website owns Docs rendering, navigation, search, deployment, and the + exact source/version it publishes; and +- `scient-agent` joins this model only when native Scient-agent implementation + begins. Its current inherited starting repository is outside the present + documentation migration. + +Repositories remain independent. A cross-repository consequence uses a +separate, explicitly ordered dependent pull request; matching branch names do +not establish dependency or authority. Each public repository must state the +minimum local rule a contributor needs without requiring access to this +repository or copying private planning authority. + +Current desktop product help is authored under `scient-desktop/docs/user/`. +The public **Scient Docs** website at `/docs` publishes a reviewed, +version-aware selection from that source; the website must not maintain a +second prose copy. Website documentation can be corrected and deployed without +an app release, but stable pages must remain truthful about the app versions +and behavior they describe. A future documentation MCP, if justified, must +retrieve this same corpus rather than become another authored authority. + +## Documentation Roles + +Classify durable knowledge by the question it answers, not by a vague audience +label or a required folder name: + +- **Help** explains how people and support agents use released behavior. +- **Capabilities** records what implementation exists, its limits, maturity, + source anchors, evolution, and related plans. +- **Architecture** owns authorities, boundaries, invariants, dependencies, and + hard-to-reverse decisions. +- **Development** owns build, test, configuration, contributor, and debugging + guidance. +- **Operations** owns release, deployment, migration, monitoring, support, and + recovery procedures. +- **Upstream** owns donor ancestry, protected divergences, conflicts, and + selective-intake decisions. +- **Records** preserves useful historical evidence, superseded plans, + retirements, and delivery context without governing current behavior. + +These are logical roles. Repositories may retain inherited paths such as +`docs/user/` and `docs/internals/` when moving files would add merge or link +cost without improving authority. Repository indexes map the logical role to +the real current path. + ## Knowledge Selection Rules Create durable documentation when it will provide future context: an important decision and its reasoning, a durable principle or constraint, an owned interface or process, source-backed research, a hard-won lesson, a repeated explanation, or knowledge at real risk of disappearing. @@ -126,6 +180,24 @@ Do not preserve every meeting, chat, transcript, task trace, or generated summar Documentation volume is not a quality measure. Prefer a small coherent knowledge system over a large archive that obscures authority. +Update an existing durable owner before creating a new file. Feature work often +lands in slices; later slices update the same capability, Help, or architecture +owner when its truth changes rather than creating one document per pull +request, milestone, component, or implementation phase. + +Create a new durable document only when the knowledge remains useful after the +pull request, no existing owner can hold it coherently, it answers a distinct +durable question, its repository/status/evidence/update trigger are clear, and +the appropriate index can route to it. Ordinary feature scratch, transcripts, +session handoffs, temporary checklists, and active progress belong outside the +worktree or in the owning GitHub work item. The merged pull request is the +implementation record. + +An ordinary bounded change should normally update zero to two primary owners. +More may be correct for privacy, architecture, retirement, upstream, or broad +program changes, but should trigger an ownership review rather than automatic +fan-out or omission. + ## Evidence Rules Durable factual claims should be grounded in one of: diff --git a/docs/operations/team-contribution-protocol.md b/docs/operations/team-contribution-protocol.md index bce5536..bb3a0ff 100644 --- a/docs/operations/team-contribution-protocol.md +++ b/docs/operations/team-contribution-protocol.md @@ -3,7 +3,7 @@ Status: Active Owner: Yaacov Created: 2026-07-22 -Last updated: 2026-07-27 +Last updated: 2026-08-28 Purpose: Defines the minimum shared workflow and verification evidence for contributions across maintained ScientFactory repositories. Doc type: Operational procedure @@ -71,6 +71,22 @@ Use separate pull requests for separate repositories. Cross-repository work must state its dependencies and landing order rather than relying on matching branch names. +Every implementation or documentation pull request must make its documentation +impact explicit in one concise declaration: + +```text +Documentation impact: None — +Documentation impact: Updated — +Documentation impact: Dependent PR — +``` + +Use one line, choosing the applicable form. `None` requires a real reason, not +silence. `Updated` points to the existing owners changed with the work. A +genuine cross-repository consequence uses `Dependent PR` and states the landing +order; do not copy the same prose into both repositories. This trial remains +deliberately smaller than a taxonomy checklist and should grow only if repeated +failures prove another field is needed. + ## Verification Standard Verification must match the behavior and risk being changed. Passing a broad @@ -222,7 +238,8 @@ should make these facts easy to find: - Quality Review findings and dispositions; - Integration Readiness Review verdict and remaining findings; - known limitations or deferrals; and -- cross-repository, deployment, migration, or release impact. +- cross-repository, deployment, migration, or release impact; and +- the concise documentation-impact declaration above. Small changes may answer briefly. Evidence should be proportional, not omitted or padded with irrelevant ceremony. diff --git a/docs/planning/scient-documentation-system-and-publishing.md b/docs/planning/scient-documentation-system-and-publishing.md index 3d7b88a..46a94b0 100644 --- a/docs/planning/scient-documentation-system-and-publishing.md +++ b/docs/planning/scient-documentation-system-and-publishing.md @@ -22,6 +22,15 @@ Until each rule is promoted into its durable owner, the current [Documentation Policy](../documentation-policy.md), repository AGENTS.md files, and area indexes remain operationally authoritative. +Phase 1 promotes recurring rules into the [Documentation +Policy](../documentation-policy.md), [Team Contribution +Protocol](../operations/team-contribution-protocol.md), and repository-local +agent, contributor, index, work-artifact, and pull-request surfaces. After those +dependent changes land, use those owners for recurring decisions. This accepted +planning note remains the implementation roadmap and decision record for the +inventory, pilots, publishing proof, migration, and automation phases; it does +not compete with the promoted policy. + Current product behavior belongs beside the implementation that provides it. Product direction and cross-product planning belong in this Scient repository. Website deployment remains owned by the website repository.