@nazty_labs/common-ground 0.5.1

package/docs/knowledge-policy.md

@@ -0,0 +1,51 @@
+# Knowledge policy
+
+Start at [START_HERE.md](../.common-ground/START_HERE.md). Use stateless lookup and assessment by default; task contexts are optional; the full MCP profile retains the original individual tools. Common Ground is a cache of the codebase, never authority over source or developer instructions.
+
+### Reading
+
+- Notes supplement codebase reading; they never replace it. Code is the source of truth. Open the source files behind a fact before relying on or changing it.
+- Navigate ownership_map → pillar chapter index → relevant chapter pages → facts and source. Signal matches are hints, not diagnoses. Read pillar_graph and fact dependencies when work crosses subsystems.
+- Read a directory's README when present, plus applicable ancestor, sibling, child, and referenced documentation. Explain facts to people in plain language with evidence; disclose stale or uncertain claims.
+- Branches, submodule checkouts, current failures, and other point-in-time state must be derived live on every check. Never cache them as durable facts.
+
+### Scope and writing
+
+- Cache verified subsystem behavior, architecture, connections, build/deploy mechanics, established conventions, and the commands that drive the code. Describe patterns that change how someone reasons about the subsystem, not inventories.
+- Exclude bugs, open issues, work to fix, incident postmortems, debugging narratives, activity logs, generic technology explainers, secrets, and anything not verified against current source.
+- Library-local detail belongs in that library's README. Keep subsystem-wide reasoning in the existing pillar/chapter and reference local documentation where useful; do not duplicate inventories.
+- Verified means you opened and read the relevant source during this session. Memory, guesses, unsupported inference, and cached quotes do not establish verification. Exact quotes and hashes cannot prove semantic truth.
+- Default to no note write. Silence is valid: an unwritten fact costs nothing; a wrong one costs every reader. When uncertain, explicitly state what cannot be verified. Ask immediately only when it blocks the developer task; otherwise collect the question for task completion. Never guess or silently accept a contradiction.
+- Classify into existing pillars and chapters first. Never add a pillar unless a new, uncovered, standalone subsystem warrants it and the developer approves. Chapters, ownership expansion, and fact admission also require developer direction; approval flags do not supply that direction.
+
+### Maintenance and correction
+
+- Touch it, own it: before adding or changing a fact, skim every page of the whole logical chapter, then review affected sibling/child chapters and reference files. Use review_plan and review_checklist; include all required dependency/dependent chapter reviews.
+- In that same edit, merge verified near duplicates, remove superseded content, and tighten narrative in the affected scope. Use explicit maintenance actions and reasons, preserving existing IDs for corrections. Repair affected references and dependency links in the same transaction. Do not clean up unrelated subsystems.
+- If an authorized code change contradicts a fact, chapter, pillar, or documentation claim, correction is mandatory in the same edit. Correct in place; never retain old and new contradictory versions or append a contradiction below the original. If boundaries themselves are wrong, raise the ownership change with the developer.
+- Corrections trigger the same full-file, sibling, child, and reference review as other touches. If the right version cannot be verified, say so explicitly and ask at the appropriate task boundary; do not publish a guessed resolution.
+- No note change does not end the check. Re-read the modified directory README and relevant documentation and ensure they remain valid, even when prepare_update returns noop.
+- Any developer may request cground tidy all, PILLAR, PILLAR/CHAPTER, or PILLAR/CHAPTER/FACT (a unique fact ID also works). This creates a scoped plan and local tidyId; the calling agent reads source and submits the verified cleanup. It neither invokes a model nor edits knowledge automatically. MCP tidy_plan only previews scope. The cground MCP tool exposes every CLI workflow: operation:help lists operations and help with args.operation returns its input schema. Use check or validate with a target; stale results list affected pillars, chapters and facts and ask "Start automatic cleanup?". With developer-requested cleanup, cleanup:true returns a scoped tidyId. The calling agent must verify source, submit reviewed corrections, then validate again. Use tidy for an explicitly requested broader cleanup.
+- Citation-only corrections can use empty touched paths without a tidy request when IDs, statements, ownership scopes and dependencies stay unchanged. A reason, full linked-chapter review, exact evidence and source/revision checks remain required.
+- For prepare_update, attest verification.sourceFiles and verification.documentFiles only after reading them this session (or verifying a deletion live). Use review_checklist for required paths and include newly cited evidence. Facts may contain up to 2,000 characters. Keep one coherent claim with enough context, conditions, and consequences to be useful; do not pad to the limit. Every assertion must be source-backed and free of temporary state.
+- Submit one complete transaction for affected chapters. Only changed chapters are rewritten; unchanged reviews use ignored local state. Existing correct facts stay unchanged unless explicit maintenance is justified. Never skip required tests based on stored notes.
+- For initial setup, “initialize” or “generate a map” requests a draft by default. Explicit developer delegation to save/publish verified initial boundaries and facts authorizes publication within that scope without another approval question. Verify source, preflight and report the saved map; flags and content tokens never prove human review. Draft-only and boundary-only requests do not authorize fact publication. Routine task additions still follow the approval workflow below.
+- Agents execute approved bootstrap/admission operations. Apply the same reading, verification, deduplication, and README checks before seed or admit. Commit durable knowledge and documentation with the code; keep .common-ground/local/ ignored.
+
+### Quiet task workflow
+
+- The developer task comes first. Use stateless lookup for relevant facts and source paths; default freshness is not checked. Assess actual task-touched paths after edits. Task contexts are optional for deferred additions and aggregate reporting, not required for trivial edits or standalone corrections.
+- Existing facts in the affected scope have standing permission for verified corrections, merges, removals, and tightening. Maintain them quietly while doing authorized work. Never run an unrelated tidy or expand ownership without developer direction.
+- Call cground assess (or task_context assess when using a task) with the files this task actually touched, including new and deleted files. Do not use the whole dirty Git tree as your own work. A no-fact-review result still requires the relevant README/documentation check. Path matching cannot establish semantic independence: follow additional references uncovered in source.
+- Before any knowledge edit, read this policy and every page of each required logical chapter. Use read_knowledge kind review/checklist and chapter with evidence:true to batch records. reviewedAllFacts:true declares review of the whole expected revision; it does not permit a partial skim. prepare_patch accepts an optional taskId and sends replacements/removals only; it retains all other facts and applies the same validation as prepare_update.
+- Keep new verified fact candidates in propose_facts during work. This creates ignored local drafts only. Most new components need only their README; propose a fact only when it changes subsystem reasoning. Do not interrupt the main task for fact admission.
+- After the main task and its checks, finish a task context only if one was started, read all result pages, and consolidate the final message. Present a compact delta of actual corrections already applied in the Git working tree: pillar/chapter, before → after, reason, source links and a keep/reverify recommendation. Present all proposed additions together with their evidence and ask: "Ready to make the following facts available to the team?" Wait for explicit approval before admission. Do not send the developer to knowledge.json or ask them to edit it. Hide unchanged facts, hashes and revision churn. Use task completion details for this task, and cground review (or MCP review) for changes against Git HEAD; --staged selects the index. Read every result page and fetch exact changed quotes with --evidence only when needed. State uncertainty instead of recommending an unsupported approval. For pending pillars/chapters, explain the responsibility, boundaries, ownership paths, rationale and source support before asking for approval. Review summaries reduce presentation tokens; complete chapter and source verification is still mandatory. Do not report routine lookups, checks, no-op reviews, or empty outcomes. Mention unresolved contradictions or failed maintenance explicitly at completion; ask earlier only if needed to complete the main task correctly.
+- After explicit developer approval, read proposed facts (kind proposals), the proposal-review checklist, all required existing chapters, sources and documentation. Then run cground accept-facts TASK_ID REVIEW.json --approve, or the cground MCP accept-facts operation with taskId, review and approved:true. REVIEW.json includes reviews [{chapterId, expectedRevision, reviewedAllFacts:true}] and verification {sourceFiles, documentFiles}. The whole queued batch is validated before one registry write. If approval covers only some entries, use cground drop-facts TASK_ID FACT_KEY... to discard the rest first. A changed draft needs fresh source verification and a new task/approval batch.
+- Pending facts are never used as authoritative knowledge. Dependencies on other pending drafts are not supported; admit the prerequisite after approval first. Approval flags are declarations of developer direction, not a permission or security boundary; never treat a flag as approval.
+- Reuse unchanged responses only within the same live task context. An unchanged/reference response means use the previously returned context, not that source was read. Request refresh:true after context loss, or start a new task for a new agent/session. Live source and dependency fingerprints invalidate reuse. Never cache branch/submodule state as knowledge.
+- Common Ground is invoked by the calling agent, not an autonomous watcher. If unavailable, continue safe main-task work and report unresolved maintenance at completion. Do not claim a correction succeeded when a tool failed. The MCP host controls its own tool approval prompts.
+
+Full-profile tools: start_here, ownership_map, pillar_graph, tidy_plan, review_checklist, list_pillars, list_chapters, read_chapter, read_fact, search_knowledge, review_plan, prepare_update, commit_update, cground.
+Validation: cground validate [all|PILLAR|PILLAR/CHAPTER|PILLAR/CHAPTER/FACT] preserves shared knowledge and refreshes the ignored local Markdown view; omitted targets mean all. It checks structure, exact evidence, and freshness, not semantic truth.
+
+CLI: cground start "build failed"; cground owners --path PATH; cground graph PILLAR; cground tidy TARGET; cground review-checklist CHAPTER --touched PATH.

