create-agdf 0.20.2 → 0.31.0

package/generated/plugins/agdf/runtime/create-agdf/generated/plugins/agdf/meta/contracts/task-target-resolution.md

@@ -154,3 +154,27 @@ result; it must not resolve targets, derive governance or become a state store.
 Show orientation when target/context separation is material, when the target changes, or when the
 result is unresolved. Avoid redundant presentation for an obvious unchanged target. Presentation
 never grants mutation or gate authority.
+
+## Worktree Placement And Assigned Checkout
+
+When choosing a new worktree for an initiative, use
+`<owning-primary-checkout>/.agdf/worktrees/<initiative>/`. Determine the primary owner from
+Git common-directory/worktree metadata through the existing repository-context/Git boundary;
+a linked checkout's cwd is not the owner. Resolve unclear ownership, unsafe initiative paths
+and destination collisions before creation. Reuse an already assigned worktree for the coherent
+initiative; do not recursively create another worktree inside it. This rule does not require
+worktrees for every trivial task.
+
+Verify that the owning checkout ignores the container before creating a worktree. Preserve an
+existing correct ignore mechanism. Otherwise prepare a contained `.agdf/worktrees/.gitignore`
+with an ignore-all rule for its contents, preserving foreign rules, and verify the destination
+with `git check-ignore`. This is preparation guidance, not permission for an automatic manager
+to create/switch/move/clean worktrees or edit arbitrary ignore files.
+
+Existing locations and explicit user-instructed alternatives remain supported; record the
+assignment/exception rather than moving existing work. One writer continues each Run in its
+assigned checkout; reviewers read only. Path/branch names confer no authority and checkout-path
+target identity does not enforce branch/HEAD binding or cross-checkout locks. Never share or
+symlink control stores. New worktrees do not copy untracked Run artefacts; inventory and preserve
+registered/untracked evidence before separately authorized handoff or cleanup. Global plugins,
+configuration, ports and external services are not isolated by Git worktrees.

package/generated/plugins/agdf/runtime/create-agdf/generated/plugins/agdf/meta/contracts/tp-definition.md

@@ -69,6 +69,14 @@ not independent proof of human provenance. Table headings may use levels two thr
 
 ## Recording and revision
 
+A returned bound authoring continuation for an incomplete own unapproved draft already
+selects its correction route. Consume its authoring-inputs/material_call/recording_calls
+forms directly and use the supplied update_draft value. Do not dispatch this author again
+or add another intake for that same snapshot. The *_action revise route below is only for
+NEW editing intent on an already READY draft, and uses skill_id gate-check, never an author
+skill ID or a host skill alias. After saving, follow the returned continuation once.
+
+
 A ready draft without new editing intent is presented unchanged. Explicit ready-draft revision uses
 gate-check intake true, intake_mode resume, exact run_id/expected_revision_id and tp_action revise
 (CLI --tp-action revise), exclusive of other source actions and continue_delivery. Approved changes
@@ -76,7 +84,7 @@ use their existing source-revision owner. Eligible incomplete-draft correction n
 source/integrity blockers.
 
 Use gate-artifact-preparation's shared language/summary and Reviewed Recording Input procedure:
-run-step --step artefact --gate TP --evidence <input.json> with this run/revision, TP-derived_from-SD,
+run-step --step artefact --gate TP --evidence <reviewed-TP.md> --reviewer <name> --reviewed true --update-draft <true|false> with this run/revision, TP-derived_from-SD,
 update_draft false initially and true for permitted replacement. Retain reviewed derivation, prior
 proof/history and other protected bytes; never hand-author receipts or bypass the checked writer.
 After recording redispatch gate-check for this same run with `continue_delivery: true`

package/generated/plugins/agdf/runtime/create-agdf/generated/plugins/agdf/meta/contracts/ur-definition.md

@@ -1,15 +1,48 @@
 # AGDF Runtime Contract — UR Definition
 
 This contract guides `ur-definition` only after a non-authorizing, bound
