Make xmd plan produce approved XMD source only #724

Description

@taras

Story

As a command-line user, I want xmd plan to produce one reviewed XMD program
artifact and never execute it, so I can choose explicitly when and where that
program runs.

Common paths

Write the exact approved source to stdout:

xmd plan "Prepare the release program."

Compose planning and execution explicitly through standard input:

xmd plan "Prepare the release program."| xmd run -

Or preserve the artifact first and run the saved file later:

xmd plan "Prepare the release program." --output release.md && xmd run release.md

--output remains an exclusive file sink: it creates the requested path only
after approval and never replaces an existing file. Without it, stdout contains
only the exact approved program bytes.

One command responsibility

xmd plan maps one instruction string to reviewed and approved XMD source. It
uses the same packaged <Plan> workflow as an ordinary document and does not
start a second root after authorship.

The packaged plan-command document remains a thin adapter: it supplies the
command surface to <Plan>, captures the resulting text, and returns those exact
bytes. The host awaits authorship and teardown, performs the existing final
caller-owned checks, and sends the artifact to exactly one destination. No
approved program effect runs on any success or failure path.

Command grammar

Remove --run completely; it has no alias. --run, --run=true,
--run=false, repeated occurrences, and any placement of that spelling receive
one actionable migration refusal before a catalog, Agent, session, review,
output file, journal, or document execution exists:

xmd plan --run was removed because xmd plan only produces approved source.
Run the program explicitly:
xmd plan "..." | xmd run -
xmd plan "..." --output release.md && xmd run release.md

Retain only arguments that configure planning or artifact disposition:

  • the one instruction argument;
  • --include for the syntax catalog;
  • --agent-provider and --default-agent for authorship;
  • --session for the planning conversation;
  • --timeout for the whole planning invocation;
  • --output for the exclusive artifact sink; and
  • ordinary --help and --version behavior.

Remove every option that configured the approved program's former execution:

  • generated root-property arguments: --props, --props-*, and
    --no-props-*;
  • --raw;
  • --verbose and -V;
  • --journal and -j;
  • --timeout-exec and --timeout-fetch;
  • --approve-all, --approve-reads, and --deny-all; and
  • --secret-detection and --no-secret-detection.

Each removed spelling refuses as an xmd plan option before authorship. The
corresponding xmd run options remain unchanged. #676 later introduces the
long-form --verbose and --journal <path> options together with their complete
authorship presentation and diagnostic behavior; this story does not accept
inert placeholders for them.

Update command help to say:

Turn a request into an XMD Plan, review it, and write the approved source.

Help never promises to run the Plan and shows both explicit CLI compositions.

Exact artifact behavior

  • Default stdout and --output receive the same byte-identical source and
    digest supplied by Make <Plan> emit or capture approved XMD source #722.
  • Status, review UI, and planning presentation never contaminate stdout or the
    exclusive output file.
  • Stop, exhaustion, failure, cancellation, or final refusal writes no artifact
    and starts no program.
  • The output file is created exclusively only after approval and teardown.
  • A command continuation or planning session cannot cause the approved program
    to execute implicitly.
  • The command has no later program execution to observe or retain.

Acceptance ownership

This story exclusively owns these Quest cases:

  • CLI Plan: exact approved bytes reach stdout or the exclusive output file;
    a negative-control program effect never occurs.
  • Removed execution option: every --run spelling reports the migration
    above and never aliases or executes.
  • Planning-only grammar: only planning and artifact-disposition options are
    accepted; every former execution option refuses before authorship, and no
    accepted option can cause implicit execution.

The successful stdin pipeline belongs to #723; this story owns the Plan
producer and the diagnostic that points to it. #676 owns and later introduces
the planning-only --verbose and --journal options.

Documentation and focused evidence

Rewrite specs/plan-command-spec.md around the single source-artifact outcome.
Update the command/component inventory and command lifecycle in
architecture.md and specs/executable-mdx-spec.md. In particular, remove the
stale inventory claims that <Plan> requires as, emits no source, or that
xmd plan can execute approved source through --run; #722 made <Plan> an
exact text component whose bare form emits and whose as form captures.

Update CLI help, README, and the homepage delivered by PR #719 so they show the
explicit command-line composition:

Plan produces a program.
Run executes a program from the host/CLI.
Composition decides whether and when a planned program runs.

The homepage includes xmd plan | xmd run -. #713 owns the homepage's
<Plan>-followed-by-<Evaluate> example and complete-program evaluation model;
PR #719 remains historical and unchanged.

The Planner handoff inventories the complete revised xmd plan --help output
and every changed user-facing diagnostic as exact text for product approval.
It reuses the source-only command diagnostics already settled in #676 where
they apply and introduces no unreviewed copy during implementation.

Focused feedback evidence:

deno task test \
packages/cli/tests/plan-cli.test.ts \
packages/cli/tests/plan-command-document.test.ts \
packages/cli/tests/plan-component.test.ts \
packages/cli/tests/syntax-cli.test.ts \
packages/cli/tests/packaged-document.test.ts

The CLI suite covers every retained and removed option class, exact stdout and
exclusive output, all no-artifact failures, and negative-control non-execution.
After a feedback commit, run deno task test --changed. Delivery proves the npm
binary with scripts/tests/cli-npm-bin.test.ts, the compiled command with
scripts/tests/plan-component-compiled.test.ts after deno task build, and the
required CI checks.

Dependencies

