Ticket System

Ticket System

Purpose: Context anchor to prevent LLM loops during complex work. Colocates all artifacts.

Namespace root: Resolve from paths.projectRoot in .safeword/config.json; if unset, use .project/ by default, falling back to legacy .safeword-project/ only when that directory already exists. Substitute the resolved root in every path below.

Creating a ticket: Resolve the Safeword CLI locally first, then run ticket new through that resolver:

if [ -x node_modules/.bin/safeword ]; then
  SW="node_modules/.bin/safeword"
elif [ -f packages/cli/src/cli.ts ]; then
  # Only true inside safeword's own repo (dogfooding) — runs from source
  # instead of requiring a build.
  SW="bun packages/cli/src/cli.ts"
else SW="bunx safeword"; fi

$SW ticket new <slug> # --type=patch|task|feature|epic, --title="...", --goal="...", --why="...", --issue="<existing-key>"

--goal fills the Goal field for any type; --why fills the rationale for task/patch/epic (features keep motivation in spec.md, so --why is rejected there). --type=epic scaffolds a container ticket with an empty children: list.

With ticketBridge.provider: none, the CLI mints a 6-char Crockford Base32 ID. With GitHub or Linear connected, a non-epic ticket creates its tracker issue first and uses the tracker key as its ID; --issue="<existing-key>" adopts that issue without creating one. Epics always remain local Crockford-ID containers. Every route creates the folder atomically and writes a starter ticket.md. Do not scan the tickets directory and pick the next ID yourself — that races between parallel sessions and silently collides across git branches. If the resolver cannot run, stop and report that the CLI is unresolvable; do not hand-mint a fallback ID.

ticket new pre-populates ticket.md (and spec.md for features) with placeholder content. Pass real values with --goal/--title/--why at creation, or Edit the scaffolded fields — do not blind-Write the whole file, which fails because the freshly-created file hasn't been Read yet.

Location: <namespace-root>/tickets/{ID}-{slug}/ for tickets created by the resolved ticket new command above. {ID} is a 6-char Crockford value for local tickets and epics, a GitHub issue number for GitHub-connected tickets, or a tracker key such as ENG-45 for Linear. The slug is always normalized. Lookup remains backward-compatible with older {ID}/ Crockford folders and legacy {numeric-id}-{slug}/ folders — all formats remain reachable by their frontmatter ID.

Folder structure:

<namespace-root>/
├── tickets/
│   ├── 7K9M3P-login-bug/       # Current format: Crockford ID + normalized slug
│   │   ├── ticket.md           # Ticket definition (frontmatter + work log)
│   │   ├── test-definitions.md # BDD scenarios (Given/When/Then)
│   │   ├── spec.md             # Product spec (features only; auto-created)
│   │   └── design.md           # Design doc for complex features (optional)
│   ├── ENG-45-login-bug/       # Connected/adopted tracker key + normalized slug
│   │   └── ticket.md
│   ├── 7K9M3P/                 # Historical Crockford ID-only format, still readable
│   │   └── ticket.md
│   ├── 080-ticket-id-collision/  # Legacy numeric format, still readable
│   │   └── ticket.md
│   └── completed/              # Archive for done tickets
├── learnings/                  # Extracted knowledge (gotchas, discoveries)
└── tmp/                        # Scratch space (research, logs, etc.)

Artifact Levels:

Create a ticket when any of these holds: multiple attempts are likely, the work is multi-step with dependencies, it needs investigation/debugging, or there's a risk of losing context mid-session. Otherwise skip it.

Examples: "Fix typo" → skip. "Debug slow login" → ticket. "Add OAuth" → ticket.

Minimal structure:

---
id: 7K9M3P
slug: feature-name
status: in_progress
---

# [Title]

**Goal:** [one sentence]

## Work Log

- [timestamp] Started: [task]
- [timestamp] Found: [finding]
- [timestamp] Complete: [result]

Frontmatter values:

• status: in_progress | done | cancelled | superseded | wontfix | blocked
• phase: intake | define-behavior | scenario-gate | plan-implementation | implement | verify | done (see ticket-template.md)
• phase_skips: ["<phase>: <reason>", ...] (optional; feature tickets only) — one entry per phase a feature was born into or advanced past without traversing it. Block sequence, non-empty reason each; the phase-provenance gate requires it when a feature skips phases (see glossary "Gate")
• phase_anchors: ["<phase>: <artifact-path>", ...] (optional; feature tickets only) — one entry per phase entered on a forward advance, recording the repo-relative path of the exit artifact of the phase being left (define-behavior ← spec.md · scenario-gate ← the feature source · implement ← impl-plan.md · verify ← test-definitions.md · done ← verify.md). Append one entry per phase; on a re-advance the latest entry for a phase wins (it names the phase's current output). The boundary gate verifies the artifact exists (and looks right) in the tree being shipped — never against git history, so anchors survive amend, rebase, squash-merge, and shallow clones. Hex commit-SHA anchors on pre-redesign tickets are grandfathered at rest
• parent: <id> (optional)
• epic: <slug-or-id> (optional)
• blocked_on: [<id>, <id>] (optional)
• depends_on: [<id>] (optional)
• external_issue: <https://.../issues/nnn> (optional; one canonical issue/link)
• external_prs: [<https://.../pull/nnn>, ...] (optional; active or relevant PR links)

Rules:

• Log immediately after each action
• Re-read ticket before significant actions
• For detailed scratch notes, use a separate work log (see Work Logs below)
• Cite durable anchors, not raw line numbers. file.md:18-22 goes stale after any unrelated merge (#799). Anchor each edit site to something that survives drift — heading text, a unique grep pattern, or a function name — and re-grep before editing if you must quote a line number.
• CRITICAL: Never mark done without user confirmation

Work Logs

Purpose: Scratch pad and working memory during execution. Think hard. Keep notes.

Location: .safeword/logs/{artifact-type}-{slug}.md

Naming convention:

One artifact = one log. If log exists, append a new session. Don't spawn multiple logs for the same work.

Create a log when executing a plan, ticket, or spec, or when investigation/debugging spans multiple attempts. Skip it for a quick single-action task.

Think hard behaviors:

1. Re-read the log before each major action
2. Pause to review your approach periodically
3. Log findings as you discover them, not after
4. Note dead ends so you don't repeat them

Log what helps you stay on track: findings, decisions, hypotheses, blockers, scratch calculations. Use your discretion.

Edge cases:

Templates

Use the matching template when ANY trigger fires: