@c4a/context-cli 0.7.5 → 0.7.9

package/plugins/skills/context-sessions-indexer/templates/incident-review.md

@@ -0,0 +1,37 @@
+# What happened and what changes
+
+This is the page shape for one incident. Use it as an outline, not a form to
+fill.
+
+## Section blueprint
+
+```markdown
+## <the incident, named by its impact rather than its date>
+- Impact: who or what was affected, and for how long
+- Sequence: what happened, only to the detail that explains the outcome
+- Cause: established causes, kept separate from hypotheses still open
+- Changed: what was actually changed as a result
+- Change discussed: the associated change, where a reader needs to check it
+- Still open: follow-ups that have not landed
+```
+
+`Impact` and `Cause` are required. A hypothesis stays labelled as one for as long
+as it is unconfirmed; an unlabelled guess in `Cause` is the failure mode this
+profile exists to prevent. Keep `Sequence` only as long as it explains the
+outcome — a troubleshooting discussion contains many attempts, and reproducing
+them in order is not an explanation.
+
+Separate what was tried and failed from what actually resolved the incident.
+Under `Changed`, a remediation someone proposed during the discussion is not a
+change; proposals belong in `Still open` until an authorized source shows they
+landed. The same distinction applies to causes: "we think it was the cache" from
+mid-discussion is a hypothesis even when the incident later resolved.
+
+`Change discussed` renders the source's optional `changes` association as readable
+prose, for a reader who needs to open the fix and see it. It does not establish
+that the fix shipped or worked; keep it out of the page frontmatter.
+
+A session records the incident as the participants understood it at the time.
+Where their account cannot establish impact or cause, record that gap rather than
+completing the story — a review that reads as resolved while its cause is
+unknown is the version people stop questioning.

package/plugins/skills/context-sessions-indexer/templates/product-requirements.md

@@ -0,0 +1,35 @@
+# Expected behavior
+
+This is the page shape for one required behavior. Use it as an outline, not a
+form to fill.
+
+## Section blueprint
+
+```markdown
+## <the requirement, named by the behavior it demands>
+- Expected: the behavior as agreed
+- Accept when: the conditions that make it satisfied
+- Today: how the current implementation differs, where that is known
+- Change discussed: the associated change, where a reader needs to check it
+- Undecided: what the discussion left open
+```
+
+`Expected` and `Accept when` are required. Keeping `Expected` and `Today` distinct
+is the entire reason this profile exists: a requirement agreed in a discussion
+written as current behavior misleads every later reader, and the mistake becomes
+invisible once the page is approved. When no authorized source establishes current
+behavior, write that it has not been checked rather than leaving `Today` absent.
+
+`Accept when` must be checkable. Requirements clarified in conversation often
+arrive as intent — "it should retry" — with no condition attached. If the
+discussion gives no checkable condition, record that gap; an untestable
+requirement will be declared met by whoever wants it met.
+
+Distinguish what participants agreed from what one participant proposed. An
+unanswered suggestion is not a requirement, and `Undecided` is where it belongs.
+A requirement agreed for a future release coexists with current behavior that
+does not satisfy it; keep both, and keep them labelled.
+
+`Change discussed` renders the source's optional `changes` association as readable
+prose, for a reader checking how far the requirement has been carried. It does
+not establish that the requirement is met. Keep it out of the page frontmatter.

package/plugins/skills/context-sessions-indexer/templates/runbook.md

@@ -0,0 +1,32 @@
+# Diagnose and recover
+
+This is the page shape for one operational situation. Use it as an outline, not a
+form to fill.
+
+## Section blueprint
+
+```markdown
+## <the symptom, as an operator first encounters it>
+- Symptom: what is observed, including the actual message or signal
+- Confirm: how to tell this case apart from ones that present the same way
+- Act: the ordered steps, with anything irreversible marked as such
+- Verify: how to know recovery actually worked
+- Escalate: who or what to fall back on when the steps do not resolve it
+```
+
+`Symptom` and `Act` are required; a page missing either is not usable under
+pressure. `Verify` is the section most often dropped and the most consequential:
+an unverifiable recovery invites an operator to declare success early. When the
+discussion never says how recovery was confirmed, record that as a gap rather
+than inventing a check. Omit `Escalate` when no fallback is known.
+
+A troubleshooting session is mostly attempts that did not work. Only what
+actually resolved the situation belongs in `Act`, and only in the order that was
+actually effective — not the order people tried things. A step someone suggested
+mid-discussion and nobody ran is not part of the procedure; if it is worth
+keeping, it is a hypothesis, not an instruction.
+
+Watch for the case where the incident resolved and nobody established why.
+Participants often settle on a cause by agreement rather than by evidence. Keep
+that out of `Confirm`, because a guessed discriminator sends the next operator
+down the wrong path while a real incident is running.

