@c4a/context-cli 0.7.5 → 0.7.9

package/providers/context/resources/procedures/homogeneous-source-review.md

@@ -0,0 +1,123 @@
+---
+id: procedure.homogeneous-source-review
+kind: procedure
+mediaType: text/markdown
+---
+
+# Review large homogeneous source groups before bulk work
+
+Apply during source exploration, the work-start report, Provider selection and
+before advancing into parser preparation, including an existing workspace's
+resume. Reuse confirmed decisions; this is the existing conversational scope
+review, not a new CLI approval flag or a semantic classifier in the CLI.
+
+## Find a real group, not just a large repository
+
+More than 100 files in a candidate group triggers a bounded homogeneity check,
+not automatic exclusion or a count-only stop. Use the supplied source inventory
+or authorized read-only file listing. Do not run symbol extraction to discover
+whether symbol extraction is needed. Record the source/repository and pinned
+revision, actual module/directory boundaries, counted paths, bytes when available,
+and representative file paths. Distinguish tracked source, captured copies,
+generated files and externally resolved dependencies; a path containing another
+repository name does not prove a new external checkout.
+
+Read a small diverse sample across relevant subdirectories, sizes and naming
+families. Establish a shared structure, generator, schema, repeated role or
+mechanical pattern from content. Examples include IDL definitions, schema-based
+configuration, generated clients/models, repeated migrations, and ordinary
+handwritten adapters or handlers with the same structural pattern. A common
+extension, a directory label, age, or boilerplate header alone is not sufficient.
+Do not call every TypeScript file homogeneous or treat all configuration as
+low-value. If samples differ substantially, split by evidenced characteristics
+or proceed normally; report uncertainty instead of claiming full inspection.
+
+For a confirmed group above 100 files with an unsettled treatment, pause before
+dependent bulk reading/parsing. Combine all currently known groups into one scope
+proposal. Do not ask per file or create 100-file approval batches. Groups below
+this threshold can still warrant discussion when their size or cost is material;
+file count is not a memory safety limit.
+
+## Present one concrete choice per group
+
+Show a compact directory tree and table with:
+
+- Repository/source, revision, exact directory or file-set boundary and whether
+  it is the whole source or a subset; physical file count versus distinct items.
+- Observed shared characteristics and two or three linked sample files with
+  short descriptions of their content. State sampling coverage honestly.
+- Connection to this task's questions, known callers/consumers and unresolved
+  dependencies; distinguish a recommendation from a confirmed exclusion.
+- Likely output, reading/parsing cost and the evidence for any estimate.
+
+Offer these treatments together, recommending one based on the user's task:
+
+| Choice | Consequence |
+| --- | --- |
+| Full indexing | Normal extraction, planning and writing over the selected group. It may yield multiple articles. Explain the extra work without asserting it is always low-value. |
+| Overview and lookup entry | List the boundary, inspect representative content and entrypoints, and plan one overview with directory/file lookup routes and concrete search instructions. Defer detailed extraction of the rest. Never first parse every file and then summarize it. |
+| Omit the source | Remove the entire source from this task's required production scope through the supported requirement/configuration flow. Do not delete captured files, caches or accepted knowledge. |
+| Exclude this subset | Keep the repository but exclude the explicitly selected directories/files from production scope. Clarify whether any are still required as supporting dependencies. |
+
+Only show subset exclusion as applicable when it is a subset; do not make the
+user distinguish two identical choices for a whole-source group. Users can give
+one policy for several groups or different choices per group. Record the exact
+scope of a shared answer. Generic managed/no-review authorization, source-read
+permission and permission to skip report feedback do not select a treatment.
+Reuse an explicit applicable treatment or explicit delegation of this scope
+choice. Otherwise ask and wait; elapsed time is not approval. Independent work
+outside the affected scope can continue if the current workflow supports it.
+
+Do not invent "one minute per group", token savings or a cost-benefit score.
+When comparable measurements exist, state the measured phase, input size,
+cold/cache conditions and uncertainty; separate parsing from Agent reading,
+writing and review. Without them state that duration is not reliably estimated.
+
+## Carry the answer into real execution
+
+Update the existing work-start report with the group boundaries, sample evidence,
+chosen treatment, user authorization and next action. Reuse that report and the
+conversation on retry; it is not itself a runtime execution receipt. Persist
+scope changes only through the existing requirement/configuration Actions and
+schemas. Exact exclusions use repository-relative paths, not invented wildcard
+fields. Retain unrelated requirements and accepted work. A source required by
+another requirement may remain active; disclose that instead of promising it
+will no longer be parsed.
+
+For full indexing, continue the current Route. For overview, resolve the actual
+production boundary and suitable existing Provider before proceeding: the
+selected entrypoints and samples support the overview; the remaining group is
+for lookup, not an exhaustive production target. Use directory-scoped routes
+when a per-file list would dominate the article. Include purpose, observed
+patterns, representative examples, source version, lookup/search procedure,
+limits of what was read and the next evidence request. Keep symbol/API facts
+unread as unknown. Do not forge a complete deep inventory, hand-write approved
+knowledge, or silently relabel the full scope as a summary profile.
+
+Check the resulting configuration before a command that prepares parser facts.
+In particular, contract-led profiles can still parse their entire registered
+boundary before article planning. Merely asking for one article does not reduce
+that work. If the current configuration route cannot express the selected
+narrow boundary or overview treatment, describe that concrete limitation and
+keep the affected bulk action paused; do not revert to full indexing or edit
+runtime receipts to make the choice appear applied.
+
+On continuation, unchanged groups with explicit decisions do not prompt again.
+New large groups, expansion beyond the agreed directory/file set, or changed
+characteristics/cost that invalidate the decision warrant a focused amendment.
+A content hash change within the agreed scope is not by itself a new question.
+If first discovered while a command is running, report the observation and
+safely interrupt the owned process when possible, preserve state and consult
+the latest Route before continuing. Do not launch a competing run or delete
+state. An uninterruptible stage must be reported, not called paused already.
+
+## Report progress with the correct denominator
+
+Keep source capture, module exploration, parser capability entries, file batches
+and delivered articles separate. A seven-file JSON entry does not mean that an
+IDL repository now contains seven relevant files. Report both the source and
+capability for each count; merging four results is not four completed modules.
+Only use completed/total modules when module boundaries and their completion
+have been observed. Before that, say module boundaries are being identified.
+Never infer percentage or scope reduction from time or RSS. RSS is not Node heap
+usage and being below a previous failure measurement does not establish safety.

