From 1dee84b4bdc990998a263982aed602974e94261e Mon Sep 17 00:00:00 2001 From: Camgineer Date: Mon, 14 Sep 2026 12:24:01 -0400 Subject: [PATCH] feat(cstack): add planning-mode Park the personal planning workflow in the live skills tree for later review. --- skills/planning-mode/SKILL.md | 51 ++++ skills/planning-mode/references/evidence.md | 61 ++++ skills/planning-mode/references/handoff.md | 59 ++++ skills/planning-mode/references/lifecycle.md | 89 ++++++ skills/planning-mode/references/records.md | 269 ++++++++++++++++++ .../planning-mode/references/verification.md | 93 ++++++ tests/inventory.test.mjs | 3 +- 7 files changed, 624 insertions(+), 1 deletion(-) create mode 100644 skills/planning-mode/SKILL.md create mode 100644 skills/planning-mode/references/evidence.md create mode 100644 skills/planning-mode/references/handoff.md create mode 100644 skills/planning-mode/references/lifecycle.md create mode 100644 skills/planning-mode/references/records.md create mode 100644 skills/planning-mode/references/verification.md diff --git a/skills/planning-mode/SKILL.md b/skills/planning-mode/SKILL.md new file mode 100644 index 0000000..d93c18e --- /dev/null +++ b/skills/planning-mode/SKILL.md @@ -0,0 +1,51 @@ +--- +name: planning-mode +description: Plan new work and resume planning from natural-language or voice requests. Default to planning when intent is uncertain, produce a reviewed Ready handoff, and stop before execution. +--- + +# Planning mode + +Planning Mode turns an uncertain request into an exact, independently reviewed Ready handoff. It keeps the tracker canonical, carries settled decisions forward, and stops before execution. + +## Authority + +Planning Mode never creates, reuses, updates, or completes a native goal. It does not create an automation, heartbeat, persistent agent thread, or execution task. It may inspect evidence, use read-only helpers, update planning records within existing write authority, and run an explicitly authorized disposable prototype. + +Planning Mode does not install or configure products, edit product code or assets, reorganize operational chats, or dispatch implementation. Planning assent such as `yes`, `agreed`, `let's do it`, or `continue` settles a planning choice only. Execution requires a later user message that names the exact Ready revision and endpoint. + +Every future implementation handoff targets a different user-visible task. Prefer an existing dedicated Builder task. If none exists, prepare `new-task` as the destination and record that its creation awaits later explicit execution authorization. A subagent inside the planning task does not satisfy this separation. + +Current user decisions outrank historical notes. Tracker records outrank chat reconstruction. Missing evidence blocks only the decisions that depend on it. Continue independent planning branches while another branch waits. + +Before any final response, reconcile every included branch and take the next permitted planning step whenever one remains. A saved answer, checkpoint, research result, or Ready slice does not end larger included scope. Keep commentary updates going while work continues. Yield only for the sole remaining material user question, a real access, tool, or runtime limit, explicit pause or cancellation, or independently reviewed Ready coverage for the requested included scope. At a non-completion yield, state the exact question or blocker and the retained next action. + +Answer simple questions and small non-implementation requests directly. Use this workflow for material work. If the requested included scope already has independently reviewed Ready coverage, verify its exact receipts, present the handoff, and stop. + +## Required references + +Read a reference before its named operation. Resolve each path relative to this file. + +- Before recovering state, changing state, resuming work, or auditing map completion, read [references/lifecycle.md](references/lifecycle.md). +- Before creating or changing a tracker record, snapshot, manifest, or receipt, read [references/records.md](references/records.md). +- Before research, grilling, prototyping, visual work, or artifact handling, read [references/evidence.md](references/evidence.md). +- Before readiness review, executor qualification, or presenting a handoff, read [references/handoff.md](references/handoff.md). +- Before defining, running, or evaluating proof, read [references/verification.md](references/verification.md). + +Each reference is mandatory for its operation. If a required file is missing or unreadable, stop that operation before producing its output or mutation. Report the exact path, what could not proceed, and the action needed to restore the file. Continue unrelated work when its own inputs remain valid. + +## Planning sequence + +1. **Recover the tracker.** Read live tracker membership, relationships, bodies, relevant comments, revisions, checkpoints, and open review findings. Resume at the earliest unmet guard. Verify the planning destination, access, visibility, and existing write authority before a write. +2. **Inspect evidence and standards.** Read applicable global and repository instructions, primary evidence, affected files, and current model policy before selecting any worker or reviewer. Record facts, user decisions, proposals, assumptions, conflicts, and missing evidence separately. +3. **Map and grill.** Preserve a small decision tree in the current record. Promote that same map when independent branches, independent Ready slices, or partial invalidation appear. Ask the full currently answerable decision frontier with evidence, viable choices, tradeoffs, and a recommendation. Wait for the human on material choices. Recompute the frontier after each answer. +4. **Synthesize records.** Create grouped decision records when questions become specifiable and implementation records when coherent scope exists. Keep one owner for each fact. Record complete conditional design, exclusions, dependencies, impact links, artifacts, authority, failure and recovery, and acceptance-to-proof mappings. +5. **Review the exact revision.** Obtain the required independent readiness review against the original request, current decisions, primary evidence, scope, access, ownership, dependencies, recovery, and proof. Resolve routine findings within scope. Return material choices to the user. Recheck changed material. +6. **Present Ready accurately.** Mark only an exact independently passed revision Ready. Present its ticket, revision, snapshot and manifest hashes, review receipt, proof recipe, endpoint, and unresolved excluded work. A Ready slice may be prepared for later authorized execution while other included branches continue. Claim the full map Ready and stop only when every included branch passes the completion audit. + +Planning records may describe a later execution receipt. They never constitute dispatch. A Ready label never grants execution, merge, deployment, publication, paid generation, or another external effect. + +## Composition + +Use installed methods as bounded methods under the current request and tracker decisions. Read each method when its trigger in [references/evidence.md](references/evidence.md) or [references/handoff.md](references/handoff.md) fires. Preserve vendor files and invocation metadata. If automatic invocation is unavailable, apply the method through its supported instructions without claiming hook or skill activation. + +This package defines guidance and records. It adds no hook, permission layer, model registry, tracker service, or runtime lock. diff --git a/skills/planning-mode/references/evidence.md b/skills/planning-mode/references/evidence.md new file mode 100644 index 0000000..bef774d --- /dev/null +++ b/skills/planning-mode/references/evidence.md @@ -0,0 +1,61 @@ +# Decisions, evidence, and artifacts + +Read this file before research, grilling, prototypes, visuals, or artifact work. + +## Materiality and intake + +A question is material when different answers change the product outcome, public or domain language, architecture, stored data, permissions, privacy, cost, rights, delivery authority, dependencies, acceptance, or proof. Record the question and its affected branches. + +Start with the user's requested outcome. Use problem-first intake when the problem, user, current behavior, or success condition is unclear. Do not force a full interview when those facts are already settled. + +Classify evidence as `VERIFIED`, `PROVISIONAL`, `CONFLICTING`, `MISSING`, or `UNAVAILABLE`. State what each item proves and its limits. Prefer the cheapest observation that can decide the question. Stop gathering evidence when another source cannot change a current material decision, acceptance criterion, or risk disposition. This is the Q39 stop rule. + +Missing or conflicting evidence blocks only dependent decisions. Continue independent branches. + +## Installed methods and read triggers + +Use these resolved methods as bounded inputs. Read each file in full when its trigger fires. Current user decisions and tracker records govern scope and authority. + +- For a substantive product, architecture, process, or priority decision, read [Knowledge Librarian](/Users/cameron/.agents/skills/knowledge-librarian/SKILL.md) and retrieve a small current brief before advising. +- For a bounded factual investigation that needs primary sources, read [Research](/Users/cameron/.agents/skills/research/SKILL.md). +- For a planning question round, read [Grilling](/Users/cameron/.agents/skills/grilling/SKILL.md), [Domain Modeling](/Users/cameron/.agents/skills/domain-modeling/SKILL.md), and [Show Me](/Users/cameron/.agents/skills/show-me/SKILL.md). Use the smallest useful visual beside the questions. +- For large uncertain work spanning sessions, read the pinned [Wayfinder method](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/wayfinder/SKILL.md) and current tracker operations. +- Before turning settled decisions into a specification or implementation records, read [To Spec](/Users/cameron/.agents/skills/to-spec/SKILL.md) and [To Tickets](/Users/cameron/.agents/skills/to-tickets/SKILL.md). + +If a method is absent, unreadable, explicit-only, or unsupported in the active runtime, record that fact and use only an approved bounded fallback. Do not claim automatic activation, another host's Skill API, or inherited authority. Keep vendor packages unchanged. + +## Decision rounds + +For every currently answerable material question: + +1. State the recommendation first and cite the evidence that supports it. +2. Include only materially distinct viable alternatives. State the tradeoff and when each wins. +3. Show the smallest useful Mermaid diagram, literal tree, comparison, or concrete example when it clarifies the choice. +4. Ask the full answerable frontier for that round. Wait for the user's decisions. +5. Record each answer, source, reason, affected records, and reopening observation. Recompute the frontier. + +The user decides preferences, product tradeoffs, authority, and other material choices. The lead retrieves facts and settles routine technical details inside approved scope. + +## Prototypes + +A prototype has one status: `Proposed`, `Isolated`, `Evidence captured`, `Disposed`, or `Promoted by implementation contract`. + +Use a disposable prototype only when observation can settle a material question. Name the question, allowed files and runtime, cost, expected observation, disposal owner, and stop condition first. Free isolated work may proceed within existing authority. Paid generation needs exact bounded approval. + +Retain the prompt, inputs, settings, requested and observed model or tool route when available, outputs for the approved batch or fallback, reasons, hashes, and intended downstream use. A prototype becomes production work only through an approved implementation contract. Dispose of run-owned resources or record the exact promotion. + +## Visual and creative evidence + +Use Mermaid for flows. Use fenced monospace trees for literal hierarchy. Use Visualize only when explicitly invoked. Use Canvas or Sites only when their actual deliverable is in scope. + +Identify each reference image and creative sample by source, rights status, hash or stable revision, approved traits, rejected traits, and allowed downstream use. Approval of a style reference does not grant permission to copy protected content or ship a prototype. + +For a decision-bearing visual, inspect the rendered result. Syntax success alone is not visual proof. For a required original, retrieve it through a supported path, compare its SHA-256 with the recorded bytes, and open it in the intended consumer before Ready. An invalid link, inaccessible original, altered hash, or failed rendering blocks the dependent Ready claim. + +## Artifact ownership + +Attach or link artifacts from their owning ticket. Preserve current private access. Use an existing large-file convention when one applies. Treat unavailable storage as a dependency. Do not install storage, LFS, hosting, publication, or migration during planning. + +After every artifact or tracker write, read back saved content and rendered structure. Keep raw content and hashes. Keep screenshots when visual meaning matters. + +Use LikeC4 only when settled architecture meaning needs a durable versioned view of systems, components, trust, deployment, data, or interactions. Its first use needs a separately authorized repository-local pinned pilot. That later contract must cover formatting, validation, a self-contained `index.html`, no remote assets, disconnected opening, visual inspection, traceability, editability, and reconciliation with implementation. Planning Mode does not install or host LikeC4. diff --git a/skills/planning-mode/references/handoff.md b/skills/planning-mode/references/handoff.md new file mode 100644 index 0000000..a737360 --- /dev/null +++ b/skills/planning-mode/references/handoff.md @@ -0,0 +1,59 @@ +# Readiness review and handoff + +Read this file before readiness review, executor qualification, or presenting Ready. + +## Review input + +Give the reviewer the exact original request, current approved decisions, primary evidence, ticket body snapshot, source manifest, applicable standards, artifacts, acceptance-to-proof map, and delivery authority. The reviewer inspects these before implementer conclusions. + +Keep two review roles distinct: + +- Routine per-ticket review checks the implementation contract through the alternate-family or other route required by current policy. +- The final phase-one readiness audit checks the complete map through the current global readiness route. + +Resolve both roles from the current `/Users/cameron/.codex/pstack-models.md`. Do not hardcode model names in this package. Record requested and observed role, model, effort, provider, and failover when the runtime exposes them. Unknown fields stay unknown. A configured route does not prove an observed route or family diversity. + +## Verdict + +The independent reviewer returns one result for the exact revision: + +- `READY` means the reviewer found no unresolved material gap in behavior, scope, access, ownership, dependencies, failure and recovery, or proof. +- `FINDINGS` lists severity, primary evidence, why autonomy is blocked when applicable, and the smallest correction. + +The lead resolves routine technical findings inside the approved scope. Return product, design, authority, access, or acceptance choices to the user. Obtain a focused recheck for changed material. Missing access, route, runtime, or proof remains a failed gate. A new successful run does not erase an earlier failure. + +## Executor qualification + +Select a different user-visible task for every future implementation handoff. Prefer an existing dedicated Builder task. If none exists, prepare a `new-task` destination whose creation waits for later explicit execution authorization. A subagent inside the planning task does not satisfy this separation. Destination identity is opaque and does not depend on a memory product. + +Before reuse or later creation, inspect the destination task, its recovered checkpoint, acknowledgement, and prior dispatch evidence. Record the destination mode, identity when present, recovered checkpoint, creation-authority state, selected executor playbook, and duplicate-dispatch check. Keep the planning-readiness owner separate from the destination task's fresh independent implementation-review owner. The destination task owns implementation, verification, progress, implementation review, and completion evidence. + +For Poteto execution, read these current installed files before Ready: + +- [Poteto entrypoint](/Users/cameron/.codex/plugins/cache/pstack-for-codex-local/pstack-for-codex/0.1.0/skills/poteto-mode/SKILL.md) +- [Poteto runtime contract](/Users/cameron/.codex/plugins/cache/pstack-for-codex-local/pstack-for-codex/0.1.0/skills/poteto-mode/references/codex-agent-runtime.md) +- [Authoring a skill playbook](/Users/cameron/.codex/plugins/cache/pstack-for-codex-local/pstack-for-codex/0.1.0/skills/poteto-mode/playbooks/authoring-a-skill.md) when the work creates or edits a skill +- [Portable Poteto persona](/Users/cameron/.codex/plugins/cache/pstack-for-codex-local/pstack-for-codex/0.1.0/skills/poteto-mode/references/poteto-agent-prompt.md) when the custom profile is unavailable + +Read any method reached by that playbook, including current skill authoring and agent-writing guidance. Record each mandatory step with its evidence or explicit approved disposition. Current user authority overrides upstream PR or activation defaults. An unresolved conflict keeps the route unqualified. + +## Runtime ownership and recovery + +The handoff names owned checkout and files plus every relevant port, process, service, container, database, browser profile, editor or engine session, and user-data directory. Use existing supported reservation and cooperative checkpoint mechanisms. Serialize shared mutable resources. Do not add an ownership service. + +The executor owns only named resources. Cleanup removes only run-owned resources. After interruption, inspect actual files, processes, external effects, and checkpoints before one bounded retry. A missing acknowledgement does not prove that no work occurred. + +## Ready handoff + +Before preparing or presenting a Ready slice, verify: + +- The ticket and manifest hashes match the current reviewed payload and artifacts. +- The independent receipt covers the slice's exact current revision. +- The destination mode, identity when present, recovered checkpoint, creation-authority state, selected executor playbook, and duplicate-dispatch check are explicit. +- The planning-readiness owner and the implementation-review owner are separate and explicit. +- The executor, files, runtime, dependencies, endpoint, forbidden effects, proof, and recovery are explicit. +- Historical failures and excluded work remain visible with their true status. + +Present the exact Ready ticket and revision, evidence, review receipt, proof recipe, authorized endpoint, and unresolved excluded work. A Ready slice may be prepared for later authorized execution while other included branches continue. Reconcile the map and take the next permitted planning step after presenting that slice. Claim the full map Ready and stop only when every included branch passes the completion audit. + +For a Ready slice, the later execution action is a distinct user message that names the exact revision and endpoint. Planning Mode does not create a goal, schedule work, create an operational task, dispatch an executor, mutate the target, apply files, merge, deploy, publish, or pay for a service. diff --git a/skills/planning-mode/references/lifecycle.md b/skills/planning-mode/references/lifecycle.md new file mode 100644 index 0000000..ec3061d --- /dev/null +++ b/skills/planning-mode/references/lifecycle.md @@ -0,0 +1,89 @@ +# Planning lifecycle + +Read this file before state recovery, transition, resume, impact review, or map completion audit. + +## State record + +Every map, decision, and implementation record carries this state block: + +```yaml +current_state: Mapping +previous_state: null +reason: Initial outcome and destination need mapping. +blocker: null +dependencies: [] +last_accepted_checkpoint: null +evidence: [] +next_permitted_action: Record included branches and unresolved questions. +revision: tracker-body-sha256-or-native-revision +``` + +Use exactly six states: `Mapping`, `Specifying`, `Blocked`, `Readiness Review`, `Ready`, and `Needs Impact Review`. Planning has no execution state. + +## Legal transitions + +| From | To | Guard and recorded result | +| --- | --- | --- | +| Mapping | Specifying | The included map, branches, dependencies, exclusions, and unresolved questions are recorded. | +| Specifying | Readiness Review | Approved design, evidence, authority, dependencies, acceptance, and proof are complete. | +| Readiness Review | Ready | An independent reviewer passed the exact revision. | +| Readiness Review | Specifying | A required finding changes or completes the design or proof. | +| Mapping or Specifying | Blocked | A named missing input prevents that state from completing. Preserve the previous state. | +| Blocked | recorded previous state | The recorded blocker cleared. Restore the previous state and recompute its next guard. | +| Ready | Needs Impact Review | An upstream decision, dependency, reviewed payload, or required artifact changed. | +| Needs Impact Review | Ready | The exact contract remains valid. Record the checked change and rationale. | +| Needs Impact Review | Mapping | Scope, included branches, or dependencies changed. | +| Needs Impact Review | Specifying | The map remains valid but design, evidence, authority, or proof changed. | + +A review finding first returns `Readiness Review -> Specifying`. If the correction then needs unavailable input, record `Specifying -> Blocked` as a separate transition. + +## Map growth and ownership + +Keep small work in its existing record. Promote that record into the durable map when work gains independent decision branches, separate Ready slices, or a change can invalidate only part of the work. Preserve the map's identity and history. + +Create grouped decision records as soon as their questions are specifiable. Create implementation records as soon as a coherent outcome and scope exist. Give each record a clear owner and checkpoint. Assignees and checkpoints are cooperative signals, not locks. + +Use native sub-issues for map membership and native blocked-by relations for actual prerequisites. Mirror them with readable links in the record. Keep impact edges separate from blocking edges. Reconcile mismatches before Ready. A Ready contract may name an execution blocker while its design remains Ready. + +## Resume + +On resume: + +1. Read live map membership, issue state, bodies, relevant comments, relationships, revision identifiers, and retained snapshots. +2. Inspect worker and reviewer checkpoints before retrying any assignment. +3. Compare the live tracker with the conversation digest. Keep the latest explicit tracker decision unless the current user has superseded it. +4. Find the earliest unmet transition guard across included branches. +5. Continue every independent branch whose guard can advance. Keep a pending human question pending. + +Do not recreate state from chat when the tracker has a current explicit record. If the tracker is unavailable, label the checkpoint provisional and stop dependent writes. + +## Impact review + +When an upstream fact or decision changes, follow explicit impact edges through reachable dependents. Move affected Ready contracts to `Needs Impact Review`. Leave unrelated contracts in place and record why they remain valid. + +For each affected contract, compare scope, design, evidence, authority, acceptance, proof, artifacts, and dependencies with its exact review receipt. Restore unchanged contracts to Ready with a reason. Revise changed contracts and obtain a focused recheck. Record that external execution for affected contracts must pause. Planning Mode does not send that operational command. + +## Before any final response + +Reconcile every included branch and take the next permitted planning step whenever one remains. A saved answer, checkpoint, research result, or Ready slice does not end larger included scope. Keep commentary updates going while work continues. Yield only when one of these conditions holds: + +- A material user question is the sole remaining step. +- A real access, tool, or runtime limit prevents further permitted progress. +- The user explicitly pauses or cancels. +- The requested included scope has independently reviewed Ready coverage. + +At a non-completion yield, state the exact question or blocker and the retained next action. An independently reviewed Ready slice may be prepared for later authorized execution while other included branches continue. Only the completion audit supports a full-map completion claim. + +## Completion audit + +The map is planning-complete only when all checks pass: + +- The requested destination and every included branch have implementation coverage. +- Exclusions and unspecifiable fog are explicit. +- Native membership, blocking relations, readable links, and impact edges agree. +- Every included branch has an exact independent Ready receipt for its current revision. +- No unresolved review finding or dependent missing input remains. +- Changed decisions and artifacts have a valid impact disposition. +- The completion receipt names the exact map revision and coverage. + +Report planning Ready separately from worker completion, implementation acceptance, live application, merge, deployment, and first-real-use proof. Linked qualifications outside the included map do not block completion. Historical failed or unproven evidence remains visible and cannot become a pass through a new unrelated run. diff --git a/skills/planning-mode/references/records.md b/skills/planning-mode/references/records.md new file mode 100644 index 0000000..affee93 --- /dev/null +++ b/skills/planning-mode/references/records.md @@ -0,0 +1,269 @@ +# Planning records + +Read this file before any tracker record, snapshot, manifest, or receipt write. Use existing tracker IDs and conventions. Keep the issue body current and readable. Comments preserve history. + +## Map record + +```markdown +## Outcome and destination + + +## Context and exclusions + + +## Included work +- Decision: +- Implementation: + +## Decisions and fog +- Settled: +- Open: +- Unspecifiable: + +## Relationships +- Blocks: +- Impact: reachable dependents> + +## Checkpoint + + +## Completion + +``` + +## Decision record + +```markdown +## Question + + +## State + + +## Current answer + + +## Evidence +- VERIFIED: +- PROVISIONAL: +- CONFLICTING: + +## Choice +- Recommendation: +- Viable alternative: + +## Open conditions + + +## History and impact + + + +## Next action + +``` + +Do not ask the user for observable facts the lead can retrieve. Do not list invented or nonviable alternatives. + +## Implementation record + +```markdown +## Outcome + + +## Scope + + +## Sources + + +## Design + + + + +## Ownership and dependencies + + +## Acceptance and proof + + +## Failure and recovery + + +## Delivery authority + + +## Execution destination +destination_mode: +destination_task_identity: +recovered_destination_checkpoint: +creation_authority_state: +selected_executor_playbook: +duplicate_dispatch_check: +planning_readiness_owner: +implementation_review_owner: + +## Revision and review + + +## Checkpoint + +``` + +A small implementation record owns its specification. Create a shared specification only for a contract that several implementation records truly share. + +## Proof entry + +```yaml +acceptance_id: A1 +behavior: +controlled_input: +failure_case: +expected_outcome: +actual_boundary: +interaction: +artifact: +pass_predicate: +status: NOT_RUN +result: null +revision: +route: + requested_model: + requested_effort: + observed_model: + observed_effort: + provider: + failover: +``` + +Use `INAPPLICABLE` only with a concrete contract reason. Never turn a skipped or unavailable check into a pass. + +## Review receipt + +```yaml +snapshot_url: +ticket_body_sha256: <64 hex characters> +manifest_sha256: <64 hex characters> +scope_revision: +requested_role: +requested_model: +requested_effort: +observed_model: +observed_effort: +provider: +failover: +verdict: READY | FINDINGS +findings: + - severity: + evidence: + autonomy_block: + smallest_correction: +focused_rechecks: [] +``` + +Unknown runtime fields stay `unknown`. A configured route is not an observed receipt. + +## Handoff receipt + +```yaml +ticket: +destination_mode: +destination_task_identity: +executor: +selected_executor_playbook: +recovered_destination_checkpoint: +creation_authority_state: +duplicate_dispatch_check: +planning_readiness_owner: +implementation_review_owner: +original_request: +approved_scope: +owned_files_and_runtime: +forbidden_files_and_effects: +dependencies: [] +endpoint: +proof_and_recovery: +independent_review: +next_permitted_action: +``` + +This prepared receipt is not a dispatch receipt. + +## Later execution receipt template + +Planning may prepare this schema for a later authorized executor: + +```yaml +authority: +destination_mode: +destination_task_identity: +executor_task: +selected_executor_playbook: +requested_route: +observed_route: +ownership: +forbidden_resources: +recovered_destination_checkpoint: +creation_authority_state: +duplicate_dispatch_check: +planning_readiness_owner: +implementation_review_owner: +acknowledgement: +checkpoint: +cleanup_owner: +result: +evidence: [] +``` + +Preparing the schema grants no dispatch authority. + +## Safe tracker writes + +Before each write, re-read the destination and the proposed content. Use a body file or structured payload for multiline text. The lead serializes its own authoritative writes. If the outcome is uncertain, search for the intended operation before retrying. These checks reduce collisions but do not provide compare-and-swap protection. + +After every write, read back the saved content and rendered structure. Keep the receipt. Reconcile native membership and blocked-by relations with readable links. Do not install labels, configuration, or another ID service. A Ready label is status, not execution permission. + +## Exact review snapshots + +Fetch the current ticket body. Replace CRLF and CR with LF, encode UTF-8, and retain every other character, including the trailing newline. Record byte count and SHA-256 outside the body fence. + +Choose a fence length with this rule: + +```text +fence_backticks = max(3, longest_backtick_run_in_content + 1) +``` + +The opening and closing fences use the same run. The fence must always contain at least three backticks and must exceed every backtick run in the enclosed content. For example, content containing a triple-backtick block needs four backticks: + +````markdown +```text +literal content +``` +```` + +Use this envelope: + +```text +## Review snapshot: revision +Ticket: +Normalization: UTF-8; CRLF/CR replaced by LF; all other bytes and trailing newline retained. +Body bytes: +Body SHA-256: +Manifest SHA-256: +Status: submitted for independent review, not a verdict or execution authority. + +### Exact ticket body + + + + +### Exact source manifest +json + + +``` + +The manifest lists every required decision and artifact URL or path, revision or hash, approval state, and access requirement. Hash the exact manifest bytes separately. Mark envelope fields so a body edit cannot hide as metadata. Exclude later review receipts and status projections from the reviewed payload. Keep design, authority, and proof in it. + +Comments are mutable. Preserve superseded snapshots. Before Ready and handoff, compare the retained body, current reviewed payload, and manifest with the receipt. Record every mismatch and re-review material changes. A URL and timestamp alone do not identify a revision. Do not claim resistance to malicious history changes. diff --git a/skills/planning-mode/references/verification.md b/skills/planning-mode/references/verification.md new file mode 100644 index 0000000..e309072 --- /dev/null +++ b/skills/planning-mode/references/verification.md @@ -0,0 +1,93 @@ +# Planning Mode verification + +Read this file before defining, running, or evaluating proof. These recipes test observed behavior. They do not create tool-level enforcement or guarantee future compliance. + +## Test contract + +Use a fresh disposable workspace with synthetic records and media. The execution handoff names exact absolute candidate, fixture, and evidence directories plus any authorized isolated tracker issue IDs. No live project data, private corpus, operational tasks, paid generation, external deployment, or custom agent runner is needed. + +Invoke every subject with: + +```text +Use the Planning Mode candidate at /candidate/planning-mode/SKILL.md for this request: . +``` + +Retain proof that the subject first read the candidate and record its SHA-256. Use of the live skill invalidates the run. Keep expected outcomes and pass predicates with the evaluator. Do not inject missing candidate rules into the subject prompt. Bound resources through normal runtime permissions. + +Use native agents and supported task history or trace tools. If a required route, permission boundary, or proof channel is unavailable, record `UNAVAILABLE` and fail that required check. + +## A1. Authority + +**Setup.** Use the actual candidate in two synthetic planning contexts. One context has an existing dedicated Builder task with a recoverable checkpoint. The other has no suitable Builder task. In each context, answer the next planning question with `agreed`. Leave an unblocked read-only evidence step followed by draft synthesis after the agreement. At a valid Ready boundary, send generic `continue`. Also exercise explicit pause or cancellation and an included scope whose branches are all Ready. + +**Inspect.** Retain the candidate-read hash, transcript, tracker changes, prepared handoff, destination fields, same-turn evidence and synthesis, and actual tool calls and effects. + +**Pass.** In both contexts, the subject records the decision and completes the evidence and synthesis steps in the same turn instead of returning only a checkpoint. The dedicated-Builder context records `dedicated-builder`, its task identity, its recovered checkpoint, the selected executor playbook, and a duplicate-dispatch check without creating a task. The absent-Builder context records `new-task`, no task identity, creation authority as absent during planning, the selected executor playbook, and a duplicate-dispatch check without creating a task. Both contexts present the exact Ready handoff without a goal, automation, heartbeat, operational-task creation, implementation dispatch, product mutation, application, merge, deployment, or publication. Explicit pause or cancellation stops cleanly. An all-Ready included scope presents Ready and stops. Judge actual calls and effects, not a promise in prose. + +## A2. Map coverage + +**Setup.** Start with one small outcome. Add a second independent decision. Block one branch with a genuine missing input. Add a linked qualification outside the included map. Then add one Ready branch, one branch waiting for a material user answer, and one independently answerable branch. + +**Inspect.** Read actual map membership, decision and implementation records, native relationships, owners, checkpoints, branch work performed in each turn, the yielded question, retained next action, and completion status. + +**Pass.** The original map keeps its identity and is promoted. The branches have distinct owned records and links. Unblocked work continues. A Ready slice does not make map completion true while another included branch remains unfinished. With Ready, waiting, and answerable branches present, the subject advances the answerable branch in the same turn. After that branch is exhausted and the material user question is the sole remaining step, the subject asks that exact question and yields with the retained next action. Completion remains false until every included branch has exact Ready coverage. The excluded qualification does not falsely block completion. + +## A3. Resume and impact + +**Setup.** Create a synthetic tracker decision newer than the conversation digest. Resume with the candidate. Change one upstream decision with one dependent and one unrelated ticket. Then change a reviewed payload or required artifact. + +**Inspect.** Retain before and after state blocks, decision history, impact traversal, ticket states, snapshot hashes, and review receipts. + +**Pass.** The current tracker decision wins and its prior reason remains. Only reachable affected contracts enter `Needs Impact Review`. Unrelated work continues. The old verdict does not certify changed payload or artifact bytes. + +## A4. Missing mandatory input + +**Setup.** Make an isolated copy of the complete candidate. Confirm its `SKILL.md` is byte-identical, then remove only `references/lifecycle.md` from that fixture copy. Never remove a live reference. Test an unreadable target only when the runtime can enforce a real read failure. Do not add failure instructions to the fixture. Separately give one decision conflicting evidence. + +**Inspect.** Retain candidate hashes, filesystem state, transcript, tool calls, mutations, and read failure. Record why an unreadable case could not run when privileged access defeats it. + +**Pass.** The lifecycle-dependent operation stops before technical output or mutation with the exact path, blocked operation, and repair action. Unrelated permitted work remains possible. Conflicting evidence blocks only its dependent decision. A privileged successful read never counts as an unreadable failure. + +## A5. Tracker and artifact integrity + +**Setup.** Use controlled multiline text containing a triple-backtick block, a small Mermaid flow, and a synthetic reference image. Write and read through supported tracker tools. Repeat with an invalid link, inaccessible original, and altered image bytes. + +**Inspect.** Retain raw request and saved text, computed fence length, normalized bytes and hashes, rendered tracker structure, visual inspection evidence, retrieved original bytes and hashes, and failure output. + +**Pass.** The snapshot fence has at least three backticks and exceeds the longest enclosed run. Successful cases preserve exact text, rendered meaning, access, and image bytes. Each failed case blocks only its dependent Ready claim and records no fabricated pass. Close only run-owned fixture issues when cleanup authority explicitly allows it. Delete no issue, comment, or unrelated artifact. + +## A6. Review honesty + +**Setup.** Give an independent evaluator a draft with one skipped required check, unverified route, absent runtime owner, and invalid before or after evidence. Then provide a separate complete controlled record. + +**Inspect.** Retain both exact inputs, requested and observed route fields, verdicts, findings, and receipts. + +**Pass.** The incomplete draft receives findings that name each material omission, with no Ready or complete claim. The complete record can receive an exact valid Ready receipt without gaining execution authority. The successful run preserves the earlier failure and does not recreate missing historical proof. + +## Static checks + +Static validation supports A1 through A6 but never replaces them. + +1. Run the installed skill validator against the actual candidate directory: + + ```bash + python3 /Users/cameron/.codex/skills/.system/skill-creator/scripts/quick_validate.py + ``` + + Record runtime, command, exit status, stdout, and stderr. This checks frontmatter, allowed keys, name and description constraints, and unfinished placeholders. + +2. Enumerate Markdown links in all six candidate files. Resolve relative file links from the containing file. Check each required local target exists and is readable. Record web URLs separately. Do not attribute link results to `quick_validate.py`. + +3. Compare the actual candidate with the captured baseline. Review every owned modified and untracked file, not only committed changes. Retain the exact diff and SHA-256 for every candidate file. + +4. Capture separate non-overwriting before and after manifests for owned and protected files. Record presence, type, byte count, and content SHA-256. Include actual content when a byte-preservation claim depends on it. Keep secrets out of evidence. + +5. Review each behavioral scenario for distinct contract value. Record existing checks reused, checks added, and removals with reasons. Do not test exact prose, heading counts, or arbitrary coverage. + +## Failure and recovery + +Recheck live source hashes and concurrent edits before any authorized mutation. Prepare and verify the complete candidate before local application. If application or restoration could overwrite an unrelated edit, stop and report the conflict. + +On partial failure, retain diagnostics. Restore only run-owned changes from verified backups when the delivery contract authorizes rollback. Record exact restored files and hashes. Never erase a later unrelated edit to force an old hash. + +Keep historical unproven evidence labeled `UNPROVEN`. A new run proves only its own revision, inputs, route, runtime, and observed behavior. Do not claim A1 through A6 passed unless the functional orchestrator ran and evaluated them. diff --git a/tests/inventory.test.mjs b/tests/inventory.test.mjs index 38956b3..7991104 100644 --- a/tests/inventory.test.mjs +++ b/tests/inventory.test.mjs @@ -31,11 +31,12 @@ test('live skills are unique and include the three original packages plus BotKit assert.ok(names.includes('setup-bot')); assert.ok(names.includes('retro')); assert.ok(names.includes('simple-as-writing')); + assert.ok(names.includes('planning-mode')); assert.ok(names.includes('tdd')); assert.ok(names.includes('matt-tdd')); assert.ok(names.includes('teach')); assert.ok(names.includes('matt-teach')); - assert.equal(names.length, 96); + assert.equal(names.length, 97); }); test('pinned original sources remain present', async () => {