package/plugins/skills/context-sessions-indexer/templates/technical-guide.md

@@ -0,0 +1,31 @@
+# Complete the task
+
+This is the page shape for one repeatable task. Use it as an outline, not a form
+to fill.
+
+## Section blueprint
+
+```markdown
+## <the task, named by what the reader accomplishes>
+- Goal: the end state the reader reaches
+- Before you start: prerequisites, permissions and required prior state
+- Steps: ordered, each one with an observable outcome
+- Check: how the reader knows the task succeeded
+- When it fails: the failures actually encountered, and what to do about them
+```
+
+`Goal`, `Steps` and `Check` are required. A step whose outcome the reader cannot
+observe is not a step — either give what it produces or say the outcome is
+unknown. `Before you start` is required whenever a missing prerequisite would fail
+the task partway. Keep `When it fails` to failures the discussion actually
+records.
+
+A session describes a task as it was worked out, not as it should be performed.
+Those differ: the working-out includes dead ends, corrections and steps that were
+later found unnecessary. Reconstruct the procedure that a reader should follow,
+and drop the path taken to discover it. Where the discussion corrected an earlier
+step, the page carries the corrected version only.
+
+Do not fill gaps with generic advice such as "check your configuration". A guide
+with three established steps and one stated unknown is more useful than five
+steps where two were inferred from context.

package/plugins/skills/context-sessions-indexer/templates/test-validation.md

@@ -0,0 +1,37 @@
+# What was checked
+
+This is the page shape for one validation. Use it as an outline, not a form to
+fill.
+
+## Section blueprint
+
+```markdown
+## <what was validated>
+- Checked: the behavior or property under test
+- How: the method, environment and scope
+- Result: what the run actually showed
+- Change discussed: the associated change, where a reader needs to check it
+- Not covered: what this validation does not establish
+```
+
+`Checked` and `Result` are required, and `Result` must carry the strength of its
+evidence. In a discussion, "I tested it and it works" is a reported result: write
+it as reported unless the actual output is in authorized scope. `Not covered` is
+required whenever the scope is narrower than the claim a reader would naturally
+draw from it.
+
+`How` matters because a result without its method cannot be repeated. Discussions
+routinely omit the environment — record that as a gap rather than describing a
+plausible setup.
+
+`Change discussed` renders the source's optional `changes` association as readable
+prose. Be especially careful here: a change link proves neither that tests ran on
+that change nor that they passed. Someone saying "tested" in a conversation about
+a commit does not establish that the commit's final state was covered, and the
+change may have moved afterwards. Keep the association out of the page
+frontmatter.
+
+Evidence strength depends on what the session contains. Actual output with its
+relevant scope can support a verified result; an unsupported claim remains a
+reported result. Attribute and bound it without downgrading actual evidence
+merely because it was supplied in a conversation.

package/plugins/skills/context-sessions-indexer/templates/user-and-developer-guide.md

@@ -0,0 +1,31 @@
+# Use this in practice
+
+This is the page shape for putting one capability to use. Use it as an outline,
+not a form to fill.
+
+## Section blueprint
+
+```markdown
+## <the capability, named by what the reader does with it>
+- When to use it: the situation it fits, and the nearby one it does not
+- How: the minimal path that actually works
+- Important combinations: options or settings that only make sense together
+- Limits: what it will not do, and what to reach for instead
+```
+
+`When to use it` and `How` are required. The negative half of `When to use it`
+carries most of the value — a reader who picks the wrong capability is not helped
+by a correct description of it. `How` shows the minimal working path, not every
+option raised in discussion.
+
+`Important combinations` exists because the costly mistakes are usually
+combinations rather than single settings. Discussions are a good source for these,
+since they often start from someone hitting the combination. Include it when a
+real dependency was established, and omit it rather than generalizing from one
+report.
+
+A session gives you practice and preference mixed together. "We always do it this
+way" establishes a convention among those participants; it does not establish a
+requirement or a recommendation the organization holds. Say which one you have.
+Where a preference was stated without a reason, either the reason is in scope or
+the page presents the usage without the recommendation.

package/plugins/skills/context-sessions-indexer/tests/fixtures/profiles.json