package/providers/context/resources/procedures/knowledge-maintenance.md

@@ -0,0 +1,68 @@
+---
+id: procedure.knowledge-maintenance
+kind: procedure
+mediaType: text/markdown
+---
+
+# Maintain knowledge while production continues
+
+Use `context task maintain --input <file|-> --format json` to register multiple
+approved pages or an approved-output rebuild. The machine-readable input is
+[maintenance input](../../schemas/knowledge-maintenance-input.schema.json). This accepts a request; it does
+not discard the current task or immediately rewrite a page.
+
+```yaml
+id: clarify-existing-guides
+operation: revise
+timing: after-batch
+targets:
+  - path: knowledge/guides/overview.md
+    instruction: Clarify the selected explanation using its existing sources.
+```
+
+Reuse the same id and input when retrying a registration. A changed request uses
+a new id; cancel a pending request with `context task cancel-maintenance <id>
+--format json` before replacing it. Do not manufacture repeated requests from
+the same user feedback.
+
+`operation` selects `revise`, `regenerate`, or `rebuild`. Rebuild has no targets;
+it packages approved content without completing the production task. It cannot
+repair a table stored in an existing page. To publish newly accepted Author
+results earlier, use the current Route’s `delivery.request.command`
+(`context run --deliver --format json`) instead of a rebuild request. Finish
+the current Author batch and follow composition, Review, close and build, then
+resume production. Regenerate prepares the currently
+supported programmatic API blocks from the selected registered code material,
+even when its source version is unchanged. Follow the resulting Author Route,
+select relevant program tokens and retain unrelated prose. This is not a
+universal rerun of every business Composer. If a required program/material is
+not available, report the exact gap; do not hand-write generated rows.
+
+Ordinary revisions need no source reacquisition or parsing. New factual notes
+and conversation summaries still use the normal source preparation and scope
+adjustment procedures. A regenerated table does not advance a whole-source
+processed baseline. A changed upstream version still requires source impact
+assessment, including other affected approved pages and new topics.
+
+`after-batch` waits for the current delivery boundary. Use `priority` when the
+user asks to handle the correction first: the Graph requests early delivery
+of complete pages, retaining ordinary Review gates. Never interrupt a running
+submission, silently approve its drafts, or start parallel workspace writers.
+Inspect `maintenance` in status for the active request, pending targets and
+the actual waiting condition. Continue the original task only within the user's
+existing authorization; registration is not new authority to publish it.
+
+The transition command is supplied by the current Route. Do not invoke it with
+a remembered revision. On a preparation failure the request remains visible;
+repair the named materials and retry the current Route, or cancel that request
+before it creates a draft. Active drafts use the current revision/Review path;
+queue cancellation does not silently roll them back. To explicitly discard its
+unfinished drafts, first read `context task maintenance-status --format json`,
+then use `cancel-maintenance <id> --discard-revision <returned revision> --format
+json`. Already approved pages are retained and rebuilt; this is not a rollback
+of delivered knowledge. Shared-source adjustments wait until this maintenance
+batch is finished or cancelled, then use the production task's source adjustment
+route. If status says `target-still-in-production`, the original task still owns
+an unfinished page of that subject: let that writer settle before revising its
+latest approved text. After completion, read the
+new Route to resume production. Never resubmit an accepted old batch.