Out of scope

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      , 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all
       blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
      }
      } catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
      })();
      (function(){
      try {
      var __m = "github.com";
      var __re = new RegExp('^' + "github\\.com" + '
      
      Skip to content

      Make xmd plan produce approved XMD source only #724

      Description

      @taras

      Story

      As a command-line user, I want xmd plan to produce one reviewed XMD program
      artifact and never execute it, so I can choose explicitly when and where that
      program runs.

      Common paths

      Write the exact approved source to stdout:

      xmd plan "Prepare the release program."

      Compose planning and execution explicitly through standard input:

      xmd plan "Prepare the release program."| xmd run -

      Or preserve the artifact first and run the saved file later:

      xmd plan "Prepare the release program." --output release.md && xmd run release.md

      --output remains an exclusive file sink: it creates the requested path only
      after approval and never replaces an existing file. Without it, stdout contains
      only the exact approved program bytes.

      One command responsibility

      xmd plan maps one instruction string to reviewed and approved XMD source. It
      uses the same packaged <Plan> workflow as an ordinary document and does not
      start a second root after authorship.

      The packaged plan-command document remains a thin adapter: it supplies the
      command surface to <Plan>, captures the resulting text, and returns those exact
      bytes. The host awaits authorship and teardown, performs the existing final
      caller-owned checks, and sends the artifact to exactly one destination. No
      approved program effect runs on any success or failure path.

      Command grammar

      Remove --run completely; it has no alias. --run, --run=true,
      --run=false, repeated occurrences, and any placement of that spelling receive
      one actionable migration refusal before a catalog, Agent, session, review,
      output file, journal, or document execution exists:

      xmd plan --run was removed because xmd plan only produces approved source.
      Run the program explicitly:
      xmd plan "..." | xmd run -
      xmd plan "..." --output release.md && xmd run release.md
      

      Retain only arguments that configure planning or artifact disposition:

      • the one instruction argument;
      • --include for the syntax catalog;
      • --agent-provider and --default-agent for authorship;
      • --session for the planning conversation;
      • --timeout for the whole planning invocation;
      • --output for the exclusive artifact sink; and
      • ordinary --help and --version behavior.

      Remove every option that configured the approved program's former execution:

      • generated root-property arguments: --props, --props-*, and
        --no-props-*;
      • --raw;
      • --verbose and -V;
      • --journal and -j;
      • --timeout-exec and --timeout-fetch;
      • --approve-all, --approve-reads, and --deny-all; and
      • --secret-detection and --no-secret-detection.

      Each removed spelling refuses as an xmd plan option before authorship. The
      corresponding xmd run options remain unchanged. #676 later introduces the
      long-form --verbose and --journal <path> options together with their complete
      authorship presentation and diagnostic behavior; this story does not accept
      inert placeholders for them.

      Update command help to say:

      Turn a request into an XMD Plan, review it, and write the approved source.
      

      Help never promises to run the Plan and shows both explicit CLI compositions.

      Exact artifact behavior

      • Default stdout and --output receive the same byte-identical source and
        digest supplied by Make <Plan> emit or capture approved XMD source #722.
      • Status, review UI, and planning presentation never contaminate stdout or the
        exclusive output file.
      • Stop, exhaustion, failure, cancellation, or final refusal writes no artifact
        and starts no program.
      • The output file is created exclusively only after approval and teardown.
      • A command continuation or planning session cannot cause the approved program
        to execute implicitly.
      • The command has no later program execution to observe or retain.

      Acceptance ownership

      This story exclusively owns these Quest cases:

      • CLI Plan: exact approved bytes reach stdout or the exclusive output file;
        a negative-control program effect never occurs.
      • Removed execution option: every --run spelling reports the migration
        above and never aliases or executes.
      • Planning-only grammar: only planning and artifact-disposition options are
        accepted; every former execution option refuses before authorship, and no
        accepted option can cause implicit execution.

      The successful stdin pipeline belongs to #723; this story owns the Plan
      producer and the diagnostic that points to it. #676 owns and later introduces
      the planning-only --verbose and --journal options.

      Documentation and focused evidence

      Rewrite specs/plan-command-spec.md around the single source-artifact outcome.
      Update the command/component inventory and command lifecycle in
      architecture.md and specs/executable-mdx-spec.md. In particular, remove the
      stale inventory claims that <Plan> requires as, emits no source, or that
      xmd plan can execute approved source through --run; #722 made <Plan> an
      exact text component whose bare form emits and whose as form captures.

      Update CLI help, README, and the homepage delivered by PR #719 so they show the
      explicit command-line composition:

      Plan produces a program.
      Run executes a program from the host/CLI.
      Composition decides whether and when a planned program runs.
      

      The homepage includes xmd plan | xmd run -. #713 owns the homepage's
      <Plan>-followed-by-<Evaluate> example and complete-program evaluation model;
      PR #719 remains historical and unchanged.

      The Planner handoff inventories the complete revised xmd plan --help output
      and every changed user-facing diagnostic as exact text for product approval.
      It reuses the source-only command diagnostics already settled in #676 where
      they apply and introduces no unreviewed copy during implementation.

      Focused feedback evidence:

      deno task test \
      packages/cli/tests/plan-cli.test.ts \
      packages/cli/tests/plan-command-document.test.ts \
      packages/cli/tests/plan-component.test.ts \
      packages/cli/tests/syntax-cli.test.ts \
      packages/cli/tests/packaged-document.test.ts

      The CLI suite covers every retained and removed option class, exact stdout and
      exclusive output, all no-artifact failures, and negative-control non-execution.
      After a feedback commit, run deno task test --changed. Delivery proves the npm
      binary with scripts/tests/cli-npm-bin.test.ts, the compiled command with
      scripts/tests/plan-component-compiled.test.ts after deno task build, and the
      required CI checks.

      Dependencies

      Out of scope

      Activity

      Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

      Metadata

      Metadata

      Assignees

      No one assigned

        Labels

        enhancementNew feature or request

        Projects

        No projects

          Milestone

          No milestone

          Relationships

          None yet

          Development

          No branches or pull requests

          Issue actions

          , 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix"); } } catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
          Skip to content

          Make xmd plan produce approved XMD source only #724

          Description

          @taras

          Story

          As a command-line user, I want xmd plan to produce one reviewed XMD program
          artifact and never execute it, so I can choose explicitly when and where that
          program runs.

          Common paths

          Write the exact approved source to stdout:

          xmd plan "Prepare the release program."

          Compose planning and execution explicitly through standard input:

          xmd plan "Prepare the release program."| xmd run -

          Or preserve the artifact first and run the saved file later:

          xmd plan "Prepare the release program." --output release.md && xmd run release.md

          --output remains an exclusive file sink: it creates the requested path only
          after approval and never replaces an existing file. Without it, stdout contains
          only the exact approved program bytes.

          One command responsibility

          xmd plan maps one instruction string to reviewed and approved XMD source. It
          uses the same packaged <Plan> workflow as an ordinary document and does not
          start a second root after authorship.

          The packaged plan-command document remains a thin adapter: it supplies the
          command surface to <Plan>, captures the resulting text, and returns those exact
          bytes. The host awaits authorship and teardown, performs the existing final
          caller-owned checks, and sends the artifact to exactly one destination. No
          approved program effect runs on any success or failure path.

          Command grammar

          Remove --run completely; it has no alias. --run, --run=true,
          --run=false, repeated occurrences, and any placement of that spelling receive
          one actionable migration refusal before a catalog, Agent, session, review,
          output file, journal, or document execution exists:

          xmd plan --run was removed because xmd plan only produces approved source.
          Run the program explicitly:
          xmd plan "..." | xmd run -
          xmd plan "..." --output release.md && xmd run release.md
          

          Retain only arguments that configure planning or artifact disposition:

          • the one instruction argument;
          • --include for the syntax catalog;
          • --agent-provider and --default-agent for authorship;
          • --session for the planning conversation;
          • --timeout for the whole planning invocation;
          • --output for the exclusive artifact sink; and
          • ordinary --help and --version behavior.

          Remove every option that configured the approved program's former execution:

          • generated root-property arguments: --props, --props-*, and
            --no-props-*;
          • --raw;
          • --verbose and -V;
          • --journal and -j;
          • --timeout-exec and --timeout-fetch;
          • --approve-all, --approve-reads, and --deny-all; and
          • --secret-detection and --no-secret-detection.

          Each removed spelling refuses as an xmd plan option before authorship. The
          corresponding xmd run options remain unchanged. #676 later introduces the
          long-form --verbose and --journal <path> options together with their complete
          authorship presentation and diagnostic behavior; this story does not accept
          inert placeholders for them.

          Update command help to say:

          Turn a request into an XMD Plan, review it, and write the approved source.
          

          Help never promises to run the Plan and shows both explicit CLI compositions.

          Exact artifact behavior

          • Default stdout and --output receive the same byte-identical source and
            digest supplied by Make <Plan> emit or capture approved XMD source #722.
          • Status, review UI, and planning presentation never contaminate stdout or the
            exclusive output file.
          • Stop, exhaustion, failure, cancellation, or final refusal writes no artifact
            and starts no program.
          • The output file is created exclusively only after approval and teardown.
          • A command continuation or planning session cannot cause the approved program
            to execute implicitly.
          • The command has no later program execution to observe or retain.

          Acceptance ownership

          This story exclusively owns these Quest cases:

          • CLI Plan: exact approved bytes reach stdout or the exclusive output file;
            a negative-control program effect never occurs.
          • Removed execution option: every --run spelling reports the migration
            above and never aliases or executes.
          • Planning-only grammar: only planning and artifact-disposition options are
            accepted; every former execution option refuses before authorship, and no
            accepted option can cause implicit execution.

          The successful stdin pipeline belongs to #723; this story owns the Plan
          producer and the diagnostic that points to it. #676 owns and later introduces
          the planning-only --verbose and --journal options.

          Documentation and focused evidence

          Rewrite specs/plan-command-spec.md around the single source-artifact outcome.
          Update the command/component inventory and command lifecycle in
          architecture.md and specs/executable-mdx-spec.md. In particular, remove the
          stale inventory claims that <Plan> requires as, emits no source, or that
          xmd plan can execute approved source through --run; #722 made <Plan> an
          exact text component whose bare form emits and whose as form captures.

          Update CLI help, README, and the homepage delivered by PR #719 so they show the
          explicit command-line composition:

          Plan produces a program.
          Run executes a program from the host/CLI.
          Composition decides whether and when a planned program runs.
          

          The homepage includes xmd plan | xmd run -. #713 owns the homepage's
          <Plan>-followed-by-<Evaluate> example and complete-program evaluation model;
          PR #719 remains historical and unchanged.

          The Planner handoff inventories the complete revised xmd plan --help output
          and every changed user-facing diagnostic as exact text for product approval.
          It reuses the source-only command diagnostics already settled in #676 where
          they apply and introduces no unreviewed copy during implementation.

          Focused feedback evidence:

          deno task test \
          packages/cli/tests/plan-cli.test.ts \
          packages/cli/tests/plan-command-document.test.ts \
          packages/cli/tests/plan-component.test.ts \
          packages/cli/tests/syntax-cli.test.ts \
          packages/cli/tests/packaged-document.test.ts

          The CLI suite covers every retained and removed option class, exact stdout and
          exclusive output, all no-artifact failures, and negative-control non-execution.
          After a feedback commit, run deno task test --changed. Delivery proves the npm
          binary with scripts/tests/cli-npm-bin.test.ts, the compiled command with
          scripts/tests/plan-component-compiled.test.ts after deno task build, and the
          required CI checks.

          Dependencies

          Out of scope

          Activity

          Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

          Metadata

          Metadata

          Assignees

          No one assigned

            Labels

            enhancementNew feature or request

            Projects

            No projects

              Milestone

              No milestone

              Relationships

              None yet

              Development

              No branches or pull requests

              Issue actions

              , 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms"); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
              Skip to content

              Make xmd plan produce approved XMD source only #724

              Description

              @taras

              Story

              As a command-line user, I want xmd plan to produce one reviewed XMD program
              artifact and never execute it, so I can choose explicitly when and where that
              program runs.

              Common paths

              Write the exact approved source to stdout:

              xmd plan "Prepare the release program."

              Compose planning and execution explicitly through standard input:

              xmd plan "Prepare the release program."| xmd run -

              Or preserve the artifact first and run the saved file later:

              xmd plan "Prepare the release program." --output release.md && xmd run release.md

              --output remains an exclusive file sink: it creates the requested path only
              after approval and never replaces an existing file. Without it, stdout contains
              only the exact approved program bytes.

              One command responsibility

              xmd plan maps one instruction string to reviewed and approved XMD source. It
              uses the same packaged <Plan> workflow as an ordinary document and does not
              start a second root after authorship.

              The packaged plan-command document remains a thin adapter: it supplies the
              command surface to <Plan>, captures the resulting text, and returns those exact
              bytes. The host awaits authorship and teardown, performs the existing final
              caller-owned checks, and sends the artifact to exactly one destination. No
              approved program effect runs on any success or failure path.

              Command grammar

              Remove --run completely; it has no alias. --run, --run=true,
              --run=false, repeated occurrences, and any placement of that spelling receive
              one actionable migration refusal before a catalog, Agent, session, review,
              output file, journal, or document execution exists:

              xmd plan --run was removed because xmd plan only produces approved source.
              Run the program explicitly:
              xmd plan "..." | xmd run -
              xmd plan "..." --output release.md && xmd run release.md
              

              Retain only arguments that configure planning or artifact disposition:

              • the one instruction argument;
              • --include for the syntax catalog;
              • --agent-provider and --default-agent for authorship;
              • --session for the planning conversation;
              • --timeout for the whole planning invocation;
              • --output for the exclusive artifact sink; and
              • ordinary --help and --version behavior.

              Remove every option that configured the approved program's former execution:

              • generated root-property arguments: --props, --props-*, and
                --no-props-*;
              • --raw;
              • --verbose and -V;
              • --journal and -j;
              • --timeout-exec and --timeout-fetch;
              • --approve-all, --approve-reads, and --deny-all; and
              • --secret-detection and --no-secret-detection.

              Each removed spelling refuses as an xmd plan option before authorship. The
              corresponding xmd run options remain unchanged. #676 later introduces the
              long-form --verbose and --journal <path> options together with their complete
              authorship presentation and diagnostic behavior; this story does not accept
              inert placeholders for them.

              Update command help to say:

              Turn a request into an XMD Plan, review it, and write the approved source.
              

              Help never promises to run the Plan and shows both explicit CLI compositions.

              Exact artifact behavior

              • Default stdout and --output receive the same byte-identical source and
                digest supplied by Make <Plan> emit or capture approved XMD source #722.
              • Status, review UI, and planning presentation never contaminate stdout or the
                exclusive output file.
              • Stop, exhaustion, failure, cancellation, or final refusal writes no artifact
                and starts no program.
              • The output file is created exclusively only after approval and teardown.
              • A command continuation or planning session cannot cause the approved program
                to execute implicitly.
              • The command has no later program execution to observe or retain.

              Acceptance ownership

              This story exclusively owns these Quest cases:

              • CLI Plan: exact approved bytes reach stdout or the exclusive output file;
                a negative-control program effect never occurs.
              • Removed execution option: every --run spelling reports the migration
                above and never aliases or executes.
              • Planning-only grammar: only planning and artifact-disposition options are
                accepted; every former execution option refuses before authorship, and no
                accepted option can cause implicit execution.

              The successful stdin pipeline belongs to #723; this story owns the Plan
              producer and the diagnostic that points to it. #676 owns and later introduces
              the planning-only --verbose and --journal options.

              Documentation and focused evidence

              Rewrite specs/plan-command-spec.md around the single source-artifact outcome.
              Update the command/component inventory and command lifecycle in
              architecture.md and specs/executable-mdx-spec.md. In particular, remove the
              stale inventory claims that <Plan> requires as, emits no source, or that
              xmd plan can execute approved source through --run; #722 made <Plan> an
              exact text component whose bare form emits and whose as form captures.

              Update CLI help, README, and the homepage delivered by PR #719 so they show the
              explicit command-line composition:

              Plan produces a program.
              Run executes a program from the host/CLI.
              Composition decides whether and when a planned program runs.
              

              The homepage includes xmd plan | xmd run -. #713 owns the homepage's
              <Plan>-followed-by-<Evaluate> example and complete-program evaluation model;
              PR #719 remains historical and unchanged.

              The Planner handoff inventories the complete revised xmd plan --help output
              and every changed user-facing diagnostic as exact text for product approval.
              It reuses the source-only command diagnostics already settled in #676 where
              they apply and introduces no unreviewed copy during implementation.

              Focused feedback evidence:

              deno task test \
              packages/cli/tests/plan-cli.test.ts \
              packages/cli/tests/plan-command-document.test.ts \
              packages/cli/tests/plan-component.test.ts \
              packages/cli/tests/syntax-cli.test.ts \
              packages/cli/tests/packaged-document.test.ts

              The CLI suite covers every retained and removed option class, exact stdout and
              exclusive output, all no-artifact failures, and negative-control non-execution.
              After a feedback commit, run deno task test --changed. Delivery proves the npm
              binary with scripts/tests/cli-npm-bin.test.ts, the compiled command with
              scripts/tests/plan-component-compiled.test.ts after deno task build, and the
              required CI checks.

              Dependencies

              Out of scope

              Activity

              Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

              Metadata

              Metadata

              Assignees

              No one assigned

                Labels

                enhancementNew feature or request

                Projects

                No projects

                  Milestone

                  No milestone

                  Relationships

                  None yet

                  Development

                  No branches or pull requests

                  Issue actions

                  , 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links"); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + '
                  Skip to content

                  Make xmd plan produce approved XMD source only #724

                  Description

                  @taras

                  Story

                  As a command-line user, I want xmd plan to produce one reviewed XMD program
                  artifact and never execute it, so I can choose explicitly when and where that
                  program runs.

                  Common paths

                  Write the exact approved source to stdout:

                  xmd plan "Prepare the release program."

                  Compose planning and execution explicitly through standard input:

                  xmd plan "Prepare the release program."| xmd run -

                  Or preserve the artifact first and run the saved file later:

                  xmd plan "Prepare the release program." --output release.md && xmd run release.md

                  --output remains an exclusive file sink: it creates the requested path only
                  after approval and never replaces an existing file. Without it, stdout contains
                  only the exact approved program bytes.

                  One command responsibility

                  xmd plan maps one instruction string to reviewed and approved XMD source. It
                  uses the same packaged <Plan> workflow as an ordinary document and does not
                  start a second root after authorship.

                  The packaged plan-command document remains a thin adapter: it supplies the
                  command surface to <Plan>, captures the resulting text, and returns those exact
                  bytes. The host awaits authorship and teardown, performs the existing final
                  caller-owned checks, and sends the artifact to exactly one destination. No
                  approved program effect runs on any success or failure path.

                  Command grammar

                  Remove --run completely; it has no alias. --run, --run=true,
                  --run=false, repeated occurrences, and any placement of that spelling receive
                  one actionable migration refusal before a catalog, Agent, session, review,
                  output file, journal, or document execution exists:

                  xmd plan --run was removed because xmd plan only produces approved source.
                  Run the program explicitly:
                  xmd plan "..." | xmd run -
                  xmd plan "..." --output release.md && xmd run release.md
                  

                  Retain only arguments that configure planning or artifact disposition:

                  • the one instruction argument;
                  • --include for the syntax catalog;
                  • --agent-provider and --default-agent for authorship;
                  • --session for the planning conversation;
                  • --timeout for the whole planning invocation;
                  • --output for the exclusive artifact sink; and
                  • ordinary --help and --version behavior.

                  Remove every option that configured the approved program's former execution:

                  • generated root-property arguments: --props, --props-*, and
                    --no-props-*;
                  • --raw;
                  • --verbose and -V;
                  • --journal and -j;
                  • --timeout-exec and --timeout-fetch;
                  • --approve-all, --approve-reads, and --deny-all; and
                  • --secret-detection and --no-secret-detection.

                  Each removed spelling refuses as an xmd plan option before authorship. The
                  corresponding xmd run options remain unchanged. #676 later introduces the
                  long-form --verbose and --journal <path> options together with their complete
                  authorship presentation and diagnostic behavior; this story does not accept
                  inert placeholders for them.

                  Update command help to say:

                  Turn a request into an XMD Plan, review it, and write the approved source.
                  

                  Help never promises to run the Plan and shows both explicit CLI compositions.

                  Exact artifact behavior

                  • Default stdout and --output receive the same byte-identical source and
                    digest supplied by Make <Plan> emit or capture approved XMD source #722.
                  • Status, review UI, and planning presentation never contaminate stdout or the
                    exclusive output file.
                  • Stop, exhaustion, failure, cancellation, or final refusal writes no artifact
                    and starts no program.
                  • The output file is created exclusively only after approval and teardown.
                  • A command continuation or planning session cannot cause the approved program
                    to execute implicitly.
                  • The command has no later program execution to observe or retain.

                  Acceptance ownership

                  This story exclusively owns these Quest cases:

                  • CLI Plan: exact approved bytes reach stdout or the exclusive output file;
                    a negative-control program effect never occurs.
                  • Removed execution option: every --run spelling reports the migration
                    above and never aliases or executes.
                  • Planning-only grammar: only planning and artifact-disposition options are
                    accepted; every former execution option refuses before authorship, and no
                    accepted option can cause implicit execution.

                  The successful stdin pipeline belongs to #723; this story owns the Plan
                  producer and the diagnostic that points to it. #676 owns and later introduces
                  the planning-only --verbose and --journal options.

                  Documentation and focused evidence

                  Rewrite specs/plan-command-spec.md around the single source-artifact outcome.
                  Update the command/component inventory and command lifecycle in
                  architecture.md and specs/executable-mdx-spec.md. In particular, remove the
                  stale inventory claims that <Plan> requires as, emits no source, or that
                  xmd plan can execute approved source through --run; #722 made <Plan> an
                  exact text component whose bare form emits and whose as form captures.

                  Update CLI help, README, and the homepage delivered by PR #719 so they show the
                  explicit command-line composition:

                  Plan produces a program.
                  Run executes a program from the host/CLI.
                  Composition decides whether and when a planned program runs.
                  

                  The homepage includes xmd plan | xmd run -. #713 owns the homepage's
                  <Plan>-followed-by-<Evaluate> example and complete-program evaluation model;
                  PR #719 remains historical and unchanged.

                  The Planner handoff inventories the complete revised xmd plan --help output
                  and every changed user-facing diagnostic as exact text for product approval.
                  It reuses the source-only command diagnostics already settled in #676 where
                  they apply and introduces no unreviewed copy during implementation.

                  Focused feedback evidence:

                  deno task test \
                  packages/cli/tests/plan-cli.test.ts \
                  packages/cli/tests/plan-command-document.test.ts \
                  packages/cli/tests/plan-component.test.ts \
                  packages/cli/tests/syntax-cli.test.ts \
                  packages/cli/tests/packaged-document.test.ts

                  The CLI suite covers every retained and removed option class, exact stdout and
                  exclusive output, all no-artifact failures, and negative-control non-execution.
                  After a feedback commit, run deno task test --changed. Delivery proves the npm
                  binary with scripts/tests/cli-npm-bin.test.ts, the compiled command with
                  scripts/tests/plan-component-compiled.test.ts after deno task build, and the
                  required CI checks.

                  Dependencies

                  Out of scope

                  Activity

                  Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

                  Metadata

                  Metadata

                  Assignees

                  No one assigned

                    Labels

                    enhancementNew feature or request

                    Projects

                    No projects

                      Milestone

                      No milestone

                      Relationships

                      None yet

                      Development

                      No branches or pull requests

                      Issue actions

                      , 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default"); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
                      Skip to content

                      Make xmd plan produce approved XMD source only #724

                      Description

                      @taras

                      Story

                      As a command-line user, I want xmd plan to produce one reviewed XMD program
                      artifact and never execute it, so I can choose explicitly when and where that
                      program runs.

                      Common paths

                      Write the exact approved source to stdout:

                      xmd plan "Prepare the release program."

                      Compose planning and execution explicitly through standard input:

                      xmd plan "Prepare the release program."| xmd run -

                      Or preserve the artifact first and run the saved file later:

                      xmd plan "Prepare the release program." --output release.md && xmd run release.md

                      --output remains an exclusive file sink: it creates the requested path only
                      after approval and never replaces an existing file. Without it, stdout contains
                      only the exact approved program bytes.

                      One command responsibility

                      xmd plan maps one instruction string to reviewed and approved XMD source. It
                      uses the same packaged <Plan> workflow as an ordinary document and does not
                      start a second root after authorship.

                      The packaged plan-command document remains a thin adapter: it supplies the
                      command surface to <Plan>, captures the resulting text, and returns those exact
                      bytes. The host awaits authorship and teardown, performs the existing final
                      caller-owned checks, and sends the artifact to exactly one destination. No
                      approved program effect runs on any success or failure path.

                      Command grammar

                      Remove --run completely; it has no alias. --run, --run=true,
                      --run=false, repeated occurrences, and any placement of that spelling receive
                      one actionable migration refusal before a catalog, Agent, session, review,
                      output file, journal, or document execution exists:

                      xmd plan --run was removed because xmd plan only produces approved source.
                      Run the program explicitly:
                      xmd plan "..." | xmd run -
                      xmd plan "..." --output release.md && xmd run release.md
                      

                      Retain only arguments that configure planning or artifact disposition:

                      • the one instruction argument;
                      • --include for the syntax catalog;
                      • --agent-provider and --default-agent for authorship;
                      • --session for the planning conversation;
                      • --timeout for the whole planning invocation;
                      • --output for the exclusive artifact sink; and
                      • ordinary --help and --version behavior.

                      Remove every option that configured the approved program's former execution:

                      • generated root-property arguments: --props, --props-*, and
                        --no-props-*;
                      • --raw;
                      • --verbose and -V;
                      • --journal and -j;
                      • --timeout-exec and --timeout-fetch;
                      • --approve-all, --approve-reads, and --deny-all; and
                      • --secret-detection and --no-secret-detection.

                      Each removed spelling refuses as an xmd plan option before authorship. The
                      corresponding xmd run options remain unchanged. #676 later introduces the
                      long-form --verbose and --journal <path> options together with their complete
                      authorship presentation and diagnostic behavior; this story does not accept
                      inert placeholders for them.

                      Update command help to say:

                      Turn a request into an XMD Plan, review it, and write the approved source.
                      

                      Help never promises to run the Plan and shows both explicit CLI compositions.

                      Exact artifact behavior

                      • Default stdout and --output receive the same byte-identical source and
                        digest supplied by Make <Plan> emit or capture approved XMD source #722.
                      • Status, review UI, and planning presentation never contaminate stdout or the
                        exclusive output file.
                      • Stop, exhaustion, failure, cancellation, or final refusal writes no artifact
                        and starts no program.
                      • The output file is created exclusively only after approval and teardown.
                      • A command continuation or planning session cannot cause the approved program
                        to execute implicitly.
                      • The command has no later program execution to observe or retain.

                      Acceptance ownership

                      This story exclusively owns these Quest cases:

                      • CLI Plan: exact approved bytes reach stdout or the exclusive output file;
                        a negative-control program effect never occurs.
                      • Removed execution option: every --run spelling reports the migration
                        above and never aliases or executes.
                      • Planning-only grammar: only planning and artifact-disposition options are
                        accepted; every former execution option refuses before authorship, and no
                        accepted option can cause implicit execution.

                      The successful stdin pipeline belongs to #723; this story owns the Plan
                      producer and the diagnostic that points to it. #676 owns and later introduces
                      the planning-only --verbose and --journal options.

                      Documentation and focused evidence

                      Rewrite specs/plan-command-spec.md around the single source-artifact outcome.
                      Update the command/component inventory and command lifecycle in
                      architecture.md and specs/executable-mdx-spec.md. In particular, remove the
                      stale inventory claims that <Plan> requires as, emits no source, or that
                      xmd plan can execute approved source through --run; #722 made <Plan> an
                      exact text component whose bare form emits and whose as form captures.

                      Update CLI help, README, and the homepage delivered by PR #719 so they show the
                      explicit command-line composition:

                      Plan produces a program.
                      Run executes a program from the host/CLI.
                      Composition decides whether and when a planned program runs.
                      

                      The homepage includes xmd plan | xmd run -. #713 owns the homepage's
                      <Plan>-followed-by-<Evaluate> example and complete-program evaluation model;
                      PR #719 remains historical and unchanged.

                      The Planner handoff inventories the complete revised xmd plan --help output
                      and every changed user-facing diagnostic as exact text for product approval.
                      It reuses the source-only command diagnostics already settled in #676 where
                      they apply and introduces no unreviewed copy during implementation.

                      Focused feedback evidence:

                      deno task test \
                      packages/cli/tests/plan-cli.test.ts \
                      packages/cli/tests/plan-command-document.test.ts \
                      packages/cli/tests/plan-component.test.ts \
                      packages/cli/tests/syntax-cli.test.ts \
                      packages/cli/tests/packaged-document.test.ts

                      The CLI suite covers every retained and removed option class, exact stdout and
                      exclusive output, all no-artifact failures, and negative-control non-execution.
                      After a feedback commit, run deno task test --changed. Delivery proves the npm
                      binary with scripts/tests/cli-npm-bin.test.ts, the compiled command with
                      scripts/tests/plan-component-compiled.test.ts after deno task build, and the
                      required CI checks.

                      Dependencies

                      Out of scope

                      Activity

                      Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

                      Metadata

                      Metadata

                      Assignees

                      No one assigned

                        Labels

                        enhancementNew feature or request

                        Projects

                        No projects

                          Milestone

                          No milestone

                          Relationships

                          None yet

                          Development

                          No branches or pull requests

                          Issue actions

                          , 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers"); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
                          Skip to content

                          Make xmd plan produce approved XMD source only #724

                          Description

                          @taras

                          Story

                          As a command-line user, I want xmd plan to produce one reviewed XMD program
                          artifact and never execute it, so I can choose explicitly when and where that
                          program runs.

                          Common paths

                          Write the exact approved source to stdout:

                          xmd plan "Prepare the release program."

                          Compose planning and execution explicitly through standard input:

                          xmd plan "Prepare the release program."| xmd run -

                          Or preserve the artifact first and run the saved file later:

                          xmd plan "Prepare the release program." --output release.md && xmd run release.md

                          --output remains an exclusive file sink: it creates the requested path only
                          after approval and never replaces an existing file. Without it, stdout contains
                          only the exact approved program bytes.

                          One command responsibility

                          xmd plan maps one instruction string to reviewed and approved XMD source. It
                          uses the same packaged <Plan> workflow as an ordinary document and does not
                          start a second root after authorship.

                          The packaged plan-command document remains a thin adapter: it supplies the
                          command surface to <Plan>, captures the resulting text, and returns those exact
                          bytes. The host awaits authorship and teardown, performs the existing final
                          caller-owned checks, and sends the artifact to exactly one destination. No
                          approved program effect runs on any success or failure path.

                          Command grammar

                          Remove --run completely; it has no alias. --run, --run=true,
                          --run=false, repeated occurrences, and any placement of that spelling receive
                          one actionable migration refusal before a catalog, Agent, session, review,
                          output file, journal, or document execution exists:

                          xmd plan --run was removed because xmd plan only produces approved source.
                          Run the program explicitly:
                          xmd plan "..." | xmd run -
                          xmd plan "..." --output release.md && xmd run release.md
                          

                          Retain only arguments that configure planning or artifact disposition:

                          • the one instruction argument;
                          • --include for the syntax catalog;
                          • --agent-provider and --default-agent for authorship;
                          • --session for the planning conversation;
                          • --timeout for the whole planning invocation;
                          • --output for the exclusive artifact sink; and
                          • ordinary --help and --version behavior.

                          Remove every option that configured the approved program's former execution:

                          • generated root-property arguments: --props, --props-*, and
                            --no-props-*;
                          • --raw;
                          • --verbose and -V;
                          • --journal and -j;
                          • --timeout-exec and --timeout-fetch;
                          • --approve-all, --approve-reads, and --deny-all; and
                          • --secret-detection and --no-secret-detection.

                          Each removed spelling refuses as an xmd plan option before authorship. The
                          corresponding xmd run options remain unchanged. #676 later introduces the
                          long-form --verbose and --journal <path> options together with their complete
                          authorship presentation and diagnostic behavior; this story does not accept
                          inert placeholders for them.

                          Update command help to say:

                          Turn a request into an XMD Plan, review it, and write the approved source.
                          

                          Help never promises to run the Plan and shows both explicit CLI compositions.

                          Exact artifact behavior

                          • Default stdout and --output receive the same byte-identical source and
                            digest supplied by Make <Plan> emit or capture approved XMD source #722.
                          • Status, review UI, and planning presentation never contaminate stdout or the
                            exclusive output file.
                          • Stop, exhaustion, failure, cancellation, or final refusal writes no artifact
                            and starts no program.
                          • The output file is created exclusively only after approval and teardown.
                          • A command continuation or planning session cannot cause the approved program
                            to execute implicitly.
                          • The command has no later program execution to observe or retain.

                          Acceptance ownership

                          This story exclusively owns these Quest cases:

                          • CLI Plan: exact approved bytes reach stdout or the exclusive output file;
                            a negative-control program effect never occurs.
                          • Removed execution option: every --run spelling reports the migration
                            above and never aliases or executes.
                          • Planning-only grammar: only planning and artifact-disposition options are
                            accepted; every former execution option refuses before authorship, and no
                            accepted option can cause implicit execution.

                          The successful stdin pipeline belongs to #723; this story owns the Plan
                          producer and the diagnostic that points to it. #676 owns and later introduces
                          the planning-only --verbose and --journal options.

                          Documentation and focused evidence

                          Rewrite specs/plan-command-spec.md around the single source-artifact outcome.
                          Update the command/component inventory and command lifecycle in
                          architecture.md and specs/executable-mdx-spec.md. In particular, remove the
                          stale inventory claims that <Plan> requires as, emits no source, or that
                          xmd plan can execute approved source through --run; #722 made <Plan> an
                          exact text component whose bare form emits and whose as form captures.

                          Update CLI help, README, and the homepage delivered by PR #719 so they show the
                          explicit command-line composition:

                          Plan produces a program.
                          Run executes a program from the host/CLI.
                          Composition decides whether and when a planned program runs.
                          

                          The homepage includes xmd plan | xmd run -. #713 owns the homepage's
                          <Plan>-followed-by-<Evaluate> example and complete-program evaluation model;
                          PR #719 remains historical and unchanged.

                          The Planner handoff inventories the complete revised xmd plan --help output
                          and every changed user-facing diagnostic as exact text for product approval.
                          It reuses the source-only command diagnostics already settled in #676 where
                          they apply and introduces no unreviewed copy during implementation.

                          Focused feedback evidence:

                          deno task test \
                          packages/cli/tests/plan-cli.test.ts \
                          packages/cli/tests/plan-command-document.test.ts \
                          packages/cli/tests/plan-component.test.ts \
                          packages/cli/tests/syntax-cli.test.ts \
                          packages/cli/tests/packaged-document.test.ts

                          The CLI suite covers every retained and removed option class, exact stdout and
                          exclusive output, all no-artifact failures, and negative-control non-execution.
                          After a feedback commit, run deno task test --changed. Delivery proves the npm
                          binary with scripts/tests/cli-npm-bin.test.ts, the compiled command with
                          scripts/tests/plan-component-compiled.test.ts after deno task build, and the
                          required CI checks.

                          Dependencies

                          Out of scope

                          Activity

                          Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

                          Metadata

                          Metadata

                          Assignees

                          No one assigned

                            Labels

                            enhancementNew feature or request

                            Projects

                            No projects

                              Milestone

                              No milestone

                              Relationships

                              None yet

                              Development

                              No branches or pull requests

                              Issue actions

                              , 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode"); } } catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); } })(); })();
                              Skip to content

                              Make xmd plan produce approved XMD source only #724

                              Description

                              @taras

                              Story

                              As a command-line user, I want xmd plan to produce one reviewed XMD program
                              artifact and never execute it, so I can choose explicitly when and where that
                              program runs.

                              Common paths

                              Write the exact approved source to stdout:

                              xmd plan "Prepare the release program."

                              Compose planning and execution explicitly through standard input:

                              xmd plan "Prepare the release program."| xmd run -

                              Or preserve the artifact first and run the saved file later:

                              xmd plan "Prepare the release program." --output release.md && xmd run release.md

                              --output remains an exclusive file sink: it creates the requested path only
                              after approval and never replaces an existing file. Without it, stdout contains
                              only the exact approved program bytes.

                              One command responsibility

                              xmd plan maps one instruction string to reviewed and approved XMD source. It
                              uses the same packaged <Plan> workflow as an ordinary document and does not
                              start a second root after authorship.

                              The packaged plan-command document remains a thin adapter: it supplies the
                              command surface to <Plan>, captures the resulting text, and returns those exact
                              bytes. The host awaits authorship and teardown, performs the existing final
                              caller-owned checks, and sends the artifact to exactly one destination. No
                              approved program effect runs on any success or failure path.

                              Command grammar

                              Remove --run completely; it has no alias. --run, --run=true,
                              --run=false, repeated occurrences, and any placement of that spelling receive
                              one actionable migration refusal before a catalog, Agent, session, review,
                              output file, journal, or document execution exists:

                              xmd plan --run was removed because xmd plan only produces approved source.
                              Run the program explicitly:
                              xmd plan "..." | xmd run -
                              xmd plan "..." --output release.md && xmd run release.md
                              

                              Retain only arguments that configure planning or artifact disposition:

                              • the one instruction argument;
                              • --include for the syntax catalog;
                              • --agent-provider and --default-agent for authorship;
                              • --session for the planning conversation;
                              • --timeout for the whole planning invocation;
                              • --output for the exclusive artifact sink; and
                              • ordinary --help and --version behavior.

                              Remove every option that configured the approved program's former execution:

                              • generated root-property arguments: --props, --props-*, and
                                --no-props-*;
                              • --raw;
                              • --verbose and -V;
                              • --journal and -j;
                              • --timeout-exec and --timeout-fetch;
                              • --approve-all, --approve-reads, and --deny-all; and
                              • --secret-detection and --no-secret-detection.

                              Each removed spelling refuses as an xmd plan option before authorship. The
                              corresponding xmd run options remain unchanged. #676 later introduces the
                              long-form --verbose and --journal <path> options together with their complete
                              authorship presentation and diagnostic behavior; this story does not accept
                              inert placeholders for them.

                              Update command help to say:

                              Turn a request into an XMD Plan, review it, and write the approved source.
                              

                              Help never promises to run the Plan and shows both explicit CLI compositions.

                              Exact artifact behavior

                              • Default stdout and --output receive the same byte-identical source and
                                digest supplied by Make <Plan> emit or capture approved XMD source #722.
                              • Status, review UI, and planning presentation never contaminate stdout or the
                                exclusive output file.
                              • Stop, exhaustion, failure, cancellation, or final refusal writes no artifact
                                and starts no program.
                              • The output file is created exclusively only after approval and teardown.
                              • A command continuation or planning session cannot cause the approved program
                                to execute implicitly.
                              • The command has no later program execution to observe or retain.

                              Acceptance ownership

                              This story exclusively owns these Quest cases:

                              • CLI Plan: exact approved bytes reach stdout or the exclusive output file;
                                a negative-control program effect never occurs.
                              • Removed execution option: every --run spelling reports the migration
                                above and never aliases or executes.
                              • Planning-only grammar: only planning and artifact-disposition options are
                                accepted; every former execution option refuses before authorship, and no
                                accepted option can cause implicit execution.

                              The successful stdin pipeline belongs to #723; this story owns the Plan
                              producer and the diagnostic that points to it. #676 owns and later introduces
                              the planning-only --verbose and --journal options.

                              Documentation and focused evidence

                              Rewrite specs/plan-command-spec.md around the single source-artifact outcome.
                              Update the command/component inventory and command lifecycle in
                              architecture.md and specs/executable-mdx-spec.md. In particular, remove the
                              stale inventory claims that <Plan> requires as, emits no source, or that
                              xmd plan can execute approved source through --run; #722 made <Plan> an
                              exact text component whose bare form emits and whose as form captures.

                              Update CLI help, README, and the homepage delivered by PR #719 so they show the
                              explicit command-line composition:

                              Plan produces a program.
                              Run executes a program from the host/CLI.
                              Composition decides whether and when a planned program runs.
                              

                              The homepage includes xmd plan | xmd run -. #713 owns the homepage's
                              <Plan>-followed-by-<Evaluate> example and complete-program evaluation model;
                              PR #719 remains historical and unchanged.

                              The Planner handoff inventories the complete revised xmd plan --help output
                              and every changed user-facing diagnostic as exact text for product approval.
                              It reuses the source-only command diagnostics already settled in #676 where
                              they apply and introduces no unreviewed copy during implementation.

                              Focused feedback evidence:

                              deno task test \
                              packages/cli/tests/plan-cli.test.ts \
                              packages/cli/tests/plan-command-document.test.ts \
                              packages/cli/tests/plan-component.test.ts \
                              packages/cli/tests/syntax-cli.test.ts \
                              packages/cli/tests/packaged-document.test.ts

                              The CLI suite covers every retained and removed option class, exact stdout and
                              exclusive output, all no-artifact failures, and negative-control non-execution.
                              After a feedback commit, run deno task test --changed. Delivery proves the npm
                              binary with scripts/tests/cli-npm-bin.test.ts, the compiled command with
                              scripts/tests/plan-component-compiled.test.ts after deno task build, and the
                              required CI checks.

                              Dependencies

                              Out of scope

                              Activity

                              Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

                              Metadata

                              Metadata

                              Assignees

                              No one assigned

                                Labels

                                enhancementNew feature or request

                                Projects

                                No projects

                                  Milestone

                                  No milestone

                                  Relationships

                                  None yet

                                  Development

                                  No branches or pull requests

                                  Issue actions