package/docs/pillar-contract.md

@@ -0,0 +1,98 @@
+# Pillar, chapter, and fact contract
+
+A pillar owns a stable repository responsibility. A chapter owns a coherent subarea within it. Facts belong to chapters and have stable IDs within their chapter. A chapter key is `pillar-id/chapter-id`.
+
+Chapter definitions include a title, scope, exclusions, literal repository-relative file/directory paths defining an authoring boundary. Facts carry their own `sourceScope`, evidence, and `dependsOn` references in `pillar/chapter/fact` form. Scopes must not overlap; fact dependencies must reference an existing fact and cannot refer to themselves. Fact dependencies may cross chapters and pillars. Cycles terminate safely during traversal. New pillars and chapters require developer approval; new pillars also require an uncovered standalone responsibility.
+
+Facts have no count ceiling. A fact statement is limited to 2,000 characters and requires exact source evidence. Its source scope stays within its chapter's authoring boundary, but supporting evidence may cite other repository files. Every evidence file is tracked for freshness independently of ownership and source scope; evidence does not confer ownership. Trailing directory slashes normalize away; traversal, absolute paths and symlinks remain rejected. Matching quotes and hashes establish evidence presence and freshness, not semantic truth.
+
+## Navigate without loading the whole knowledge base
+
+For everyday reads use stateless `cground lookup`; default freshness is not checked, and `--verify` checks selected facts and dependencies. Use `cground assess --touched` after changes, then `--review` only when correction needs complete chapters and verification paths. Task contexts are optional for deferred additions and aggregate reporting. Use `read_knowledge` to retrieve bounded indexes, chapters and full evidence batches. Its kinds map to the detailed operations below. To use these original MCP tool names, select `--profile full`; CLI commands remain unchanged.
+
+Start with the full-profile `start_here` or `.common-ground/START_HERE.md`. `ownership_map` routes registered paths and keyword signals to candidate pillars/chapters. Paths have literal ownership semantics; signal text matches boundary, fact, and evidence tokens and is only a hint. `pillar_graph` groups cross-pillar fact dependencies into directed edges, with example fact references and freshness. It does not infer missing dependencies. All these indexes are paginated.
+
+1. `list_pillars` gives responsibility boundaries and chapter counts.
+2. `list_chapters` gives a pillar's chapter index: titles, scopes, revisions, and fact counts. It does not return facts.
+3. `read_chapter` gives one chapter's fact summaries in pages (default 10, maximum 20). Follow `nextCursor` to read more. Cursors reject content changes between pages.
+4. `read_fact` fetches the evidence for a particular fact. `search_knowledge` offers bounded keyword search, optionally scoped to a chapter.
+
+These response limits do not limit stored facts or chapter counts. Source fingerprints are not dumped into agent read responses.
+
+## Compact patches and task-time admission
+
+`prepare_patch` accepts optional `taskId`, `chapterId`, optional initiating `factIds`, `touchedPaths`, `verification`, optional `tidyId`, and complete chapter review declarations. Each review carries `chapterId`, `expectedRevision`, `reviewedAllFacts: true`, `reason`, optional `maintenance`, `replacements` containing only changed existing full fact records, and `removeFactIds`. Without taskId, preparation creates only the review proposal and requires no task start/finish; corrections are reported directly. With taskId, task completion aggregates committed corrections. The server reconstructs unchanged facts and the complete reviewed ID set before invoking the validator described below. A stale revision, unknown/duplicate edit ID, missing chapter, or incomplete source/documentation declaration rejects the request. Whole-chapter reading remains mandatory.
+
+Use `propose_facts` for new records during a task; these are local drafts excluded from retrieval. After `task_context finish` and explicit developer approval, `cground accept-facts TASK_ID REVIEW.json --approve` validates a batch. REVIEW.json has `reviews: [{chapterId, expectedRevision, reviewedAllFacts: true}]` and `verification: {sourceFiles, documentFiles}`. Read `read_knowledge` kinds `proposals` and `proposal-review` for the complete drafts and required files/chapters. Admission reviews whole owning chapters and linked chapters and rejects changed draft evidence/dependencies/chapters. Correct stale existing facts before staging additions. Discard rejected entries with `cground drop-facts TASK_ID FACT_KEY...`; an altered draft requires fresh review and approval. See [the quiet workflow](quiet-workflow.md).
+
+## Dependency-aware review and update
+
+`Fact A.dependsOn = [Fact B]` means A relies on B. A changed B may invalidate A. Before editing any fact, call `review_plan` for the affected chapter. Pass optional `factIds` to identify initiating facts. Without them, all facts in the initiating chapter are considered. The beta follows fact dependencies and reverse dependents transitively, then requires full review of the chapters containing those facts. It does not traverse unrelated facts merely because they share a chapter. Dense fact graphs can still require broad review. Unknown or ambiguous impact requires developer input.
+
+Read every fact page for each required chapter. Submit one update request with:
+
+- `chapterId`: the chapter that initiated the review.
+- `factIds`: optional initiating fact IDs matching the review plan.
+- `touchedPaths`: repository paths touched by the authorized task. May be empty for fully reviewed citation-only repairs or with a developer-requested `tidyId`.
+- `reviews`: one entry for every required chapter, with `chapterId`, `expectedRevision`, `reviewedFactIds`, `invalidatedFactIds`, the complete replacement `facts`, and a `reason`.
+- `verification`: `sourceFiles` and `documentFiles` that the agent actually opened in this session (or verified as deleted). Get required paths from `review_checklist`, using the chapter IDs and touched paths, and include new evidence sources.
+- `tidyId`: optional local receipt from a developer-requested `cground tidy TARGET`.
+- `reviews[].maintenance`: optional explicit actions on existing facts, each with `factId`, `action` (`correct`, `merge`, `remove`, or `tighten`), and a source-backed `reason`. `merge` also requires the surviving `replacement` fact key.
+
+Every old fact must appear in `reviewedFactIds`, including removed facts. Correct facts stay structurally identical unless explicit maintenance is justified. New facts require separate developer-approved admission. Modified or removed facts must be identified as invalidated. Ordinary updates require changed evidence in a touched path or a changed upstream dependency. Explicit maintenance permits source-verified corrections, merges, removals, and tightening without source drift, within the affected scope or a developer-requested tidy scope. It cannot silently expand into unrelated chapters. Corrections preserve IDs; merges remove the duplicate and require a surviving replacement. All dependent references must be repaired in the same transaction.
+
+A maintenance action triggers full dependency review of that chapter, including dependencies of its other facts. If a narrowed `factIds` plan omitted these, rerun `review_plan` for the full chapter and include all required reviews.
+
+A related chapter whose facts remain true has an empty invalidation list and unchanged facts. It is reviewed but not rewritten. If all facts remain true, preparation returns `noop: true` and updates only disposable local review snapshots.
+
+Preparation validates the entire candidate for every chapter, captures all relevant source snapshots, and fingerprints the registry. Commit also checks snapshots of attested source and documentation files, including files that were missing during review. A new required README invalidates an incomplete request. Commit repeats validation under a writer lock and atomically publishes all changed chapters in one registry replacement. Any changed source or registry invalidates the proposal. Only changed chapters increment revisions and update their source baselines and dependency fact fingerprints.
+
+Unchanged reviewed chapters receive local review snapshots, not shared timestamp churn. Other checkouts independently assess their freshness. `evidence-unchanged` is not a semantic guarantee. An ambiguous fact or dependency impact must be resolved with the developer.
+
+See `examples/demo-monorepo/demo-data/search-update.json` for a complete two-chapter request: search changes, while the result-list fact remains unchanged.
+
+## Session verification and documentation
+
+Notes supplement code reading. Verification requires the agent to open source now; remembered statements or matching cached quotes are insufficient. The software checks declarations and hashes, not whether an external agent read or understood a file. It cannot establish semantic truth or automatically identify every point-in-time claim.
+
+`review_checklist` discovers source evidence, ancestor/local documentation, child documentation, sibling directory READMEs, and local Markdown document links. It skips generated/vendor paths and never follows symlinks or remote URLs. Discovery is bounded to 10,000 entries per scoped scan and 1,000 documents, with a 2 MB file limit; exceeding limits fails explicitly. Root-level changes include root documentation and immediate child READMEs rather than crawling every subsystem. Follow additional code references and non-Markdown documentation references manually and include those verified files in the request. A checklist is not proof of exhaustive semantic impact.
+
+The checklist also accepts no chapter IDs plus touched paths, so README review can proceed when no cached fact is affected. Documentation verification remains mandatory for no-op transactions. A logical chapter is the note to skim in full; sharing one physical JSON registry does not require loading every unrelated pillar into context.
+
+## Read-only validation
+
+`cground validate [TARGET]` defaults to `all` and accepts the same pillar, chapter and fact selectors as tidy. It checks schema and reference integrity globally, then checks exact evidence, source scope hashes and upstream dependency freshness for the selected facts. Fact validation does not expand to unrelated sibling facts or reverse dependents. Matching local review receipts can acknowledge unchanged assertions after source drift, but evidence quotes must still exist. By default no shared records or review receipts are written; CLI and MCP checks refresh the ignored Markdown export. Stale results list affected pillars, chapters and facts. Accepting cleanup with --cleanup y (CLI) or cleanup:true (MCP) creates a scoped local tidyId, and the calling agent must then perform the complete source review and submit corrections.
+
+CLI and MCP operation results show failing rows by default; use `--all-results` or `allResults:true` for passing rows too. The global summary and exit status cover the whole selection even when result rows are paginated. Invalid evidence, unresolved drift, unpopulated chapters and an empty registry yield exit 1. A successful result establishes mechanical consistency, not semantic truth; code and documentation review remain necessary. Cursors reject changes to the registry or validation results.
+
+## Developer-requested cleanup
+
+`cground tidy all`, `cground tidy PILLAR`, `cground tidy PILLAR/CHAPTER`, or `cground tidy PILLAR/CHAPTER/FACT` generates a plan and local receipt without changing shared records. An unqualified fact ID works only when unambiguous. The reserved target `all` includes every chapter, including disconnected pillars. An empty registry returns no receipt. Fact cleanup expands to its whole chapter and linked chapters; pillar cleanup includes all its chapters and their dependencies/dependents. Follow pagination to see the complete plan. Duplicate hints are lexical suggestions requiring source review, never automatic deletions.
+
+The agent performs the work, then submits a complete verified transaction with the `tidyId` and explicit maintenance reasons. The receipt is bound to the registry revision and scope; any shared change requires a new tidy request. MCP `tidy_plan` previews the plan without issuing a receipt; the cground MCP tidy operation issues the same scoped receipt as the CLI. CLI receipts and approval flags record workflow intent, not identity or proof of human authorization against an agent with filesystem access.
+
+## Developer-directed operations
+
+Agents author the records and can execute approved CLI operations. `approve`, `approve-chapters`, `seed`, `admit`, `accept-facts`, `bootstrap`, `seed-batch`, and `migrate` require explicit developer direction and are also exposed as cground MCP operations with approved:true. An approval flag is a workflow convention, not an identity boundary against a process with filesystem access.
+
+`admit` validates the full resulting chapter and all its evidence. Dependent chapters detect changed dependency fact fingerprints; use `review_plan` afterward. Fact dependency changes caused by authorized work can be included in a reviewed transaction; the required reviews cover both the old and new dependency graphs. Moving chapter ownership or moving existing facts between chapters does not yet have a dedicated operator command.
+
+Initial setup authorization distinguishes drafting from publication. “Initialize” or “generate a map” produces a draft by default. An explicit request to “initialize and save/publish the map autonomously” delegates initial publication within that scope, without a redundant approval question. The agent still verifies source, refines responsibility boundaries, runs preflight, and reports saved content and coverage gaps. A changed payload requires fresh verification and preflight; it must remain within the delegation or receive new content approval. A boundary-only or draft-only request never authorizes fact publication. This exception is specific to initial setup; ordinary task additions follow the deferred approval workflow.
+
+## Bootstrap preflight
+
+`cground schema bootstrap` and `cground bootstrap --help --example` expose the combined initial payload: `pillars` plus `batches: [{chapterId, facts}]`. Use `--dry-run` without approval for structural, quote, dependency and source checks. It performs no filesystem writes and returns a content-bound preflight token and tracked file counts per chapter. After content approval of both boundaries and facts, or explicit developer delegation to publish a verified initial map within scope, apply with `--approve --preflight TOKEN`. The registry must still be absent, and every proposed chapter must have a nonempty fact batch. Use boundary-only approve when facts are not ready. The whole batch is published in one atomic replacement under the writer lock, with source and registry rechecks. This is an optimistic filesystem check, not an OS snapshot or proof of semantic verification.
+
+For approved empty chapters, `seed-batch` accepts only `batches` and uses the same preflight/apply protocol. Cross-batch dependencies are validated against the full candidate. Nonempty chapters reject seeding. Failed preflights or conflicting publication leave shared knowledge unchanged. Receipts bind the declared publication to content; `approved.declarationOnly:true` and `approved.humanReviewVerified:false` explicitly disclaim proof of human content review. Approval flags remain declarations, not identity checks. Existing boundary-only approval and single-chapter seed/admit commands remain supported.
+
+Source scope expansion still rejects scans exceeding 10,000 entries. Source hashing streams regular files without the quotation size cap; evidence extraction retains its 2,000,000-byte limit. Supporting evidence outside ownership participates in validation, task assessment, dependency freshness and review checklists.
+
+CLI JSON payloads support `--stdin` or `-`. `cground schema OPERATION` returns the CLI payload schema by default; `--both` also includes the MCP argument schema (seed/admit/propose-facts take a facts array). Mutation operations approve/approve-chapters/seed/admit return counts, changed IDs, validation scope and output path; `--verbose` or MCP `verbose:true` returns the original full object.
+
+## Schema v1 migration
+
+Run `cground migrate --approve`, then `cground init` to update the managed instructions. Each old pillar becomes a pillar with one `overview` chapter. Facts, source hashes, scope, and revision are preserved; each fact derives its source scope from its evidence paths, and fact dependencies start empty. No dependency relationships are invented. A backup goes to `.common-ground/local/pre-v2-migration.json`. Migration is atomic and idempotent; it does not migrate pending local update proposals.
+
+Citation-only repairs may use empty touchedPaths without a tidyId: only evidence may change; the fact ID, statement, sourceScope and dependsOn must remain unchanged. Supply a verified reason, read every required chapter, attest source/documentation verification and the expected revisions. Publication rechecks source and registry conflicts. Use review-plan and review-checklist for the selected chapter; do not invent touched paths.
+
+For a chapter owning `src`, keep `sourceScope: ["src"]`. A supporting quote in `shared/config.ts` belongs in `evidence: [{"path":"shared/config.ts","quote":"mode = 1"}]`; external evidence is tracked automatically without expanding chapter ownership.

