ticket-new.mjs

Files a Forge issue whose body is rendered from this repository's ticket standard, checked against it, and whose acceptance command has been run and seen to fail.

Agent tooling › ticket-new.mjs

What it does

Renders a body from the sections in tools/lib/ticket-standard.mjs, for the kind named on the command line. Stamps the branch and worktree out of git, and the date off the clock. Checks the result with tools/ticket-lint.mjs, then runs the acceptance command in the repository root and refuses the ticket when it already exits zero. Creates the issue through node tools/forge.mjs create-issue only after both pass.

Usage

One command files a ticket, with the sections in a file beside it:

node tools/ticket-new.mjs --kind task --title "..." --slots-file <path.json>

Replace the following:

• task — one of task, defect, failure, spec, epic. It chooses the opening heading and which optional sections the body starts with.
• "..." — the issue title. No prefix is required or accepted.
• <path.json> — a JSON object keyed by flag name without the dashes, carrying the sections: {"what-to-build": "...", "scope": "...", "acceptance-criteria": "npm test"}.

Every section can be passed on the command line instead, as --what-to-build, --context-to-load, --scope, --blocked-by, --if-unsure and --acceptance-criteria. Use the file for anything holding a newline: git-bash truncates an argument at the first one.

Options

Flag	Value	What it does	Default
--kind	one of task, defect, failure, spec, epic	Chooses the opening heading and the optional sections offered.	Required.
--title	text	The issue title.	Required.
--requested-by	<name> (<role>)	Names who asked for the ticket. Rendered with the date into the one-line Request section.	Required.
--<section>	text	Any section of the standard, as its heading in lower case with dashes for spaces.	The required sections have no default; the optional ones are left out when absent.
--label	a Forge label name	Applies the label to the new issue. Repeatable.	No labels.
--slots-file	path to a JSON object	Supplies any section, kind, title, requested-by or label. A key set here and on the command line is refused rather than silently preferred.	Not read.
--dry-run	no value	Prints the body, the check result and the acceptance run, and creates nothing.	Off.
--json	no value	Prints the created issue as JSON instead of one line.	Off.
--help	no value	Prints the usage, including every kind and the sections it takes.	Off.
--body-file	path	Not an option of this tool. It appears in the source as the flag passed on to tools/forge.mjs create-issue with the rendered body.	Not applicable.

Inputs and outputs

Reads the JSON named by --slots-file, the git state of the repository root, and the clock. Runs the acceptance command through a shell in the repository root, so it sees whatever the repository sees. Writes the rendered body to a temporary file for tools/forge.mjs, and removes it afterwards.

On success, exit 0 and one line: issue #<n> -- <title> followed by the issue URL, or the whole issue as JSON under --json.

On a malformed invocation — an unknown kind, a missing section, a section that is stamped rather than written — exit 2 and no issue. On a body that does not meet the standard, exit 1 with the findings. On an acceptance command that already exits zero, exit 1 with the command and its output. Under --dry-run, exit 0 when both would pass and 1 when either would not.

Examples

See what would be filed, and prove the gate is red, without creating anything:

node tools/ticket-new.mjs --kind task --title "The map feed carries recent battles" \
  --requested-by "Evgenii Shmoish (owner)" --slots-file .gwtmp/ticket.json --dry-run

File a defect with the label the queue reads:

node tools/ticket-new.mjs --kind defect --title "The station panel offers no action" \
  --requested-by "Evgenii Shmoish (owner)" --slots-file .gwtmp/ticket.json --label ready-for-agent

Notes

The acceptance command reaches a shell, so pass it bare: a backticked command is a substitution the shell performs before running anything, and it can never go green. A leading ! is refused for the same reason on the other side — it does not run on every platform this repository builds on.

There is no override. No flag and no environment variable skips the check or the acceptance run, and --dry-run creates nothing, so a body that does not meet the standard is never filed.

Provenance and Request are refused as flags. They are stamped from git and the clock because an agent asked to remember which tree it was working in misremembers it.

Source

tools/ticket-new.mjs — part of Agent tooling

See also: tools/ticket-lint.mjs the standard, read backwards