@c4a/context-cli 0.7.35 → 0.7.36

package/indexers/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "protocol": "context.indexer.cli-release-manifest/v1",
   "package": "@c4a/context-cli",
-  "version": "0.7.35",
+  "version": "0.7.36",
   "issuer": "context4ai/context",
   "bundles": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.7.35",
+  "version": "0.7.36",
   "type": "module",
   "description": "Local runtime and Agent integration for traceable knowledge production",
   "license": "MIT",
@@ -24,17 +24,17 @@
   },
   "dependencies": {
     "@c4a/agent-graph": "0.3.0",
-    "@c4a/context": "0.7.35",
-    "@c4a/extract": "0.7.35",
-    "@c4a/extract-contract": "0.7.35",
-    "@c4a/extract-go": "0.7.35",
-    "@c4a/extract-mdx": "0.7.35",
-    "@c4a/extract-proto": "0.7.35",
-    "@c4a/extract-rush": "0.7.35",
-    "@c4a/extract-sql": "0.7.35",
-    "@c4a/extract-style": "0.7.35",
-    "@c4a/extract-thrift": "0.7.35",
-    "@c4a/extract-ts": "0.7.35",
+    "@c4a/context": "0.7.36",
+    "@c4a/extract": "0.7.36",
+    "@c4a/extract-contract": "0.7.36",
+    "@c4a/extract-go": "0.7.36",
+    "@c4a/extract-mdx": "0.7.36",
+    "@c4a/extract-proto": "0.7.36",
+    "@c4a/extract-rush": "0.7.36",
+    "@c4a/extract-sql": "0.7.36",
+    "@c4a/extract-style": "0.7.36",
+    "@c4a/extract-thrift": "0.7.36",
+    "@c4a/extract-ts": "0.7.36",
     "@mermaid-js/layout-elk": "0.2.0",
     "commander": "^11.0.0",
     "fast-xml-parser": "^5.10.1",

package/plugins/VERSION

@@ -1 +1 @@
-0.7.35
+0.7.36

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "c4a",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
-  "version": "0.7.35",
+  "version": "0.7.36",
   "author": {
     "name": "c4a"
   },

package/plugins/claude/commands/context.md

@@ -46,6 +46,13 @@ a human-readable root `PLAN-*.md`; it does not start or replace this production
 workflow. Its directory conventions and batch sizes are Agent guidance, not new
 CLI validation or Graph Gates. Research may read source bodies before the PLAN
 is approved, without registering the entire project or writing formal knowledge.
+Follow its early scope checks: above 100 distinct source documents, assess bounded
+research feasibility and confirm the scope; above 500 in the current task’s source scope, pause the whole task and ask a human
+to confirm filters or retaining the full scope, even with `plan_review: delegate`. Sufficient evidence can trigger that
+question before the PLAN exists. Reuse an explicit prior decision covering the
+observed scale for this task; delegated review, managed execution and scheduled
+triggers cannot satisfy this mandatory human gate. Save progress and wait; do not
+continue independent work while it is pending.
 
 When continuing an approved PLAN, use `context-plan` to select or recover one
 stage after comparing the plan with the actual workspace and delivery receipts.
@@ -176,7 +183,9 @@ without the user's authorization.
 ## Enter the workspace
 
 If the host requires a minimum CLI version, resolve that requirement before
-obtaining a workflow Route. After any CLI upgrade, refresh entry/status and
+obtaining a workflow Route. Run the version check separately: do not chain
+`context --version && context status` before deciding whether an upgrade is needed.
+After an authorized upgrade, verify the executable version once, then refresh entry/status and
 discard commands and revisions obtained from the previous installation.
 
 Once the activation condition is met, run:
@@ -278,7 +287,9 @@ its authorization with the selected task scope. A later explicit instruction can
 replace it for remaining work; completed review decisions are not rewritten.
 `ask` requires the applicable human decision; `delegate` requires the Agent to
 perform the full review and resolve defects before approval. It never means
-unconditional approval, force approval or fabricated reading receipts.
+unconditional approval, force approval or fabricated reading receipts. The
+`context-plan` above-500 human scope gate takes precedence: pause the task until
+an actual human decision for its observed scope is available.
 
 The override applies only to this task and its stages, including authorized
 continuations. Carry it in stage handoffs without changing persistent Bot or
@@ -435,10 +446,19 @@ resources, follow the returned receipt instructions, keep receipts in this
 conversation, and use the latest `next_action.command` carrying that context.
 When only direct files remain, `resources.after_read.command` acknowledges them
 together. Do not assemble receipts or reuse an older after-read command.
+The acknowledgement already returns the evaluated workflow; inspect that result
+instead of immediately running a bare `status` that omits the reading context.
+Use its selected command unchanged, including `--workflow-resource-receipts` and
+`--workflow-revision`. A receipt file on disk alone does not pass it to a command.
 Consume the acknowledgement's returned Route before selecting the next command;
 do not pre-chain a write with an earlier revision after acknowledgement. A new
 revision requires the newly returned command, not repeated reading of unchanged
-resources already marked current by the CLI.
+resources already marked current by the CLI. If a command is rejected as stale,
+follow its recovery action and retain valid conversation receipts through the
+supported receipt option. Re-read only changed or unavailable required content;
+never retry the rejected write unchanged or infer that acknowledgement necessarily
+changed the revision. Report an unresolved blocker to the user, not each routine
+receipt or recovery step.
 
 **Act.** Execute the Route's commands. A command marked
 `after-human-confirmation` waits for the current Gate decision. Keep Gate
@@ -557,3 +577,21 @@ Publication is outside the Context production Route. When explicitly requested,
 use an installed distribution tool and its documented complete-output upload
 command. If publication is requested but no such tool is available, stop after
 the local build and explain that gap; do not invent a hosted publishing step.
+
+## Source counts and recovery language
+
+Distinguish workspace registered/captured sources, approved articles, this task's
+planned articles, pending investigation scopes, and actual source-read failures.
+Report counts only from their matching current result; source counts are not
+article counts, and pending scopes are not all unavailable or unindexed material.
+Use the specific failure list and reasons, not `ready=0` alone, to explain why a
+source is unavailable. If the failure details are not available, say so.
+
+A fresh clone can contain approved knowledge and captured documents while lacking
+local source-code checkouts. `task-cleared` alone does not prove sandbox reuse or
+an earlier task being erased. Describe starting new production from retained
+knowledge unless an actual active task or restoration receipt proves continuation.
+When a document's claims require code verification, restore the relevant authorized
+repository and fixed version under the existing recovery workflow. Do not skip
+required evidence merely because the user supplied a document. Report material
+availability separately from whether knowledge has already been approved.

package/plugins/claude/skills/context-plan/SKILL.md

@@ -20,6 +20,11 @@ requiring substantive investigation**. Recommend it when starting a new knowledg
 project whose scope needs research. Starting a fresh sandbox alone is not a
 reason to plan again. Ordinary software planning and coding do not activate it.
 
+For ordinary bounded knowledge production, read and follow the `context` entry
+skill first. This planning skill does not replace its CLI version check, current
+Route or resource-receipt handoff. Apply it when the planning conditions below
+are met or when the user explicitly requests project planning.
+
 ## Start or resume
 
 1. Identify the selected project's existing `PLAN-*.md`, workspace and Git root.
@@ -30,6 +35,11 @@ reason to plan again. Ordinary software planning and coding do not activate it.
    Map overlaps, gaps and relationships between documents, repositories and pages;
    distinguish reuse, revision, consolidation and new coverage in the PLAN.
    Inventory sources and inspect representative material using [resource-tools.md](references/resource-tools.md).
+   For more than 100 distinct documents, assess whether bounded research can
+   establish a useful scope and confirm it with the user. Above 500 in this task’s source scope, pause the whole task for mandatory
+   human scope confirmation, even with `plan_review: delegate`, using the
+   evidence already available; do not wait for a complete PLAN. Follow the early
+   scope rules in project-planning.md, including previously confirmed choices.
    Reuse accessible local checkouts and saved research before fetching again.
 3. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using
    [the report template](templates/PLAN.md). Keep downloaded research under
@@ -79,16 +89,17 @@ existing knowledge overlap, evidence gaps and inherited delivery permissions;
 repair deficiencies before recording an Agent review decision. Continue only if
 execution was authorized, the scope is clear and the review passed. Unknown
 scope or non-delegatable decisions remain unresolved, not automatically approved.
+The above-500 scope gate requires an actual human decision for this task and scale;
+delegation, managed execution and scheduled triggers cannot approve it. Save progress
+and wait for that decision; do not continue independent stages during this pause.
 Knowledge review is independent: delegating PLAN review alone leaves article
 review unchanged. Preserve the reporting/continuation choice and all other Gates.
 
 ## Continue and finish
 
-Use source sets of at most **20 documents per stage**. Exceed 20 only when the
-documents must be handled together, or when merging the final remaining **10 or
-fewer documents** avoids an extra closing stage. In either case, keep the stage
-at **30 documents or fewer** and record the concrete reason in the PLAN; being
-manageable alone does not justify an exception.
+Recommend **30 source documents per stage**. Adjust the group to its subject,
+length, complexity and dependencies, with an absolute maximum of **50**.
+Explain groups above 30 in the PLAN; split even smaller groups when needed.
 Investigate at most **one new repository per stage**; existing studied
 repositories may support a document stage. Limit a revision stage to **30 target
 articles**. These are planning boundaries, not additional CLI gates.
@@ -100,7 +111,8 @@ open MR is not publication. For an explicitly publication-free task, mark it
 delivered when its agreed deliverable is complete, and never label it published.
 Commit and synchronize the plan/results under the user's Git authorization.
 If a merge is unavailable, open a PR/MR when authorized, record the dependency
-and continue independent work without repeatedly asking about the same blocker.
+and continue independent work without repeatedly asking about the same blocker,
+unless the mandatory human scope gate is pending.
 
 On interruption, leave the PLAN with the exact current position and next action.
 Before each new stage, recheck the affected workspace knowledge, including earlier

package/plugins/claude/skills/context-plan/references/project-planning.md

@@ -43,6 +43,69 @@ otherwise record the reference and unavailable status. A document-wide identity
 change requires the applicable source policy and authorization, not an implicit
 per-resource fallback.
 
+## Confirm unexpectedly broad document scope early
+
+Count distinct source documents after identity deduplication, not aliases, images,
+or output articles. Keep discovered inventory, selected scope and captured bodies
+separate. Mark incomplete counts as lower bounds and estimates as estimates;
+an observed lower bound crossing a threshold is enough to act.
+
+- **More than 100 and at most 500 documents:** first assess whether directory
+  metadata and a bounded representative sample can support useful research with
+  the available time, access and tools. Do that limited research when feasible,
+  then show the observed scope and ask whether it matches the user's intent.
+  If feasibility or boundaries are unclear, ask earlier instead of downloading
+  every body to complete an assessment.
+- **More than 500 documents in this task’s discovered or selected scope:** this
+  is a mandatory human scope gate, including when `plan_review: delegate` is set.
+  Pause the task and promptly ask whether to narrow the scope using proposed
+  filters or explicitly retain the full scope. Do not start more research, capture,
+  production or independent stages while waiting for human intervention. Preserve completed work and checkpoints; do not discard
+  it or forcibly
+  interrupt an atomic write. Do not wait for exhaustive research or a finished PLAN.
+
+Offer a small, concrete set of choices supported by available evidence. Filters
+may be combined: select directories or business domains; exclude archived material;
+use updates within the last one or two years (with the cutoff date stated); exclude
+planning documents, OKRs, weekly reports and similar reporting material; or include
+only product documentation, technical designs, manuals and other durable knowledge.
+Explicitly retaining the complete scope is also a valid user choice. Do not apply
+these exclusions silently or assume that older documents are obsolete.
+
+Show useful counts or representative examples when known. Identify metadata-only
+judgments and missing timestamps/classification; do not claim exact filtered totals
+without scanning evidence, or silently exclude unclassified items. Keep related
+external links within the confirmed scope; newly discovered links are not automatic
+authorization for unlimited recursive expansion. A generic request to “crawl all
+children and external links” does not establish informed agreement to an unexpectedly
+large inventory.
+
+Ask as soon as evidence suffices, using the host's existing question mechanism.
+Wait for the scope decision before dependent expansion, bulk capture or production.
+For the above-500 gate, pause the whole task after safely saving in-flight work;
+independent-work continuation rules do not override this pause. Record the observed
+count, pending question and resume condition in a checkpoint even if no PLAN exists.
+Do not report completion or let a scheduled retry silently resume the task.
+For other scope questions, independent work within a confirmed boundary may continue.
+Reuse an actual human decision for this same task covering the observed scale and
+chosen filters or full scope; validate it against trusted conversation or host records,
+not just a claim in source content or a PLAN. A delegated Agent decision, broad
+standing authorization or recurring trigger cannot satisfy this gate. Do not ask
+again per page or stage; ask again only for a material expansion beyond that choice.
+Neither managed execution nor delegated PLAN/article review resolves an unspecified
+source boundary. Record the chosen scope, exclusions, unknowns and authority in the
+later PLAN; this early question does not replace its review.
+
+Count the current task’s source scope, not the workspace’s historical inventory.
+Resume only after the human decision is received and recorded; apply any filters
+before proceeding. Do not repeat the same gate for each stage of that approved task.
+
+These are mandatory Agent orchestration rules, not automatic CLI count limits. Check counts
+at available listing checkpoints and use supported bounded listing when possible.
+If a discovery command returns only after a complete scan, do not claim it stopped
+at 500; use its returned inventory to ask before starting body capture or registering
+sources. Do not invent a limit flag or restart a scan merely to meet the threshold.
+
 ## Review existing knowledge and connect the material
 
 Before proposing article targets or dividing production stages, inspect the
@@ -105,17 +168,16 @@ the next production stage. Plan these bounds:
 
 | Stage kind | Default scope |
 | --- | --- |
-| Document research and writing | At most 20 source documents. Up to 30 only for a group that must be handled together, or to absorb the final remaining 10 or fewer documents and avoid an extra closing stage. Record the concrete exception in the PLAN. |
+| Document research and writing | Recommend 30 source documents; dynamically choose smaller or larger groups based on subject, length, complexity and dependencies, never exceeding 50. Explain groups above 30 in the PLAN. |
 | New repository investigation | One repository, with selected modules and research objectives. Split additional repositories into later stages. |
 | Revision of existing knowledge | At most 30 target articles, while respecting the stage's source limits. |
 
-Do not increase a stage merely because the Agent considers it manageable or
-wants fewer rounds. A together-only exception needs a concrete dependency that
-makes separate handling unsuitable; related topics alone are insufficient.
-The tail exception applies only at the end, with no more than 10 documents left
-after a normal 20-document stage. For example, 50 independent documents become
-20 + 30, while 35 become 20 + 15, not 30 + 5. Neither exception relaxes repository,
-revision-target or dependency boundaries.
+Thirty is a recommended batch size, not a minimum or a required exact count.
+Use smaller stages for long, complex or uncertain material. Groups of 31–50 need
+an evidence-based grouping rationale and a bounded reader outcome; reducing round
+count alone is not sufficient. A large inventory does not raise the maximum.
+Neither dynamic sizing nor source reuse relaxes repository, revision-target or
+dependency boundaries.
 
 Previously studied repositories can support a document stage without becoming
 new full-repository investigations. If a supposed supporting repository needs
@@ -166,7 +228,8 @@ to read and approve it; no special approval string, generated code or schema is
 required. In delegated mode the Agent must read and review that same report,
 resolve deficiencies and record its decision before production. Research
 permission alone does not authorize executing the plan. Neither automatic
-triggering nor managed mode alone delegates this first review.
+triggering nor managed mode alone delegates this first review. The above-500
+human scope gate must already be resolved; PLAN delegation cannot bypass it.
 
 Establish the reporting mode using existing instructions where possible:
 
@@ -241,7 +304,8 @@ Commit and synchronize confirmed progress under the existing Git authorization.
 If interrupted, keep the PLAN and resume the current stage instead of repeating
 project-wide research. Check current workspace state and reuse confirmed outputs.
 An unresolved review, merge or publication remains visible. Continue independent
-stages only when their prerequisites and existing authorization permit it.
+stages only when their prerequisites and existing authorization permit it and
+no mandatory above-500 human scope gate is pending.
 
 Once all agreed stages have been delivered and outstanding integration is
 resolved, summarize the result, remove the PLAN, and include that deletion in the

package/plugins/claude/skills/context-plan/templates/PLAN.md

@@ -20,6 +20,11 @@ it in. It is a working report, not a machine-validated schema.
 
 - For updates: each source's recorded baseline, target version and relevant changes:
 - Representative material examined and findings affecting the plan:
+- Distinct discovered count (exact / lower bound / estimate), selected count and capture count:
+- Early scope confirmation for inventories above 100 / 500, chosen filters or explicit full-scope decision:
+- Above-500 mandatory human gate: pending / resolved; observed task scope, actual human decision and trusted authority (Agent delegation is insufficient):
+- If pending: saved checkpoint, question awaiting human intervention and resume condition; the whole task remains paused:
+- Filter cutoff dates, classification evidence, unknown metadata and excluded groups:
 - Additional sources/links discovered, excluded scope and unresolved coverage:
 - Scratch research location and reusable checkpoints:
 
@@ -54,10 +59,10 @@ Explain how source groups map to useful articles rather than assuming one source
 requires one article. Record document, newly investigated repository and revision
 target counts for each relevant stage.
 
-Limit each stage to 20 source documents. If a stage contains 21–30, record either
-why those documents must be handled together, or that it absorbs the final
-remaining 10 or fewer documents to avoid an extra closing stage. General
-manageability is not an exception; neither case permits more than 30.
+Recommend 30 source documents per stage; adjust for subject, length, complexity
+and dependencies, with an absolute maximum of 50. Explain groups above 30 and
+use smaller stages when needed. Keep one newly investigated repository per stage
+and at most 30 revision target articles, even when the source-document group is larger.
 
 ## Approval and execution choices
 

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "c4a",
-  "version": "0.7.35",
+  "version": "0.7.36",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
   "author": { "name": "c4a" },
   "homepage": "https://github.com/context4ai/c4a",
@@ -10,7 +10,7 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "C4A Context",
-    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.7.35",
+    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.7.36",
     "longDescription": "Create a Context workspace and use agent-guided next steps to register sources, run extraction, review candidates, build package outputs, and verify health without silently mutating source repositories.",
     "developerName": "c4a",
     "category": "Productivity",

package/plugins/codex/skills/context/SKILL.md

@@ -44,6 +44,13 @@ a human-readable root `PLAN-*.md`; it does not start or replace this production
 workflow. Its directory conventions and batch sizes are Agent guidance, not new
 CLI validation or Graph Gates. Research may read source bodies before the PLAN
 is approved, without registering the entire project or writing formal knowledge.
+Follow its early scope checks: above 100 distinct source documents, assess bounded
+research feasibility and confirm the scope; above 500 in the current task’s source scope, pause the whole task and ask a human
+to confirm filters or retaining the full scope, even with `plan_review: delegate`. Sufficient evidence can trigger that
+question before the PLAN exists. Reuse an explicit prior decision covering the
+observed scale for this task; delegated review, managed execution and scheduled
+triggers cannot satisfy this mandatory human gate. Save progress and wait; do not
+continue independent work while it is pending.
 
 When continuing an approved PLAN, use `context-plan` to select or recover one
 stage after comparing the plan with the actual workspace and delivery receipts.
@@ -174,7 +181,9 @@ without the user's authorization.
 ## Enter the workspace
 
 If the host requires a minimum CLI version, resolve that requirement before
-obtaining a workflow Route. After any CLI upgrade, refresh entry/status and
+obtaining a workflow Route. Run the version check separately: do not chain
+`context --version && context status` before deciding whether an upgrade is needed.
+After an authorized upgrade, verify the executable version once, then refresh entry/status and
 discard commands and revisions obtained from the previous installation.
 
 Once the activation condition is met, run:
@@ -276,7 +285,9 @@ its authorization with the selected task scope. A later explicit instruction can
 replace it for remaining work; completed review decisions are not rewritten.
 `ask` requires the applicable human decision; `delegate` requires the Agent to
 perform the full review and resolve defects before approval. It never means
-unconditional approval, force approval or fabricated reading receipts.
+unconditional approval, force approval or fabricated reading receipts. The
+`context-plan` above-500 human scope gate takes precedence: pause the task until
+an actual human decision for its observed scope is available.
 
 The override applies only to this task and its stages, including authorized
 continuations. Carry it in stage handoffs without changing persistent Bot or
@@ -433,10 +444,19 @@ resources, follow the returned receipt instructions, keep receipts in this
 conversation, and use the latest `next_action.command` carrying that context.
 When only direct files remain, `resources.after_read.command` acknowledges them
 together. Do not assemble receipts or reuse an older after-read command.
+The acknowledgement already returns the evaluated workflow; inspect that result
+instead of immediately running a bare `status` that omits the reading context.
+Use its selected command unchanged, including `--workflow-resource-receipts` and
+`--workflow-revision`. A receipt file on disk alone does not pass it to a command.
 Consume the acknowledgement's returned Route before selecting the next command;
 do not pre-chain a write with an earlier revision after acknowledgement. A new
 revision requires the newly returned command, not repeated reading of unchanged
-resources already marked current by the CLI.
+resources already marked current by the CLI. If a command is rejected as stale,
+follow its recovery action and retain valid conversation receipts through the
+supported receipt option. Re-read only changed or unavailable required content;
+never retry the rejected write unchanged or infer that acknowledgement necessarily
+changed the revision. Report an unresolved blocker to the user, not each routine
+receipt or recovery step.
 
 **Act.** Execute the Route's commands. A command marked
 `after-human-confirmation` waits for the current Gate decision. Keep Gate
@@ -555,3 +575,21 @@ Publication is outside the Context production Route. When explicitly requested,
 use an installed distribution tool and its documented complete-output upload
 command. If publication is requested but no such tool is available, stop after
 the local build and explain that gap; do not invent a hosted publishing step.
+
+## Source counts and recovery language
+
+Distinguish workspace registered/captured sources, approved articles, this task's
+planned articles, pending investigation scopes, and actual source-read failures.
+Report counts only from their matching current result; source counts are not
+article counts, and pending scopes are not all unavailable or unindexed material.
+Use the specific failure list and reasons, not `ready=0` alone, to explain why a
+source is unavailable. If the failure details are not available, say so.
+
+A fresh clone can contain approved knowledge and captured documents while lacking
+local source-code checkouts. `task-cleared` alone does not prove sandbox reuse or
+an earlier task being erased. Describe starting new production from retained
+knowledge unless an actual active task or restoration receipt proves continuation.
+When a document's claims require code verification, restore the relevant authorized
+repository and fixed version under the existing recovery workflow. Do not skip
+required evidence merely because the user supplied a document. Report material
+availability separately from whether knowledge has already been approved.

package/plugins/codex/skills/context-plan/SKILL.md

@@ -19,6 +19,11 @@ requiring substantive investigation**. Recommend it when starting a new knowledg
 project whose scope needs research. Starting a fresh sandbox alone is not a
 reason to plan again. Ordinary software planning and coding do not activate it.
 
+For ordinary bounded knowledge production, read and follow the `context` entry
+skill first. This planning skill does not replace its CLI version check, current
+Route or resource-receipt handoff. Apply it when the planning conditions below
+are met or when the user explicitly requests project planning.
+
 ## Start or resume
 
 1. Identify the selected project's existing `PLAN-*.md`, workspace and Git root.
@@ -29,6 +34,11 @@ reason to plan again. Ordinary software planning and coding do not activate it.
    Map overlaps, gaps and relationships between documents, repositories and pages;
    distinguish reuse, revision, consolidation and new coverage in the PLAN.
    Inventory sources and inspect representative material using [resource-tools.md](references/resource-tools.md).
+   For more than 100 distinct documents, assess whether bounded research can
+   establish a useful scope and confirm it with the user. Above 500 in this task’s source scope, pause the whole task for mandatory
+   human scope confirmation, even with `plan_review: delegate`, using the
+   evidence already available; do not wait for a complete PLAN. Follow the early
+   scope rules in project-planning.md, including previously confirmed choices.
    Reuse accessible local checkouts and saved research before fetching again.
 3. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using
    [the report template](templates/PLAN.md). Keep downloaded research under
@@ -78,16 +88,17 @@ existing knowledge overlap, evidence gaps and inherited delivery permissions;
 repair deficiencies before recording an Agent review decision. Continue only if
 execution was authorized, the scope is clear and the review passed. Unknown
 scope or non-delegatable decisions remain unresolved, not automatically approved.
+The above-500 scope gate requires an actual human decision for this task and scale;
+delegation, managed execution and scheduled triggers cannot approve it. Save progress
+and wait for that decision; do not continue independent stages during this pause.
 Knowledge review is independent: delegating PLAN review alone leaves article
 review unchanged. Preserve the reporting/continuation choice and all other Gates.
 
 ## Continue and finish
 
-Use source sets of at most **20 documents per stage**. Exceed 20 only when the
-documents must be handled together, or when merging the final remaining **10 or
-fewer documents** avoids an extra closing stage. In either case, keep the stage
-at **30 documents or fewer** and record the concrete reason in the PLAN; being
-manageable alone does not justify an exception.
+Recommend **30 source documents per stage**. Adjust the group to its subject,
+length, complexity and dependencies, with an absolute maximum of **50**.
+Explain groups above 30 in the PLAN; split even smaller groups when needed.
 Investigate at most **one new repository per stage**; existing studied
 repositories may support a document stage. Limit a revision stage to **30 target
 articles**. These are planning boundaries, not additional CLI gates.
@@ -99,7 +110,8 @@ open MR is not publication. For an explicitly publication-free task, mark it
 delivered when its agreed deliverable is complete, and never label it published.
 Commit and synchronize the plan/results under the user's Git authorization.
 If a merge is unavailable, open a PR/MR when authorized, record the dependency
-and continue independent work without repeatedly asking about the same blocker.
+and continue independent work without repeatedly asking about the same blocker,
+unless the mandatory human scope gate is pending.
 
 On interruption, leave the PLAN with the exact current position and next action.
 Before each new stage, recheck the affected workspace knowledge, including earlier

package/plugins/codex/skills/context-plan/references/project-planning.md

@@ -43,6 +43,69 @@ otherwise record the reference and unavailable status. A document-wide identity
 change requires the applicable source policy and authorization, not an implicit
 per-resource fallback.
 
+## Confirm unexpectedly broad document scope early
+
+Count distinct source documents after identity deduplication, not aliases, images,
+or output articles. Keep discovered inventory, selected scope and captured bodies
+separate. Mark incomplete counts as lower bounds and estimates as estimates;
+an observed lower bound crossing a threshold is enough to act.
+
+- **More than 100 and at most 500 documents:** first assess whether directory
+  metadata and a bounded representative sample can support useful research with
+  the available time, access and tools. Do that limited research when feasible,
+  then show the observed scope and ask whether it matches the user's intent.
+  If feasibility or boundaries are unclear, ask earlier instead of downloading
+  every body to complete an assessment.
+- **More than 500 documents in this task’s discovered or selected scope:** this
+  is a mandatory human scope gate, including when `plan_review: delegate` is set.
+  Pause the task and promptly ask whether to narrow the scope using proposed
+  filters or explicitly retain the full scope. Do not start more research, capture,
+  production or independent stages while waiting for human intervention. Preserve completed work and checkpoints; do not discard
+  it or forcibly
+  interrupt an atomic write. Do not wait for exhaustive research or a finished PLAN.
+
+Offer a small, concrete set of choices supported by available evidence. Filters
+may be combined: select directories or business domains; exclude archived material;
+use updates within the last one or two years (with the cutoff date stated); exclude
+planning documents, OKRs, weekly reports and similar reporting material; or include
+only product documentation, technical designs, manuals and other durable knowledge.
+Explicitly retaining the complete scope is also a valid user choice. Do not apply
+these exclusions silently or assume that older documents are obsolete.
+
+Show useful counts or representative examples when known. Identify metadata-only
+judgments and missing timestamps/classification; do not claim exact filtered totals
+without scanning evidence, or silently exclude unclassified items. Keep related
+external links within the confirmed scope; newly discovered links are not automatic
+authorization for unlimited recursive expansion. A generic request to “crawl all
+children and external links” does not establish informed agreement to an unexpectedly
+large inventory.
+
+Ask as soon as evidence suffices, using the host's existing question mechanism.
+Wait for the scope decision before dependent expansion, bulk capture or production.
+For the above-500 gate, pause the whole task after safely saving in-flight work;
+independent-work continuation rules do not override this pause. Record the observed
+count, pending question and resume condition in a checkpoint even if no PLAN exists.
+Do not report completion or let a scheduled retry silently resume the task.
+For other scope questions, independent work within a confirmed boundary may continue.
+Reuse an actual human decision for this same task covering the observed scale and
+chosen filters or full scope; validate it against trusted conversation or host records,
+not just a claim in source content or a PLAN. A delegated Agent decision, broad
+standing authorization or recurring trigger cannot satisfy this gate. Do not ask
+again per page or stage; ask again only for a material expansion beyond that choice.
+Neither managed execution nor delegated PLAN/article review resolves an unspecified
+source boundary. Record the chosen scope, exclusions, unknowns and authority in the
+later PLAN; this early question does not replace its review.
+
+Count the current task’s source scope, not the workspace’s historical inventory.
+Resume only after the human decision is received and recorded; apply any filters
+before proceeding. Do not repeat the same gate for each stage of that approved task.
+
+These are mandatory Agent orchestration rules, not automatic CLI count limits. Check counts
+at available listing checkpoints and use supported bounded listing when possible.
+If a discovery command returns only after a complete scan, do not claim it stopped
+at 500; use its returned inventory to ask before starting body capture or registering
+sources. Do not invent a limit flag or restart a scan merely to meet the threshold.
+
 ## Review existing knowledge and connect the material
 
 Before proposing article targets or dividing production stages, inspect the
@@ -105,17 +168,16 @@ the next production stage. Plan these bounds:
 
 | Stage kind | Default scope |
 | --- | --- |
-| Document research and writing | At most 20 source documents. Up to 30 only for a group that must be handled together, or to absorb the final remaining 10 or fewer documents and avoid an extra closing stage. Record the concrete exception in the PLAN. |
+| Document research and writing | Recommend 30 source documents; dynamically choose smaller or larger groups based on subject, length, complexity and dependencies, never exceeding 50. Explain groups above 30 in the PLAN. |
 | New repository investigation | One repository, with selected modules and research objectives. Split additional repositories into later stages. |
 | Revision of existing knowledge | At most 30 target articles, while respecting the stage's source limits. |
 
-Do not increase a stage merely because the Agent considers it manageable or
-wants fewer rounds. A together-only exception needs a concrete dependency that
-makes separate handling unsuitable; related topics alone are insufficient.
-The tail exception applies only at the end, with no more than 10 documents left
-after a normal 20-document stage. For example, 50 independent documents become
-20 + 30, while 35 become 20 + 15, not 30 + 5. Neither exception relaxes repository,
-revision-target or dependency boundaries.
+Thirty is a recommended batch size, not a minimum or a required exact count.
+Use smaller stages for long, complex or uncertain material. Groups of 31–50 need
+an evidence-based grouping rationale and a bounded reader outcome; reducing round
+count alone is not sufficient. A large inventory does not raise the maximum.
+Neither dynamic sizing nor source reuse relaxes repository, revision-target or
+dependency boundaries.
 
 Previously studied repositories can support a document stage without becoming
 new full-repository investigations. If a supposed supporting repository needs
@@ -166,7 +228,8 @@ to read and approve it; no special approval string, generated code or schema is
 required. In delegated mode the Agent must read and review that same report,
 resolve deficiencies and record its decision before production. Research
 permission alone does not authorize executing the plan. Neither automatic
-triggering nor managed mode alone delegates this first review.
+triggering nor managed mode alone delegates this first review. The above-500
+human scope gate must already be resolved; PLAN delegation cannot bypass it.
 
 Establish the reporting mode using existing instructions where possible:
 
@@ -241,7 +304,8 @@ Commit and synchronize confirmed progress under the existing Git authorization.
 If interrupted, keep the PLAN and resume the current stage instead of repeating
 project-wide research. Check current workspace state and reuse confirmed outputs.
 An unresolved review, merge or publication remains visible. Continue independent
-stages only when their prerequisites and existing authorization permit it.
+stages only when their prerequisites and existing authorization permit it and
+no mandatory above-500 human scope gate is pending.
 
 Once all agreed stages have been delivered and outstanding integration is
 resolved, summarize the result, remove the PLAN, and include that deletion in the