package/docs/quiet-workflow.md

@@ -0,0 +1,98 @@
+# Quiet maintenance and context use
+
+The developer asks for an ordinary coding task. Their agent uses Common Ground as needed, corrects verified existing facts within the affected scope, and mentions meaningful knowledge changes once at completion. There is no autonomous model, watcher, or command capture inside Common Ground. An MCP host still controls its permission prompts.
+
+Before bootstrap approval, `task_context start` (or `cground task start`) returns `state: "bootstrap-required"`, the proposal path and a compact next-action object, with no `taskId` and no local task writes. Continue from source, verify boundaries and facts, establish content approval or explicit delegation to publish the initial map within scope, and use `cground bootstrap PLAN.json --dry-run` followed by approval-directed `--approve --preflight TOKEN` for one atomic initial transaction. The separate `cground approve .common-ground/local/bootstrap.json --approve` workflow approves only boundaries; `seed-batch` can populate the approved empty chapters after fact approval. Start again afterward. Do not assess, propose facts or finish without a task ID. If neither registry nor proposal exists, the state is `not-initialized` and the next step is `cground init`. Invalid registries remain errors.
+
+## Default: stateless lookup and proportional assessment
+
+Use `cground lookup --path PATH` or a short query. Up to five fact statements and source locations are returned, with no source hashing or local writes by default. Freshness is explicitly `not-checked`; `--verify` checks only selected facts and their upstream evidence/source scopes. Verification compares stored source baselines and does not reuse local whole-chapter review receipts. Each compact result contains its fact ID, statement, source paths, relevance and freshness. `--verbose` adds `matchReason`, `matchedPaths`, `matchedTerms`, `unmatchedTerms`, and `queryCoverage` (matched/total terms, or null for path-only lookup). `relevance` distinguishes `ownership-only`, `partial-query`, `weak-match`, and `matched`; these are lexical/path categories, not confidence scores or semantic guarantees. Weak coverage leads with “No direct answer found,” then navigation hints and partial matches. A separate `source-search` suggestion remains unexecuted until the agent chooses to search explicit source paths; its results are labeled live source evidence. See [the source-search guide](../SETUP.md#search-live-source-when-knowledge-is-thin). Matching quotes and hashes still do not establish semantic truth.
+
+After editing, use `cground assess --touched PATH1,PATH2` for the task's actual changed paths. Empty paths mean no work; unowned or unchanged source means no fact review. The response includes only focused local/ancestor documentation, without recursively following unrelated documentation links. Source changes return candidate claims to inspect. Missing or unreadable tracked sources require attention, never silent success.
+
+If a claim needs correction, `assess --review` returns complete affected/linked chapters, revisions, facts with evidence and source/documentation paths in one paginated package. It also supports verified maintenance when the source is unchanged but an existing claim is wrong. The package identifies each initiating review-scope and its required chapters; prepare unrelated scopes separately. Follow every page and verify source before calling `prepare-patch` without a taskId. Preparation still requires complete reviews; publication still rejects source, documentation and registry conflicts. Report the correction directly; no task start or finish is needed.
+
+CLI and both MCP profiles expose `lookup` and `assess` through the cground operation catalog. Existing task workflows remain compatible. Ordinary reads without a task skip cache-context construction; task reads deduplicate source hashes within each request while recomputing them on later requests.
+
+## Optional task context
+
+1. When deferred additions or aggregate correction reporting are useful, call `task_context` with `action: "start"` and known `paths` or a short `signal`. Keep the returned `taskId` for this task. Do not create a task for every chat message.
+2. Read relevant knowledge with `read_knowledge`. A returned owner already identifies a chapter; an additional pillar-index round trip is optional. Use `kind: "chapter", target: "web-components/search", evidence: true` for complete fact batches, and open their actual source in this session. Ordinary navigation need not read unrelated chapters.
+3. Do the coding work. Call `task_context` with `action: "assess"` and the actual paths this task touched. Include new/deleted files. Do not claim another developer's dirty files. This returns affected chapters and source/documentation paths, or `no-fact-review` with documentation paths. Follow all pages. Path/scope matching cannot detect undeclared semantic connections; follow references found in source.
+4. Before a knowledge edit, read `.common-ground/POLICY.md`, every fact page in each required chapter, and source/README/reference files. `kind: "review"` accepts a chapter or qualified fact ID; `kind: "checklist"` discovers required file paths. Maintenance actions can expand the required scope to other facts in the maintained chapter. The validator reports omitted chapters.
+5. Use `prepare_patch` and `commit_update` for verified corrections. The old full `prepare` CLI and `prepare_update` full-profile tool also work, but only task-associated patches participate in the automatic task completion report.
+6. Queue any worthwhile additions with `propose_facts`. Do not add an inventory entry just because a new component exists. Local library details belong in the library README.
+7. Finish the main task and its checks. Call `task_context` with `action: "finish"`, follow its pages, and consolidate the final response. `notification: "none"` means no Common Ground message is needed. `summary` names committed corrections; `approval-required` includes pending new facts; `attention` includes stale drafts, an uncommitted review, or a correction changed since publication. An unrelated uncertainty is flagged, not turned into unsolicited cleanup.
+
+Example completion: “Applied one CI/CD correction: retry limit 2 → 3, verified in ci/build.yml. Recommend keeping it. One new fact is pending approval.” Use real source links and the verified reason for the actual repository. Corrections do not need a second authorization; additions still ask “Ready to make the following facts available to the team?” Never tell the developer to read or hand-edit knowledge.json.
+
+`finish` returns only changed facts with before/after fields, the submitted reason, evidence paths, a recommendation, and whether the current record/evidence needs another review. Repeated changes within a task collapse into a net change; reverting to the original fact produces no correction notification. Local receipts from older versions lack this detail and are explicitly flagged for review. This is a presentation aid: exact quotes, freshness and review declarations do not prove semantic truth.
+
+Use `cground review [TARGET]` or the MCP `review` operation to compare current knowledge with Git HEAD, including changes made outside this task. `--staged`/`staged:true` selects the Git index. It reports pillar/chapter boundary changes and fact changes; it omits unchanged records, source hashes, revisions and dependency fingerprints. All additions/deletions are explicit, including initial setup. Follow every page. Exact changed evidence quotes are opt-in with `--evidence`/`evidence:true`; otherwise the summary reports changed evidence and its paths. This command never marks anything reviewed, approves it, or writes files. The agent must establish the reason and recommendation from source, not infer them from a diff. Uncertainty blocks approval, not the main task unless relevant.
+
+## Compact correction request
+
+This example applies to the synthetic demo after changing `SEARCH_MIN_LENGTH` to 3. Replace the sample UUID with the real task ID and verify current revisions and all files before submitting it. Read the unchanged Results chapter in full too.
+
+```json
+{
+  "taskId": "00000000-0000-4000-8000-000000000000",
+  "chapterId": "web-components/search",
+  "factIds": ["search-minimum"],
+  "touchedPaths": ["packages/ui/search.ts"],
+  "verification": {
+    "sourceFiles": ["packages/ui/search.ts", "packages/ui/results.ts"],
+    "documentFiles": ["AGENTS.md", "packages/ui/README.md"]
+  },
+  "reviews": [
+    {
+      "chapterId": "web-components/search",
+      "expectedRevision": 1,
+      "reviewedAllFacts": true,
+      "reason": "The authorized change raises the verified minimum from 2 to 3.",
+      "replacements": [{
+        "id": "search-minimum",
+        "statement": "The search component exports SEARCH_MIN_LENGTH as 3.",
+        "evidence": [{"path": "packages/ui/search.ts", "quote": "export const SEARCH_MIN_LENGTH = 3;"}],
+        "sourceScope": ["packages/ui/search.ts"],
+        "dependsOn": []
+      }]
+    },
+    {
+      "chapterId": "web-components/results",
+      "expectedRevision": 1,
+      "reviewedAllFacts": true,
+      "reason": "Read all facts and source; Results still uses the shared threshold."
+    }
+  ]
+}
+```
+
+Unchanged records are reconstructed server-side. `reviewedAllFacts: true` attests the whole expected revision; it is neither proof of reading nor permission to skip reading. Use `removeFactIds` for deletions. Citation-only repairs may use empty touchedPaths without a tidyId: only evidence may change; the fact ID, statement, sourceScope and dependsOn must remain unchanged. Supply a verified reason, read every required chapter, attest source/documentation verification and the expected revisions. Publication rechecks source and registry conflicts. Use review-plan and review-checklist for the selected chapter; do not invent touched paths.
+
+Other explicit maintenance without directly changed evidence needs a reasoned `maintenance` action (`correct`, `merge`, `remove`, or `tighten`) and relevant touched paths, or a developer-requested `tidyId`. See [the record contract](pillar-contract.md) and published `patch.schema.json`.
+
+## Deferred additions
+
+`propose_facts` takes `taskId`, `chapterId`, and a `facts` array with the existing fact schema. It validates evidence and ownership, and stores drafts under ignored `.common-ground/local/`. Re-proposing the same ID replaces its local draft; it never overwrites a shared fact. Dependencies must already exist in shared knowledge. Stage additions after known corrections to avoid invalidating drafts with those corrections.
+
+After finish and explicit developer approval:
+
+- Read all pages of `read_knowledge` with `kind: "proposals"` and the task ID.
+- Read all `kind: "proposal-review"` pages for required whole chapters, revisions, sources and documents. Open these files now. If existing facts need correction, resolve that first and reverify/re-propose stale additions in a new task.
+- Have the agent create `REVIEW.json` with `reviews: [{"chapterId": "pillar/chapter", "expectedRevision": 1, "reviewedAllFacts": true}]` for every required chapter, and `verification: {"sourceFiles": [...], "documentFiles": [...]}`.
+- Run `cground accept-facts TASK_ID REVIEW.json --approve`. This validates the entire batch and writes one atomic registry replacement. Only chapters receiving additions increment revisions. It rejects unfinished tasks, uncommitted maintenance, missing reviews, stale drafts and invalid evidence/dependencies.
+
+If only some additions are approved, first discard rejected drafts with `cground drop-facts TASK_ID PILLAR/CHAPTER/FACT...`. A flag records developer direction; it cannot prove authorization against an agent with filesystem access. Legacy developer-directed `seed` and `admit` remain available for operator/bootstrap use, but agents must follow this deferred workflow during normal coding tasks.
+
+## Context controls and limitations
+
+- The default MCP profile has six tools. `--profile full` retains the original thirteen plus cground for compatibility; all CLI workflows are available through MCP.
+- Generated `AGENTS.md` recommends stateless lookup/assessment and carries essential instructions and links to the detailed policy, loaded before edits.
+- Chapter evidence pages have a 12,000-character soft record budget and a 20-record maximum. At least one complete record is returned even if unusually large; evidence and dependencies are never silently cut off. There is no stored fact-count limit.
+- With a task ID, repeated unchanged reads/assessments return a short `unchanged` reference. Reuse it only if the original response is still in the agent's context. Use `refresh: true` to resend after context loss, and a new task for a new agent/session. Source and dependency changes invalidate relevant reuse; documentation changes invalidate checklist/assessment reuse. No live branch/submodule state is cached.
+- Source verification, mandatory correction, full affected-chapter reviews and README checks remain required. Byte reductions do not measure semantic quality or total billed tokens. The engine still parses the full registry and hashes source; huge chapters/dense dependencies remain expensive.
+- `finish` records the task boundary; later code work needs a new task. Stale drafts require re-proposal and a new finish/approval batch. Abandoned local tasks and proposals can be removed after confirming no agent or review still needs them. Do not delete the writer lock while a writer is active.
+- A prepared correction that fails to commit remains visible as attention at finish. If publication succeeds but a later local bookkeeping write fails, inspect the Git diff before retrying or discarding the local receipt; do not claim nothing happened. Common Ground cannot automatically report corrections made through unrelated operator commands or direct file edits.
+
+Run `npm run measure:context` to reproduce comparisons of serialized UTF-8 bytes. This measures current full/compact tool definitions, generated entry guidance against the pre-workflow baseline, one corrected record in a synthetic 300-fact chapter, and repeated retrieval. Actual tokenizer, host caching and billing behavior vary.

package/docs/releases.md

@@ -0,0 +1,157 @@
+# npm and GitHub Releases distribution
+
+Common Ground publishes `@nazty_labs/common-ground` to npm and the same package archive to [GitHub Releases](https://github.com/naztylabs/common-ground/releases). Tag-triggered GitHub Actions checks the package before publishing through npm trusted publishing (OIDC).
+
+Consumers still need Node.js 22+ and npm. The archive contains compiled JavaScript and schemas, but not bundled dependencies. npm downloads those dependencies from the configured registry at installation time. Normal runtime operation is local.
+
+## 0.5.1
+
+This patch addresses feedback from initial setup, build/release lookup and technical format queries:
+
+- Short query tokens such as CI require token boundaries, and technical versions such as `1.4` stay intact. Lookup and search downweight repository-wide terms, prioritize distinctive concepts and rank direct evidence-path matches first.
+- Lookup leads weak coverage with “No direct answer found” and separate, bounded chapter/ownership hints from the registry. Compact results show each statement, source list, relevance and freshness once; `--verbose` restores matching diagnostics. Hints remain unverified even with `--verify`; default lookup performs no filesystem scan or knowledge write.
+- A separate `source-search` command and MCP operation provide bounded searches of explicit source paths. Results are labeled live source evidence, with file/line excerpts and scan limits. Weak lookup coverage suggests this fallback without executing it or storing new facts.
+- Initial setup distinguishes draft requests from explicit delegation to save/publish the source-verified initial map. Existing delegation needs no second approval question. Preflight receipts explicitly state they do not prove human content review; source and registry conflict checks remain mandatory.
+- Initialization reports completed, skipped, failed and pending steps. Hook permission failures are advisory; other failures return `INIT_INCOMPLETE` with the underlying error and retry instructions. `init --skip-hook` / MCP `skipHook:true` skips installation. Retries preserve existing knowledge and edited bootstrap drafts.
+- Discovery separates raw signals, responsibility suggestions and rationale. Complete homogeneous subtrees can use directory boundaries; mixed, excluded or truncated trees retain narrower hints. Incomplete ownership is prominent, and delivery prompts cover versions, release triggers, artifacts and publication without inferring facts.
+- A format-architecture review prompt requires several distinct implementation-role filenames and a format specification. It asks about verified relationships, repeated navigation needs and existing ownership before any entry is proposed.
+- START_HERE provides a self-contained bootstrap path and links to detailed maintenance policy, reducing repeated guidance.
+- README introduces the framework and a short agent-led quickstart; the linked, packaged SETUP.md holds detailed commands, workflows, configuration and troubleshooting.
+
+Upgrade with the 0.5.1 archive, run `cground refresh-guidance`, and restart the MCP server. Schema-v2 registries remain compatible. Lookup's default response is now compact: consumers needing per-result matching diagnostics must request `verbose:true` or `--verbose`, and navigation kind/freshness live on the shared navigation object. Lookup ranking and discovery candidate paths intentionally change. `check` still establishes mechanical consistency, not exhaustive topic coverage. Synthetic regression tests cover the feedback scenarios through CLI and both MCP profiles.
+
+## 0.5.0-beta-2
+
+- Lookup explains evidence, source-scope, ownership and query matches, with matched/unmatched terms and explicit lexical coverage limits.
+- CLI errors distinguish missing/unreadable input, malformed JSON, invalid option values, unknown commands, invalid registries and source/registry conflicts. Recovery guidance and affected fields match the failure.
+- Healthy doctor and guidance checks return `next: null`; successful bootstrap suggests lookup with optional task contexts.
+- Guidance refresh reports changed and unchanged files, including idempotent reruns.
+
+## 0.5.0-beta-1
+
+- Doctor detects outdated managed guidance; `refresh-guidance` updates instructions without changing knowledge, MCP configuration or hooks.
+- Fully reviewed citation-only corrections work without source edits or a tidy request, retaining reason, revision, evidence and publication safeguards.
+- `--json` errors have a stable envelope on stderr with code, message, affected fields and recovery guidance.
+- Fact schemas and help distinguish owned source scope from cross-chapter supporting evidence.
+- Discovery excludes more dependency and editor/agent configuration directories, reports skipped paths, and accepts explicit `scan --exclude PATH1,PATH2` boundaries.
+- Schema output defaults to the CLI payload schema. Use `schema OPERATION --both` (MCP `both:true`) for the additional operation schema.
+
+## 0.5.0-beta.0
+
+- Stateless lookup returns a few relevant facts and source paths; optional verification checks selected facts and dependencies. Source-aware assessment distinguishes unchanged source from claims needing review, with complete review packages on request.
+- Standalone corrections accept prepare-patch without a task context while retaining full review and publication safeguards. Existing task contexts remain available for deferred additions and aggregate reporting.
+
+- CLI schemas, JSON examples and stdin input make setup discoverable without inspecting implementation code.
+- Bootstrap and multi-chapter seeding support no-write preflight, source-file counts and atomic publication guarded by a content token and developer approval.
+- Supporting evidence can cross chapter ownership while remaining tracked for freshness. Source hashing streams large files independently of quotation size limits.
+- Mutation receipts are compact by default; use `--verbose` for full objects. Validation shows failing rows by default; use `--all-results` for passing rows. MCP equivalents are `verbose:true` and `allResults:true`.
+- Discovery recognizes C/C++ projects, skips more vendored trees and prioritizes conventional first-party directories. Setup guidance is shorter and state-specific.
+
+Schema-v2 registries remain supported. Integrations that consume full mutation objects or passing validation rows must opt in to the corresponding options. Run `cground init` after upgrading to refresh managed guidance.
+
+## 0.4.1-beta.0
+
+- `cground review` presents meaningful pillar, chapter, and fact changes against Git HEAD, with staged and structured-output options. When changes exist, the CLI recommends reviewing through a coding agent to verify source and explain what to keep or approve.
+- Task completion gives compact before/after corrections, reasons, source links, and keep/reverify recommendations. Verified corrections are applied before the summary; additions and ownership changes still require developer approval.
+- Init and hook messages direct developers to agent-led review instead of editing the shared JSON.
+
+## 0.4.0-beta.0
+
+- A complete Markdown reference lives in ignored `.common-ground/local/knowledge.md`, created on init and refreshed by validate, tidy, and shared knowledge updates only when content changes.
+
+- `cground validate` checks all knowledge by default, or a selected pillar, chapter, or fact. It preserves shared knowledge, refreshes the local Markdown view, and returns nonzero for invalid, stale, or unpopulated knowledge.
+- `cground tidy all` creates a review scope covering the entire registry without changing facts.
+
+- Fact statements allow up to 2,000 characters for conditions, behavior, and consequences, retaining exact evidence requirements. Schema v2 records remain compatible with this version; older clients with the 320-character limit cannot read longer statements.
+- Initialization installs advisory pre-commit checks by default when no existing hook manager owns the entry point. `cground hook mute` and `unmute` control notifications locally without blocking commits or changing facts.
+- Init output is a short summary and review link; `--json` preserves the full response for integrations.
+- Agents explicitly present proposed facts and evidence for team-sharing approval; corrections are summarized in chat with before/after, reasons and source links.
+
+## One-time setup
+
+1. Commit and push `.github/workflows/release.yml`, the packaging script, and the related project changes before tagging.
+2. Ensure GitHub Actions is enabled for the repository. Repository or organization policy must allow the workflow's `contents: write` permission so it can create a release and upload assets.
+3. Create the package on npm with an initial manual release if it does not exist yet. Run the release checks first, then publish the generated archive with `npm publish ./release/nazty_labs-common-ground-0.5.1.tgz --access public`. Authenticate with your npm account and 2FA. The next automated release must use a new version.
+4. In the npm package settings, add a GitHub Actions trusted publisher: GitHub owner `naztylabs`, repository `common-ground`, workflow filename `release.yml`, and no environment name. Enable direct `npm publish` permission. The npm organization is `nazty_labs`; the GitHub owner is `naztylabs`.
+5. Allow the workflow’s `id-token: write` permission. No npm token secret is needed. GitHub release uploads use the built-in `GITHUB_TOKEN`. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+The workflow runs on a GitHub-hosted Ubuntu runner, uses `.nvmrc`, and triggers only for pushed tags beginning with `v`. The tag must exactly equal `v` followed by the version in `package.json`. The versioned commit must contain the workflow.
+
+## Build and inspect locally
+
+From the repository root:
+
+```sh
+nvm use
+npm ci
+npm run release:pack
+```
+
+This runs tests and the synthetic demo, regenerates the compiled runtime and JSON schemas, and writes these files for the current version:
+
+```text
+release/nazty_labs-common-ground-0.5.1.tgz
+release/nazty_labs-common-ground-0.5.1.tgz.sha256
+```
+
+Inspect the archive with `tar -tzf release/nazty_labs-common-ground-0.5.1.tgz`. The package includes `dist/`, `schemas/`, documentation, its manifest and license. Repository knowledge, local state, tests, source fixtures, and `node_modules/` are excluded. Local packaging does not publish remotely.
+
+## Publish the current version
+
+After committing all intended changes, create and push the matching tag:
+
+```sh
+git tag -a v0.5.1 -m "Common Ground 0.5.1"
+git push origin v0.5.1
+```
+
+Pushing the tag publishes the release automatically after the checks pass. Follow the **GitHub release** run in the repository's Actions tab. The workflow verifies the installed CLI version, publishes the tested archive to npm, then uploads the archive and checksum and generates release notes. Stable versions use npm’s `latest` tag; prerelease versions use `next`. Versions containing a prerelease suffix, such as `-beta.1`, are marked as prereleases and are not marked Latest.
+
+For a subsequent beta, start with a clean working tree and run:
+
+```sh
+npm version prerelease --preid=beta --no-git-tag-version
+```
+
+This updates `package.json` and `package-lock.json`. The CLI and MCP server read the package version automatically. Update version-specific installation examples, inspect and commit the changes, then tag and push that new version. Do not reuse an already published version or move its tag.
+
+If npm publishing succeeds but GitHub release creation fails, finish the GitHub release manually using that run’s version; rerunning cannot republish the same npm version.
+
+If validation or packaging fails before release creation, fix the problem and publish a new version, or rerun a failed job if the cause was transient. Release creation intentionally fails when the release already exists; it does not overwrite published assets. If a failed upload leaves a draft, inspect and finish that draft in GitHub instead of expecting a rerun to replace it.
+
+## Install a release
+
+Download the `.tgz` asset using a browser. GitHub's **Source code (zip)** and **Source code (tar.gz)** downloads are source snapshots, not the built npm package. From the download directory:
+
+```sh
+npm install -g ./nazty_labs-common-ground-0.5.1.tgz
+cground --version
+```
+
+Optionally download the corresponding `.sha256` asset and check it on Linux before installing:
+
+```sh
+sha256sum --check nazty_labs-common-ground-0.5.1.tgz.sha256
+```
+
+With GitHub CLI installed and, for a private repository, authenticated:
+
+```sh
+gh release download v0.5.1 --repo naztylabs/common-ground \
+  --pattern 'nazty_labs-common-ground-0.5.1.tgz*'
+```
+
+Downloading first and installing the local file also avoids npm version differences in permissions for remote tarball URLs. Public release assets can be downloaded without a GitHub account; private repository assets require access.
+
+## References
+
+- [npm pack](https://docs.npmjs.com/cli/v11/commands/npm-pack)
+- [npm install](https://docs.npmjs.com/cli/v11/commands/npm-install)
+- [GitHub CLI release creation](https://cli.github.com/manual/gh_release_create)
+- [GitHub Actions token permissions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication)
+
+Beta 0.3.0 also exposes every CLI workflow through the discoverable `cground` MCP tool in both profiles. Scoped check/validate report affected IDs and offer developer-requested cleanup. The check JSON format now matches validate instead of returning a chapter-status array; automation should read `valid`, `summary`, and `affected`. Cleanup acceptance issues a review plan, not completed fact changes.
+
+## 0.4.0-beta.0 developer-experience audit
+
+Every command now supports `--help`/`-h`, including task and hook subcommands, without executing it. CLI and MCP use shared operation handlers; check and validate are aliases. Terminal checks are concise; scripts retain JSON and `--json` disables interaction. Unknown/unsupported flags and extra/missing arguments now fail explicitly. Use `cground export` to regenerate the local reference. No new runtime dependency was added. See [the audit](audit-0.4.0.md) for findings, retained tradeoffs, and startup measurements.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@nazty_labs/common-ground",
+  "version": "0.5.1",
+  "description": "An open-source framework for shared, evidence-backed repository knowledge across coding agents",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/naztylabs/common-ground.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "cground": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "README.md",
+    "SETUP.md",
+    "LICENSE",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run schema",
+    "demo": "npm run build && node scripts/demo.mjs",
+    "schema": "npm run build && node scripts/schema.mjs",
+    "release:pack": "npm test && npm run demo && node scripts/release-pack.mjs",
+    "measure:context": "npm run build && node scripts/measure-context.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "jsonc-parser": "^3.3.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "contributors": [
+    {
+      "name": "Nazty Labs"
+    }
+  ]
+}

package/schemas/admission.schema.json

@@ -0,0 +1,75 @@
+{
+  "$ref": "#/definitions/admission",
+  "definitions": {
+    "admission": {
+      "type": "object",
+      "properties": {
+        "reviews": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "chapterId": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]*\\/[a-z0-9][a-z0-9-]*$"
+              },
+              "expectedRevision": {
+                "type": "integer",
+                "exclusiveMinimum": 0
+              },
+              "reviewedAllFacts": {
+                "type": "boolean",
+                "const": true
+              }
+            },
+            "required": [
+              "chapterId",
+              "expectedRevision",
+              "reviewedAllFacts"
+            ],
+            "additionalProperties": false
+          },
+          "minItems": 1
+        },
+        "verification": {
+          "type": "object",
+          "properties": {
+            "sourceFiles": {
+              "type": "array",
+              "items": {
+                "allOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                ],
+                "description": "Repository-relative path without traversal or symlinks; trailing directory slashes normalize away."
+              }
+            },
+            "documentFiles": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/admission/properties/verification/properties/sourceFiles/items"
+              }
+            }
+          },
+          "required": [
+            "sourceFiles",
+            "documentFiles"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "reviews",
+        "verification"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}