package/providers/context/resources/procedures/knowledge-review.md

@@ -24,7 +24,7 @@ Without explicit session-managed authority:
 
 - open the report returned by the route;
 - let the user publish or durably omit candidates;
-- apply the exact returned decision payload; and
+- apply the exact copied review code through the returned review apply command; and
 - retain the exact report reference and reviewed scope in this conversation for
   the final completion summary.
 
@@ -38,10 +38,12 @@ With explicit session-managed authority, materialize the required
 `context.review-current` Markdown Resource once. Read its index and every
 reader-facing batch file listed there. Each Candidate appears in exactly one
 bounded batch; keep the decisions in the current Agent context and do not write
-a Review ledger. Only after every batch is publishable may the Agent run the
-single managed atomic approval command. Do not generate, open, or parse the
-ordinary HTML report. If any page needs repair, do not approve any batch;
-reopen the owning Author or Composer through the current repair route. The
+a Review ledger. Use the current scope template in that index with the Route's
+atomic apply command. Add explicit decisions only for reviewed pages; leave
+repair or undecided pages out of decisions and do not set a default. For a fully
+reviewed acceptable set, default approval remains available. Do not generate,
+open, or parse the ordinary HTML report. Reopen repair pages through their
+current repair command; unrelated approvals remain valid. The
 authority exists only in the current conversation. It does not bypass source
 permission, validation, close, or verify, and it is not proof that the files
 were read.
@@ -51,5 +53,66 @@ Do not persist a duplicate review-report ledger in the workspace.
 
 The Review UI names the internal `rejected` decision **Omit** because it is a
 durable content decision, not a request to rewrite the page. When a page needs
-changes, leave the whole batch unapplied and use `context revise` so the owning
+changes, leave that page pending and use `context revise` so the owning
 Author or Composer produces a new Candidate through the same lifecycle.
+
+Use the affected page's `Repair` command in the review material, replacing only
+the correction instruction. Current candidates are repaired within this batch;
+`--timing priority` is not needed and does not queue them behind delivery.
+`--regenerate` schedules program regeneration for approved pages. If supplied
+for a current candidate, follow the CLI's returned repair command instead.
+After the repair, read the new Route and review the changed material before
+approving the batch. Pending maintenance requests for other pages remain queued.
+
+For a repaired generated table, inspect the new Candidate's affected rows, not
+only its Repair ID or accepted Author/Composer outcome. Check the reported error
+against the available source version and facts. A missing value is not always a
+missing source: the source may be present but unsupported by the parser, or the
+correct fact may have been lost during rendering. Describe which case the
+available material establishes. An explicit limitation may be acceptable for the
+reader's task; a known false value must be repaired. If the same error remains
+after regeneration, preserve the batch and report the affected page, field and
+source/fact comparison. Repeating the same repair without new material or a tool
+fix is not progress. Do not approve, omit, or hand-edit a block to hide the error.
+
+## Interpreting generated API output
+
+Check fields, types, requiredness and supported defaults against the selected
+source version. A table can completely express a simple declaration; omitting
+that duplicate folded declaration is intentional. Complex relationships or
+constraints not represented in rows remain in a named declaration. Program
+`declaration_status`, when present, distinguishes `table-complete`,
+`component-wrapper`, `retained` and `not-provided`; its `fact_ref` and `source_ref`
+locate the input. Missing folds alone do not establish a parser failure.
+
+If the user explicitly requires a different presentation, explain the difference
+and resolve that choice before accepting it. Do not rerun unchanged Repair to
+force a format the program deliberately omits. Check the actual resulting page;
+accepted tasks or an empty Composer result alone do not demonstrate a correction.
+
+## Delivering approved pages while others need repair
+
+A partial decision keeps remaining pages in Review. It does not build after each
+approval. When the user asks to see approved results now, use
+`context run --deliver --format json` and follow its new Route through close and
+build. The CLI checks that the approved pages do not depend on unresolved pages;
+if they do, finish the linked pages first. No draft is approved or omitted by
+this request. Remaining drafts, accepted work and source baselines stay in place,
+and the Route returns to their Review/repair after the selected output builds.
+
+## Check usefulness as well as factual accuracy
+
+Use the current requirements and agreed scope to check whether a reader can
+complete the promised task with these pages. Source citations and a valid API
+table alone do not establish that. Compare representative pages with their
+actual definitions: keep defaults and members attached to the correct callable
+or type; inspect inherited members and static entry points when needed for the
+reader's task. Do not infer that an unexpanded type has no options or callbacks.
+
+Look for promised integration steps, examples or troubleshooting answers that
+may be missing across the relevant pages. Check neighboring pages before
+requesting additions. Repeated prose is a reason to inspect the actual content,
+not an automatic rejection rule. If the source is insufficient, identify what
+is unavailable and its effect on the reader instead of inventing content or
+forcing another identical regeneration. Keep correct pages eligible for the
+partial approval and delivery path above.