-`skill_continuation` with `phase: ur_definition`. It creates no gate or persistence authority.
+`skill_continuation` with `phase: ur_definition` or `phase: planned_ur_definition`.
+The same owner defines UR content in both modes. It creates no gate or persistence authority.
 
-## Binding and ownership
+## Planning mode before a Run
 
-Use only the returned governance_target, run_id, revision_id, artifact_path and template_path.
+For explicit capture/refinement/priority intent, dispatch this same skill with the confirmed
+target and `planning: {plan_id, expected_digest}`. Use null digest for capture and an inspected
+canonical digest for replacement. Planning is mutually exclusive with Run/revision, delivery
+intake, continue_delivery and source-revision selectors. Do not enter Run assignment to save a
+planned need. The optional planning plugin orchestrates this mode; Core owns its semantics.
+
+Follow `phase: planned_ur_definition` only. Read every returned authoring-inputs page for the
+version-matched UR template, current source and `planning_capability`. Use the same need,
+clarification, preview, language and summary rules below. An incomplete draft remains saveable
+with clarification open. Planning stops at UR and minimal metadata: never author planned PRD,
+SD or TP, present a gate, collect Approval: UR or infer delivery permission.
+
+Use `agdf_record/planned_material.stage` for one UR, then `planned_ur.create` or
+`planned_ur.replace` with that exact planning scope and original mutation UUID. Choose the new
+identity as `plan-<mutation UUID>` without asking the user for an identifier. Creation material
+contains the ordinary UR template without planning scalar fields: Core adds exactly one initial
+`Planning schema: planned-ur-v1`, `Planning id: <plan_id>` and `Planning priority: high|normal|low`.
+Default normal applies only on explicit create. Replacement preserves schema/identity and
+changes priority in that same UR source under its expected digest; no saved parallel title/status.
+No Run-bound material, generic file writer, shell fallback or copied template is permitted.
+
+Return the saved readable title, source reference/digest, priority and remaining clarification.
+Completeness/priority/selection never starts delivery. Only a later explicit request to start from
+the selected current source uses `agdf_run/run.create_from_planned`; read its contract and preserve
+the original UUID after uncertainty. The handoff creates one unapproved Run for normal UR review.
+A different UUID on an already transferred identity returns that Run. Historical planning source
+is read-only afterwards; later product edits use the active Run's existing revision owner.
+Inspect the original operation before retry. Missing/incompatible Core, unsafe/stale source,
+pending recovery or ambiguous origins stop the affected action with concrete diagnosis.
+
+## Run mode binding and ownership
+
+For `phase: ur_definition`, use only the returned governance_target, run_id, revision_id, artifact_path and template_path.
 template_path is the absolute, version-matched template owned by the installed plugin runtime.
 Repository copies under `.agdf/control/templates/` are derived scaffold references and never
 override this authoring source. Read the template without rewriting it; persist only artifact_path.
-A direct invocation first dispatches ur-definition; without a bound run follow the existing
+An already returned bound `ur_definition` continuation satisfies entry: consume its authoring inputs and writer forms directly. Do not repeat author dispatch or intake for that same snapshot. A direct invocation without such a continuation first dispatches ur-definition; without a bound run follow the existing
 resolve_delivery_run assignment, then gate-check intake/resume with its expected_revision_id.
 Never use AGDF_RUN_ID, cwd, discovery or a previous approval as authority. Missing, stale,
 foreign, invalid or approved bindings require fresh control routing; do not write.
@@ -42,7 +75,7 @@ Preserve the requirement and name a concrete recovery or obtain an explicit scop
 cannot be delivered. Record the responsible later UX/PRD step in Next Step; UR authoring still
 writes only its assigned UR, not a preview or product implementation. A requested before-PRD preview
 is created through UX intent clarification under the existing post-UR routing owner. Its durable
-output belongs to `.agdf/control/artefacts/<run_id>/previews/` for the bound run; the UX skill owns
+output belongs to `.agdf/control/runs/<run_id>/evidence/previews/` for the bound run; the UX skill owns
 creation, versioning, evidence and references. An inline chat rendering alone does not fulfill that
 run deliverable. In a new UR, set exactly one initial metadata line before the first section:
 `Preview requirement: before_prd_interactive` for a required interactive before-PRD preview,
@@ -71,7 +104,7 @@ follows its current-request language contract and does not change the artefact l
 
 Before recording a complete draft, when `approval_summary_required` is true, include exactly
 one `## <approval_summary_heading>` section using the supplied heading verbatim. Write a
-complete summary in the resolved presentation language covering problem, goal, affected users,
+complete summary in the resolved presentation language. Read `approval_summary_format.required_fields` from authoring-inputs: those exact list field declarations need concrete authored values; prose or a heading alone is not a named field. Cover problem, goal, affected users,
 scope, non-goals, acceptance signals, source ownership, risks/unknowns and next step.
 Do not truncate decision-relevant content or use ellipses. The existing approval renderer's
 limits and validation apply. This summary is editorial; the UR remains authoritative.
@@ -79,15 +112,20 @@ For new-format URs, a missing or invalid required summary returns to this same a
 route before presentation. Correct it through the existing revision writer; no user approval
 is required merely to complete an unapproved incomplete draft.
 
-## Revision and recording
+## Run mode revision and recording
 
 A new draft is recorded through existing run-step --step ur --title <short title>, using
 --dir <governance_target> --run <run_id> --revision <revision_id>.
-For an already registered unapproved draft, require explicit user revision intent. Resume
-through gate-check with intake true, intake_mode resume, run_id, expected_revision_id and
-ur_action revise (CLI --ur-action revise). Ordinary intake of a ready draft still presents it.
-After editing a registered draft use existing run-update, not run-step: the previous seal
-must be replaced by the canonical revision writer. Never edit an approved UR or its approval.
+When this bound continuation returns a registered, incomplete unapproved draft, correct its
+readiness gaps directly through the supplied `ur_draft.replace` form. The existing authoring
+route already covers completing that same need; do not open another intake or dispatch.
+A deliberate change to an already READY registered draft outside that continuation still
+requires explicit user revision intent: enter via gate-check with intake true, intake_mode
+resume, run_id, expected_revision_id and ur_action revise (CLI --ur-action revise).
+Ordinary intake of a ready draft still presents it. Never substitute a field named revision.
+Stage the replacement and use ur_draft.replace with the current binding. The writer
+publishes the document and typed evidence atomically. Never edit bound bytes, reseal
+an unknown change or alter an approved UR or its approval.
 Use the returned new revision, redispatch gate-check for this target/run, prepare the fresh
 run-present when supplied, show its returned text verbatim and wait for a NEW deliberate
 `Approval: UR`. Previous presentations/replies cannot approve a changed draft.

package/generated/plugins/agdf/runtime/create-agdf/lib/cli/codex-document-command.js

@@ -0,0 +1,195 @@
+// A terminal frontend for Codex JSONL, not a model message or approval recorder.
+import { createHash } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { validateRunPresentationRecord } from '#agdf-core/control-state/run-presentation.js';
+import { resolutionRecordVersion } from '#agdf-core/control-state/input-resolution.js';
+import { resolveControlCommandTarget, canonicalJson } from '#agdf-core/control-state/approval-command-contract.js';
+import { RUN_ID_PATTERN, REVISION_ID_PATTERN, APPROVAL_GATES } from '#agdf-core/control-state/run-identity.js';
+import { pluginDefinition } from '../runtime/control-context.js';
+
+const fail = code => { throw Error(`document_delivery_${code}`); };
+const hash = bytes => 'sha256:' + createHash('sha256').update(bytes).digest('hex');
+const digestPattern = /^[a-f0-9]{64}$/u;
+const LIMITS = Object.freeze({ frame: 4 * 1024 ** 2, stream: 64 * 1024 ** 2, events: 10000, document: 131072 });
+
+export function validateDocumentSelection(options) {
+  if (!isAbsolute(options.dir ?? '') || !RUN_ID_PATTERN.test(options.runId ?? '')
+    || !REVISION_ID_PATTERN.test(options.revisionId ?? '') || !REVISION_ID_PATTERN.test(options.presentationId ?? '')
+    || !APPROVAL_GATES.includes(options.gate)) fail('selection_required');
+  if (options.documentServer !== undefined && (typeof options.documentServer !== 'string'
+    || !/^[A-Za-z0-9_.-]{1,128}$/u.test(options.documentServer))) fail('server_invalid');
+}
+
+function binding(options) {
+  validateDocumentSelection(options);
+  const root = realpathSync(options.dir);
+  const targetId = resolveControlCommandTarget(root).target_id;
+  if (!targetId) fail('target_unavailable');
+  // Canonical envelope reader validates paths, links, identity and record digest.
+  // It does not read the document snapshot. Output bytes must come from MCP.
+  const checked = validateRunPresentationRecord(root, options);
+  if (checked.reason || resolutionRecordVersion(checked.record) !== 7) fail('presentation_unavailable');
+  return { root, targetId, checked };
+}
+
+function domainFor(item) {
+  const result = item.result;
+  if (result?.isError || result?.is_error || item.error || item.status !== 'completed') fail('tool_failed');
+  const snake = result?.structured_content, camel = result?.structuredContent;
+  if (snake && camel && canonicalJson(snake) !== canonicalJson(camel)) fail('conflicting_channels');
+  const domain = snake ?? camel;
+  if (!domain || typeof domain !== 'object') fail('structured_result_required');
+  if (!Array.isArray(result.content) || result.content.length !== 1 || result.content[0]?.type !== 'text') fail('text_result_required');
+  let text;
+  try { text = JSON.parse(result.content[0].text); } catch { fail('text_result_invalid'); }
+  if (canonicalJson(text) !== canonicalJson(domain)) fail('conflicting_channels');
+  return domain;
+}
+
+// Async iterable input supports real stdin and byte-split stream regression tests.
+export async function readCodexDocument(input, options) {
+  const expected = binding(options), server = options.documentServer ?? 'agdf';
+  const record = expected.checked.record, pages = new Map(), activeTools = new Map();
+  const prefix = expected.checked.digest.slice(7) + ':';
+  const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+  let pending = '', streamBytes = 0, events = 0, offset = 0, cursor, duplicates = 0, reads = 0, failedReads = 0;
+  let threadId, started = false, completed = false, runtimeDigest;
+  function event(line) {
+    if (++events > LIMITS.events || Buffer.byteLength(line) > LIMITS.frame) fail('stream_limit');
+    let value;
+    try { value = JSON.parse(line); } catch { fail('json_invalid'); }
+    if (completed) fail('events_after_completion');
+    if (value.type === 'thread.started') {
+      if (threadId || !REVISION_ID_PATTERN.test(value.thread_id ?? '')) fail('thread_invalid');
+      threadId = value.thread_id; return;
+    }
+    if (value.type === 'turn.started') {
+      if (!threadId || started) fail('turn_invalid');
+      started = true; return;
+    }
+    if (!started) fail('turn_missing');
+    if (value.type === 'turn.completed') {
+      if (activeTools.size) fail('unfinished_tool');
+      completed = true; return;
+    }
+    if (['turn.failed', 'error'].includes(value.type)) fail('turn_failed');
+    if (!['item.started', 'item.updated', 'item.completed'].includes(value.type) || !value.item) fail('event_unsupported');
+    const item = value.item;
+    if (['error', 'command_execution', 'file_change', 'web_search'].includes(item.type)) fail('unexpected_action');
+    if (item.type !== 'mcp_tool_call') {
+      if (!['agent_message', 'reasoning', 'todo_list'].includes(item.type)) fail('item_unsupported');
+      return;
+    }
+    if (item.server !== server || item.tool !== 'agdf_inspect') fail('unexpected_tool');
+    if (typeof item.id !== 'string' || !item.id) fail('tool_id_invalid');
+    if (value.type === 'item.started') {
+      if (activeTools.has(item.id)) fail('tool_id_repeated');
+      activeTools.set(item.id, true); return;
+    }
+    if (value.type !== 'item.completed') return;
+    if (!activeTools.delete(item.id)) fail('tool_start_missing');
+    const call = item.arguments;
+    // Other read-only orientation calls cannot supply document bytes.
+    if (call?.operation !== 'presentation-document') return;
+    if (item.status === 'failed') { failedReads++; return; }
+    const domain = domainFor(item), report = domain.report;
+    if (domain.schema_version !== '1' || domain.outcome !== 'inspect_result'
+      || domain.operation !== 'presentation-document' || domain.authorizes !== false
+      || report?.available !== true || report.authorizes !== false) fail('document_result_invalid');
+    const runtime = domain.runtime;
+    if (runtime?.provenance_status !== 'matched' || runtime.expected_version !== pluginDefinition.version
+      || !digestPattern.test(runtime.runtime_digest ?? '')) fail('runtime_unmatched');
+    if (runtimeDigest && runtimeDigest !== runtime.runtime_digest) fail('runtime_changed');
+    runtimeDigest = runtime.runtime_digest;
+    if (!['explicit_target', 'continued_target', 'current_repository'].includes(call.target_source)
+      || call.primary_target !== expected.root || domain.target?.resolution_state !== 'resolved'
+      || domain.target.governance_target !== expected.root || domain.target.primary_target !== expected.root
+      || domain.target.target_source !== call.target_source || domain.target.authorizes !== false) fail('target_mismatch');
+    for (const [field, wanted] of Object.entries({ target_id: expected.targetId, run_id: options.runId,
+      gate: options.gate, presentation_id: options.presentationId })) {
+      if (call[field] !== wanted || report[field] !== wanted) fail('selection_mismatch');
+    }
+    if (call.expected_revision_id !== options.revisionId || report.revision_id !== options.revisionId
+      || report.presentation_digest !== expected.checked.digest || report.content_digest !== record.document_digest
+      || report.total_bytes !== record.document_bytes || report.presentation_language !== record.presentation_language
+      || report.document_language !== record.document_language) fail('binding_mismatch');
+    const start = report.byte_start, end = report.byte_end;
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end <= start
+      || end > record.document_bytes || end > LIMITS.document || typeof report.content !== 'string') fail('range_invalid');
+    const bytes = Buffer.from(report.content, 'utf8');
+    if (bytes.toString('utf8') !== report.content || bytes.length !== end - start) fail('utf8_invalid');
+    if (call.cursor !== (start === 0 ? undefined : prefix + start)
+      || report.complete !== (end === record.document_bytes)
+      || report.next_cursor !== (end === record.document_bytes ? null : prefix + end)) fail('cursor_invalid');
+    reads++;
+    if (pages.has(start)) {
+      const old = pages.get(start);
+      if (old.end !== end || !old.bytes.equals(bytes)) fail('duplicate_conflict');
+      duplicates++; return;
+    }
+    if (start !== offset || call.cursor !== cursor) fail('page_gap');
+    pages.set(start, { end, bytes }); offset = end; cursor = report.next_cursor;
+  }
+  for await (const chunk of input) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    streamBytes += bytes.length;
+    if (streamBytes > LIMITS.stream) fail('stream_limit');
+    pending += decoder.decode(bytes, { stream: true });
+    let newline;
+    while ((newline = pending.indexOf('\n')) >= 0) {
+      const line = pending.slice(0, newline); pending = pending.slice(newline + 1);
+      if (!line.trim()) fail('empty_frame');
+      event(line);
+    }
+    if (Buffer.byteLength(pending) > LIMITS.frame) fail('stream_limit');
+  }
+  pending += decoder.decode();
+  if (pending) event(pending);
+  if (!completed || offset !== record.document_bytes || cursor !== null) fail('incomplete');
+  const document = Buffer.concat([...pages.values()].map(page => page.bytes));
+  if (hash(document) !== record.document_digest) fail('digest_mismatch');
+  const current = binding(options);
+  if (current.root !== expected.root || current.targetId !== expected.targetId
+    || current.checked.digest !== expected.checked.digest) fail('binding_changed');
+  // Never interpret raw terminal controls from a frozen artefact. Reject, do not
+  // sanitize bytes and then pretend the original digest was delivered.
+  if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]|\r(?!\n)/u.test(document.toString('utf8'))) fail('terminal_controls');
+  return { document, receipt: { mode: 'verified_terminal', proof_scope: 'stdout_bytes_written',
+    authorizes: false, thread_id: threadId, target_id: expected.targetId, run_id: options.runId,
+    gate: options.gate, revision_id: options.revisionId, presentation_id: options.presentationId,
+    presentation_digest: expected.checked.digest, content_digest: record.document_digest,
+    bytes: document.length, pages: pages.size, reads, duplicate_reads: duplicates, failed_reads: failedReads,
+    runtime_digest: runtimeDigest, turn_completed: true } };
+}
+
+async function write(stream, data) {
+  await new Promise((resolve, reject) => stream.write(data, error => error ? reject(error) : resolve()));
+}
+
+export function createCodexDocumentRequest(options) {
+  const selected = binding(options), server = options.documentServer ?? 'agdf';
+  const request = { operation: 'presentation-document', presentation_language: selected.checked.record.presentation_language,
+    working_directory: selected.root, target_source: 'explicit_target', primary_target: selected.root,
+    target_id: selected.targetId, run_id: options.runId, gate: options.gate,
+    expected_revision_id: options.revisionId, presentation_id: options.presentationId };
+  return `The verified AGDF render-document terminal frontend is explicitly configured for this request. It receives the original MCP frames and independently validates the selected canonical binding, every page and SHA256 before writing any text. This is a read-only request, never approval. Use only agdf_inspect from server ${JSON.stringify(server)}. Use the literal tool name already supplied in the code when it is available. Do not add ALL_TOOLS discovery or dynamic tools[variable], tools[match.name] or aliases. If the configured server exposes a different name, discover it separately and replace ONLY the literal name; never select a tool dynamically. The strict observer rejects dynamic dispatch. Preserve every selected value, including this historical revision even if a newer revision exists. Execute the complete bounded read loop in one Code Mode cell. Progress is in result.structuredContent.report, not at the structuredContent root. Print only progress metadata, not content or whole tool replies. Never repeat completed pages or infer a cursor.\n\n`
+    + `const selected = ${JSON.stringify(request)};\nlet cursor;\nlet done = false;\nfor (let pageNumber = 0; pageNumber < 64; pageNumber++) {\n`
+    + `  const result = await tools[${JSON.stringify('mcp__' + server + '__agdf_inspect')}](cursor === undefined ? selected : {...selected, cursor});\n`
+    + `  const domain = result.structuredContent;\n  const page = domain?.report;\n`
+    + `  if (domain?.outcome !== "inspect_result" || page?.available !== true) throw new Error("Document read failed");\n`
+    + `  text({byte_end:page.byte_end, complete:page.complete, next_cursor:page.next_cursor});\n`
+    + `  if (page.complete === true) { done = true; break; }\n`
+    + `  if (typeof page.next_cursor !== "string" || page.next_cursor === cursor) throw new Error("Missing or repeated cursor");\n`
+    + `  cursor = page.next_cursor;\n}\nif (!done) throw new Error("Document page limit exceeded");\n\n`
+    + 'After successful completion say only that the pages were retrieved and the host will perform verified output. Do not claim that output or human approval already happened. The renderer receipt proves stdout bytes written only, not human visibility or approval.\n';
+}
+
+export async function renderCodexDocument(options, { input = process.stdin, output = process.stdout, errors = process.stderr } = {}) {
+  if (options.documentRequest) { await write(output, createCodexDocumentRequest(options)); return 0; }
+  if (input.isTTY) fail('jsonl_stdin_required');
+  const { document, receipt } = await readCodexDocument(input, options);
+  await write(output, document);
+  await write(errors, 'AGDF_DOCUMENT_DELIVERY ' + JSON.stringify(receipt) + '\n');
+  return 0;
+}