@@ -0,0 +1,281 @@
+[
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-domain-reference",
+    "anonymized": true,
+    "profile": "domain-reference",
+    "source_role": "authoritative-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-domain-reference",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-purpose"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-domain-reference-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-domain-reference-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-product-requirements",
+    "anonymized": true,
+    "profile": "product-requirements",
+    "source_role": "authoritative-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-product-requirements",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-purpose"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-product-requirements-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-product-requirements-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-technical-guide",
+    "anonymized": true,
+    "profile": "technical-guide",
+    "source_role": "authoritative-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-technical-guide",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-structure"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-technical-guide-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-technical-guide-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-user-and-developer-guide",
+    "anonymized": true,
+    "profile": "user-and-developer-guide",
+    "source_role": "supporting-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-user-and-developer-guide",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-operation"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-user-and-developer-guide-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-user-and-developer-guide-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-runbook",
+    "anonymized": true,
+    "profile": "runbook",
+    "source_role": "operational-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-runbook",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-operation"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-runbook-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-runbook-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-faq-support",
+    "anonymized": true,
+    "profile": "faq-support",
+    "source_role": "supporting-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-faq-support",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-purpose"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-faq-support-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-faq-support-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-decision-record",
+    "anonymized": true,
+    "profile": "decision-record",
+    "source_role": "decision-record",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-decision-record",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-purpose"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-decision-record-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-decision-record-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-incident-review",
+    "anonymized": true,
+    "profile": "incident-review",
+    "source_role": "operational-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-incident-review",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-operation"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-incident-review-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-incident-review-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-test-validation",
+    "anonymized": true,
+    "profile": "test-validation",
+    "source_role": "authoritative-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-test-validation",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-operation"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-test-validation-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-test-validation-source"
+    ]
+  }
+]

package/providers/context/actions/advance-knowledge-maintenance.yaml

@@ -0,0 +1,5 @@
+schema: agent-graph.action.v1
+id: advance-knowledge-maintenance
+runner: command
+effect: write
+command: context task advance-maintenance --format json

package/providers/context/actions/author-approved-revision.yaml

@@ -0,0 +1,6 @@
+schema: agent-graph.action.v1
+id: author-approved-revision
+runner: agent
+effect: write
+skill: skills/run-indexer-agent-step/SKILL.md
+outputSchema: schemas/approved-revision-result.schema.json

package/providers/context/actions/finish-rollback.yaml

@@ -0,0 +1,5 @@
+schema: agent-graph.action.v1
+id: finish-rollback
+runner: command
+effect: write
+command: context task finish-rollback --format json

package/providers/context/actions/inspect-source-update.yaml

@@ -0,0 +1,6 @@
+schema: agent-graph.action.v1
+id: inspect-source-update
+runner: agent
+effect: write
+skill: skills/run-indexer-agent-step/SKILL.md
+outputSchema: schemas/source-update-result.schema.json

package/providers/context/actions/inspect-task-recovery.yaml

@@ -0,0 +1,5 @@
+schema: agent-graph.action.v1
+id: inspect-task-recovery
+runner: agent
+effect: read
+skill: skills/recover-workspace/SKILL.md

package/providers/context/actions/record-workspace-version.yaml

@@ -0,0 +1,5 @@
+schema: agent-graph.action.v1
+id: record-workspace-version
+runner: agent
+effect: write
+skill: skills/record-workspace-version/SKILL.md

package/providers/context/actions/register-source-batch.yaml

@@ -1,6 +1,6 @@
 schema: agent-graph.action.v1
 id: register-source-batch
-description: Register the source batch explicitly confirmed in the current conversation.
+description: Register the source batch after the complete work-start report was presented and the boundary was explicitly confirmed.
 runner: command
 effect: write
 command: context source add batch --input .tmp/agent-payloads/source-batch.json --format json

package/providers/context/actions/repair-project-entry.yaml

@@ -3,3 +3,12 @@ id: repair-project-entry
 runner: host
 effect: write
 handler: context.project.repair-entry
+# Supporting SDK manuals remain available through links, without mandatory reads.
+files:
+  - resources/manuals/reference/code-extractors.md
+  - resources/manuals/guides/knowledge-updates.md
+  - resources/manuals/guides/note.md
+  - resources/manuals/guides/sessions.md
+  - resources/manuals/guides/workspace-prepare.md
+  - resources/manuals/guides/workspace-commit.md
+  - resources/manuals/guides/workspace-restore.md

package/providers/context/actions/resume-workspace-task.yaml

@@ -0,0 +1,5 @@
+schema: agent-graph.action.v1
+id: resume-workspace-task
+runner: command
+effect: write
+command: context task resume --format json

package/providers/context/codes.yaml

@@ -1,5 +1,8 @@
 schema: agent-graph.code-catalog.v1
 codes:
+  - { code: route.version.content-changed, kind: route-reason, summary: Record an increasing workspace version and changelog for formal content changes. }
+  - { code: route.workspace.recovery, kind: route-reason, summary: Inspect a stuck task independently of normal workflow evaluation., document: resources/procedures/task-recovery.md }
+  - { code: route.indexer.maintenance, kind: route-reason, summary: Advance registered knowledge maintenance at a safe boundary., document: resources/procedures/knowledge-maintenance.md }
   - { code: diagnostic.project-entry-invalid, kind: diagnostic, severity: error, summary: The Context project entry cannot be loaded., document: resources/diagnostics/workspace-state.md }
   - { code: diagnostic.workspace-state-invalid, kind: diagnostic, severity: error, summary: Context cannot establish valid lifecycle facts for the workspace., document: resources/diagnostics/workspace-state.md }
   - { code: diagnostic.structure-snapshot-invalid, kind: diagnostic, severity: error, summary: An active source-bound structure snapshot is invalid., document: resources/diagnostics/workspace-state.md }
@@ -20,6 +23,9 @@ codes:
   - { code: route.capture.pending-target, kind: route-reason, summary: Capture the next declared document target., document: resources/procedures/document-capture.md }
   - { code: route.review.decision-required, kind: route-reason, summary: The complete current candidate batch needs one review decision set., document: resources/procedures/knowledge-review.md }
   - { code: route.review.apply-managed, kind: route-reason, summary: Apply the current candidate batch under explicit session-managed authority., document: resources/procedures/knowledge-review.md }
+  - { code: route.rollback.close-required, kind: route-reason, summary: Rebuild approved structure after the explicitly applied rollback. }
+  - { code: route.rollback.build-required, kind: route-reason, summary: Rebuild package outputs after rollback before discarding runtime. }
+  - { code: route.rollback.cleanup-required, kind: route-reason, summary: Clear the completed rollback runtime before accepting another task. }
   - { code: route.close.projection-stale, kind: route-reason, summary: Rebuild the deterministic approved structure projection., document: resources/procedures/close-and-build.md }
   - { code: route.package.output-required, kind: route-reason, summary: Approved knowledge has no confirmed package output., document: resources/procedures/package-output.md }
   - { code: route.package.configuration-required, kind: route-reason, summary: Declare the confirmed package output in the Context project., document: resources/procedures/package-output.md }
@@ -29,9 +35,12 @@ codes:
   - { code: route.indexer.lifecycle-required, kind: route-reason, summary: Continue the sole registry-and-Provider indexing lifecycle until current Candidates exist. }
   - { code: route.indexer.lifecycle-advance, kind: route-reason, summary: Advance deterministic Indexer lifecycle state to the next Agent step or user Gate. }
   - { code: route.indexer.semantic-structure-review, kind: route-reason, summary: Review the complete semantic structure and create-or-enrich targets before Author work starts. }
+  - { code: route.indexer.obsolete-scope-confirmation, kind: route-reason, summary: Resolve substantial obsolete scope from an applicable explicit decision or scope delegation; otherwise explain counts and consequences and ask the user. }
   - { code: route.indexer.recovery-required, kind: route-reason, summary: "Resolve a persisted source, material, or execution failure before retrying the Indexer lifecycle." }
   - { code: route.indexer.layout-confirmation-required, kind: route-reason, summary: Confirm the proposed knowledge layout change or reject it with revision feedback. }
   - { code: route.indexer.agent-step, kind: route-reason, summary: Run one digest-bound Indexer workset with the static Context Agent Action. }
+  - { code: route.indexer.approved-revision-recovery, kind: route-reason, summary: Merge concurrent approved changes with the pending revision before Review. }
+  - { code: route.indexer.approved-revision, kind: route-reason, summary: Revise the selected approved page using its current text and confirmed instruction. }
   - { code: route.indexer.provider-configuration, kind: route-reason, summary: Configure an exact path-free Provider selection from currently visible Indexer Skills. }
   - { code: route.indexer.provider-host-resolution-required, kind: route-reason, summary: Resolve the exact current Indexer Provider through its declared Host Action. }
   - { code: route.indexer.provider-finalization-required, kind: route-reason, summary: Deterministically validate and apply the fully resolved current Indexer Provider selection. }
@@ -83,3 +92,5 @@ codes:
   - { code: route.indexer.incremental-impact, kind: route-reason, summary: "Report exact logical-unit, Artifact, and Section impact from complete current Merkle dependency views." }
   - { code: route.indexer.candidate-review, kind: route-reason, summary: Review the exact current candidate set only after current mechanical validation passes. }
   - { code: route.indexer.approved-knowledge-close, kind: route-reason, summary: Atomically close approved Indexer structure after required material gaps are resolved. }
+  - { code: route.indexer.source-update, kind: route-reason, summary: Inspect fixed source changes against current approved pages. }
+  - { code: route.workspace.task-cleared, kind: route-reason, summary: Task state is cleared and production awaits an explicit resume request., document: resources/procedures/workspace-prepare.md }