{
  "sourceCommit": "5b3cc3a256250b42a1a0a7e639fd6fb4388db0f5",
  "source": "src/commands.ts",
  "checkedAt": "2026-09-15",
  "commands": [
    {
      "name": "preflight",
      "group": "collegare",
      "title": "Check prerequisites",
      "description": "Checks Node, coding CLIs and GitHub tooling before a project is connected. Reports the missing prerequisite.",
      "effect": "Checks only",
      "syntax": "northstar preflight [--pack <dir>] [--agent <provider>]",
      "subcommands": [],
      "options": [
        "--pack <dir>",
        "--agent <provider>"
      ]
    },
    {
      "name": "adopt",
      "group": "collegare",
      "title": "Connect an existing repository",
      "description": "Builds a project pack from Git history, including work, release markers and recurring activity. Review the proposed release convention.",
      "effect": "Creates a pack",
      "syntax": "northstar adopt --repo <dir> --pack <dir> [--yes] [--force] [options]",
      "subcommands": [],
      "options": [
        "--repo <dir>",
        "--name <name>",
        "--mission <text>",
        "--north-star <metric>",
        "--release-marker <tag|release|commit|none>",
        "--release-pattern <regexp>",
        "--routine-min <n>",
        "--family-min <n>",
        "--limit <n>",
        "--offline",
        "--yes",
        "--force"
      ]
    },
    {
      "name": "refresh",
      "group": "collegare",
      "title": "Complete readable product context",
      "description": "Finds missing labels and user outcomes. --fix applies mechanical corrections; --propose asks an agent for reviewable wording.",
      "effect": "Writes with flags",
      "syntax": "northstar refresh [--pack <dir> | --packs <dir>] [--fix] [--propose] [--json]",
      "subcommands": [],
      "options": [
        "--pack <dir>",
        "--packs <dir>",
        "--fix",
        "--propose",
        "--propose-family",
        "--propose-value",
        "--agent <provider>",
        "--batch <n>",
        "--passes <n>",
        "--from <file>",
        "--json"
      ]
    },
    {
      "name": "truth",
      "group": "collegare",
      "title": "Read current problems",
      "description": "Runs the probe declared by the pack and returns identified signals with priorities. The configured probe determines source access.",
      "effect": "Runs a probe",
      "syntax": "northstar truth --pack <dir>",
      "subcommands": [],
      "options": []
    },
    {
      "name": "triage",
      "group": "loop",
      "title": "Select one task",
      "description": "Returns at most one task packet with its issue boundary and required evidence. It does not start a worker.",
      "effect": "Reads state",
      "syntax": "northstar triage --pack <dir>",
      "subcommands": [],
      "options": []
    },
    {
      "name": "checkpoint",
      "group": "loop",
      "title": "Decide whether the loop can stop",
      "description": "Reports executable work, an active PR to resume, a human dependency or a valid stop. Use at the start and end of a run.",
      "effect": "Reads state",
      "syntax": "northstar checkpoint --pack <dir>",
      "subcommands": [],
      "options": []
    },
    {
      "name": "run",
      "group": "loop",
      "title": "Execute bounded repair work",
      "description": "Starts a coding worker in a dedicated worktree and resumes according to checkpoint results. Pack permissions and per-run budgets apply.",
      "effect": "Executes work",
      "syntax": "northstar run --pack <dir> [--agent <provider>] [--require-strategist] [limits]",
      "subcommands": [],
      "options": [
        "--agent <provider>",
        "--agent-args <text>",
        "--require-strategist",
        "--strategist-agent <provider>",
        "--resume-worktree <dir>",
        "--max-hours <n>",
        "--max-invocations <n>",
        "--max-consecutive-failures <n>",
        "--max-consecutive-no-progress <n>",
        "--max-consecutive-execution-only <n>",
        "--worker-timeout-minutes <n>"
      ]
    },
    {
      "name": "watch",
      "group": "loop",
      "title": "Keep checking on a schedule",
      "description": "Records periodic observations and launches the configured run command when work exists. Requires the pack schedule and a running host.",
      "effect": "Schedules work",
      "syntax": "northstar watch --pack <dir>",
      "subcommands": [],
      "options": []
    },
    {
      "name": "confirm-cause",
      "group": "loop",
      "title": "Validate the cause before editing",
      "description": "Checks the evidence and failing reproducer before a repair begins. Rejects unsupported cause claims without writing a receipt.",
      "effect": "Validates and records",
      "syntax": "northstar confirm-cause --pack <dir> (--json <claims> | --file <path>)",
      "subcommands": [],
      "options": [
        "--json <claims>",
        "--file <path>"
      ]
    },
    {
      "name": "confirm-fix",
      "group": "loop",
      "title": "Record a tested repair",
      "description": "Checks the passing reproducer, test suite and bounded change. This is the command that creates a remediation receipt.",
      "effect": "Validates and records",
      "syntax": "northstar confirm-fix --pack <dir> (--json <claims> | --file <path>)",
      "subcommands": [],
      "options": [
        "--json <claims>",
        "--file <path>"
      ]
    },
    {
      "name": "record",
      "group": "loop",
      "title": "Record a lifecycle event",
      "description": "Appends evidence of a merge, deployment, decision or resolution. It cannot create remediation or independent verification receipts.",
      "effect": "Writes a receipt",
      "syntax": "northstar record --pack <dir> (--json <receipt> | --file <path>)",
      "subcommands": [],
      "options": [
        "--json <receipt>",
        "--file <path>"
      ]
    },
    {
      "name": "verify",
      "group": "loop",
      "title": "Independently check the released fix",
      "description": "Runs the configured verifier against the released revision outside the worker’s worktree. Can detect recurrence on a previously verified repair.",
      "effect": "Runs checks and records",
      "syntax": "northstar verify --pack <dir> [--signal <identity>]",
      "subcommands": [],
      "options": [
        "--signal <identity>"
      ]
    },
    {
      "name": "cures",
      "group": "loop",
      "title": "Inspect and recheck repairs",
      "description": "Lists verified repair boundaries and their measuring commands. --cure reruns the check for a selected repair.",
      "effect": "Rechecks with a flag",
      "syntax": "northstar cures --pack <dir> [--cure <id>]",
      "subcommands": [],
      "options": [
        "--cure <id>"
      ]
    },
    {
      "name": "strategist",
      "group": "giudizio",
      "title": "Review the selected work",
      "description": "Evaluates a bounded task packet against mission, metrics and history. Produces a recommendation and rationale, not lifecycle proof.",
      "effect": "Records a review",
      "syntax": "northstar strategist --pack <dir> [--agent <provider>]",
      "subcommands": [],
      "options": [
        "--agent <provider>"
      ]
    },
    {
      "name": "audit",
      "group": "giudizio",
      "title": "Find reproducible work",
      "description": "Investigates under the pack’s declared audit perspective, records evidence and turns findings into backlog work. Each pass tracks what changed.",
      "effect": "Investigates and writes",
      "syntax": "northstar audit --pack <dir> [--agent <provider>]",
      "subcommands": [],
      "options": [
        "--agent <provider>"
      ]
    },
    {
      "name": "advisor",
      "group": "giudizio",
      "title": "Track gaps against a goal",
      "description": "Scans threshold gaps or records a declared opportunity. Gaps become backlog work through backlog accept. This is distinct from product-advisor.",
      "effect": "Writes gap records",
      "syntax": "northstar advisor [scan|add|dismiss] --pack <dir> [options]",
      "subcommands": [
        "scan",
        "add",
        "dismiss"
      ],
      "options": [
        "--kind <Prodotto|Funzione|Esperienza>",
        "--title <text>",
        "--why <text>",
        "--score <1|2|3>",
        "--lane <lane>",
        "--short <text>",
        "--gap <id>",
        "--source <channel>",
        "--url <url>",
        "--voices <n>",
        "--last-at <date>",
        "--limit <n>"
      ]
    },
    {
      "name": "product-advisor",
      "group": "giudizio",
      "title": "Review capabilities and engineering history",
      "description": "Builds fact packs, candidates and bounded model reviews. Records advisory runs without changing the lifecycle, backlog or product map.",
      "effect": "Records advice",
      "syntax": "northstar product-advisor [fact-pack|candidates|run|brief|runs|audit|review-pack] --pack <dir> [options]",
      "subcommands": [
        "fact-pack",
        "candidates",
        "run",
        "brief",
        "runs",
        "audit",
        "review-pack"
      ],
      "options": [
        "--agent <stub|muse|claude|codex|grok>",
        "--top <n>",
        "--batch <n>",
        "--json"
      ]
    },
    {
      "name": "owner-decision",
      "group": "giudizio",
      "title": "Keep owner decisions and outcomes",
      "description": "Records owner judgments on Advisor recommendations. Explicit promotion checks eligibility and enters the existing governed intake; work reads back its state. Neither action launches an executor or grants release permission.",
      "effect": "Records decisions or explicitly promotes eligible work; no execution",
      "syntax": "northstar owner-decision [record|history|position|outcomes|metrics|promote|work] --pack <dir> [options]",
      "subcommands": [
        "record",
        "history",
        "position",
        "outcomes",
        "metrics",
        "promote",
        "work"
      ],
      "options": [
        "--run <advisorRunId>",
        "--subject <id>",
        "--subject-type <type>",
        "--decision <verdict>",
        "--decision <decisionId>",
        "--rationale <text>",
        "--by <actor>",
        "--supersedes <decisionId>",
        "--json <input>",
        "--file <path>",
        "--dry-run"
      ]
    },
    {
      "name": "capability-success",
      "group": "giudizio",
      "title": "Measure a capability’s product benefit",
      "description": "Reads status, runs declared measurements, records a hypothesis and compares stored before/after observations with an explicit attribution basis. Does not authorize engineering work.",
      "effect": "Measures and records",
      "syntax": "northstar capability-success [status|measure|expect|verify-benefit] --pack <dir> [options]",
      "subcommands": [
        "status",
        "measure",
        "expect",
        "verify-benefit"
      ],
      "options": [
        "--capability <id>",
        "--hypothesis <text>",
        "--by <actor>",
        "--baseline <measurementRef>",
        "--expectation <ref>",
        "--after <measurementRef>",
        "--before <measurementRef>",
        "--release <ref>",
        "--attribution-kind <none|controlled_experiment|explicit_owner_attribution>",
        "--attribution-ref <ref>"
      ]
    },
    {
      "name": "approve",
      "group": "giudizio",
      "title": "Approve a Strategist proposal",
      "description": "Records the owner’s approval for a specific proposal. A coding agent must already have authority to represent that decision.",
      "effect": "Owner authority required",
      "syntax": "northstar approve --pack <dir> --proposal <n>",
      "subcommands": [],
      "options": [
        "--proposal <n>"
      ]
    },
    {
      "name": "approvals",
      "group": "giudizio",
      "title": "Inspect approvals and expired claims",
      "description": "Lists approvals. The explicit sweep operation releases expired claims; it is not an automatic background action.",
      "effect": "Sweep changes state",
      "syntax": "northstar approvals [list|sweep] --pack <dir> [--max-age-minutes <n>]",
      "subcommands": [
        "list",
        "sweep"
      ],
      "options": [
        "--max-age-minutes <n>"
      ]
    },
    {
      "name": "upstream",
      "group": "giudizio",
      "title": "Review framework drift",
      "description": "Compares declared upstream baselines with mirrors and records decisions on differences. Use for framework maintenance, not ordinary product repair.",
      "effect": "Decision writes",
      "syntax": "northstar upstream [check|decide|decisions] [--repo <owner/repo>] [--ref <ref>] [--dir <mirror>]",
      "subcommands": [
        "check",
        "decide",
        "decisions"
      ],
      "options": [
        "--repo <owner/repo>",
        "--ref <ref>",
        "--dir <mirror>",
        "--json <decision> | --file <path>",
        "--priority <P1|P2|P3>",
        "--promotion-title <text>"
      ]
    },
    {
      "name": "intake",
      "group": "backlog",
      "title": "Turn a request into durable work",
      "description": "Validates a full batch of classified requests, checks existing evidence and duplicates, appends the intake decision and returns stable backlog IDs.",
      "effect": "Writes backlog intake",
      "syntax": "northstar intake --pack <dir> (--json <batch> | --file <path>)",
      "subcommands": [],
      "options": [
        "--json <batch>",
        "--file <path>"
      ]
    },
    {
      "name": "backlog",
      "group": "backlog",
      "title": "Manage declared work",
      "description": "Lists, adds, links and changes work status. Can accept legacy Advisor gaps and import Strategist proposals. Status updates append history.",
      "effect": "Writes by subcommand",
      "syntax": "northstar backlog [list|add|accept|link|set-status|import-proposal] --pack <dir> [options]",
      "subcommands": [
        "list",
        "add",
        "accept",
        "link",
        "set-status",
        "import-proposal"
      ],
      "options": [
        "--title <text>",
        "--priority <P1|P2|P3>",
        "--evidence <text>",
        "--id <id>",
        "--status <status>",
        "--signal <identity>",
        "--family <key>",
        "--gap <id>",
        "--proposal <n>"
      ]
    },
    {
      "name": "roadmap",
      "group": "backlog",
      "title": "Review and update the roadmap",
      "description": "Reads and validates the roadmap, previews a patch, applies it or activates a node. Preview first and preserve revision checks.",
      "effect": "Writes by subcommand",
      "syntax": "northstar roadmap [status|validate|preview|apply|activate] --pack <dir> [--file <patch>]",
      "subcommands": [
        "status",
        "validate",
        "preview",
        "apply",
        "activate"
      ],
      "options": [
        "--file <patch>"
      ]
    },
    {
      "name": "milestone",
      "group": "backlog",
      "title": "Set a measurable project milestone",
      "description": "Records a milestone, selects the active one or records completion. Declaring a target and achieving it are separate events.",
      "effect": "Writes by subcommand",
      "syntax": "northstar milestone [list|add|set|done] \"<name>\" --pack <dir> [options]",
      "subcommands": [
        "list",
        "add",
        "set",
        "done"
      ],
      "options": [
        "--name <name>",
        "--hint <text>",
        "--progress <metric>",
        "--tail <text>",
        "--node <id>",
        "--no-node",
        "--no-activate"
      ]
    },
    {
      "name": "issues",
      "group": "backlog",
      "title": "Schedule work",
      "description": "Reads the work plan or assigns an issue identity to a sprint, target date and position. Supports an expected revision for writes.",
      "effect": "Plan changes state",
      "syntax": "northstar issues [status|plan] --pack <dir> [--identity <id> --sprint <name> --target-date <date> --position <n>]",
      "subcommands": [
        "status",
        "plan"
      ],
      "options": [
        "--identity <id>",
        "--sprint <name>",
        "--target-date <date>",
        "--position <n>",
        "--expected-revision <n>"
      ]
    },
    {
      "name": "relations",
      "group": "backlog",
      "title": "Connect causes and dependencies",
      "description": "Lists or adds same-cause and dependency relationships. Validates the graph and rejects dependency cycles. Confirm shared causes with evidence.",
      "effect": "Add changes state",
      "syntax": "northstar relations [list|add] --pack <dir> [--from <identity> --to <identity> --kind <type> --note <text>]",
      "subcommands": [
        "list",
        "add"
      ],
      "options": [
        "--from <identity>",
        "--to <identity>",
        "--kind <type>",
        "--note <text>"
      ]
    },
    {
      "name": "map",
      "group": "backlog",
      "title": "Build and maintain the capability map",
      "description": "Scans and proposes topology, detects Git-based drift, revises or declares nodes and links, and reads current or historical capability views. Proposed and declared links remain distinct.",
      "effect": "Writes by subcommand",
      "syntax": "northstar map [scan|drift|revise|declare|propose-topology|propose-links|retract-link|status|history|show] --pack <dir> [options]",
      "subcommands": [
        "scan",
        "drift",
        "revise",
        "declare",
        "propose-topology",
        "propose-links",
        "retract-link",
        "status",
        "history",
        "show"
      ],
      "options": [
        "--patch <json>",
        "--file <path>",
        "--node <id>",
        "--edge <from,to,kind>",
        "--expected-revision <n>",
        "--link <linkId>",
        "--label <text>",
        "--batch <n>",
        "--agent <name>",
        "--revision <n>",
        "--revisit",
        "--history"
      ]
    },
    {
      "name": "reproject",
      "group": "backlog",
      "title": "Correct a derived view",
      "description": "Previews and applies controlled projection corrections while preserving the raw ledger. Use the frozen count, hash and cutoff safeguards.",
      "effect": "Preview or governed write",
      "syntax": "northstar reproject --pack <dir> (--json <request> | --file <path>) [--dry-run]",
      "subcommands": [],
      "options": [
        "--json <request>",
        "--file <path>",
        "--dry-run"
      ]
    },
    {
      "name": "diary",
      "group": "osservare",
      "title": "Read lifecycle history",
      "description": "Reads ledger receipts for a signal identity or family. Use it to reconstruct attempted fixes, releases and verification.",
      "effect": "Reads state",
      "syntax": "northstar diary --pack <dir> [--signal <identity> | --family <key>]",
      "subcommands": [],
      "options": [
        "--signal <identity>",
        "--family <key>"
      ]
    },
    {
      "name": "metrics",
      "group": "osservare",
      "title": "Measure project metrics",
      "description": "Runs the declared metric sources and reports values and history length. --record saves an observation. Missing values remain unknown.",
      "effect": "Measures; optional record",
      "syntax": "northstar metrics --pack <dir> [--record]",
      "subcommands": [],
      "options": [
        "--record"
      ]
    },
    {
      "name": "board",
      "group": "osservare",
      "title": "Read the owner board",
      "description": "Builds a view across project packs. Unreadable packs remain visible. --html writes the board to a local file.",
      "effect": "Reads; optional export",
      "syntax": "northstar board [--packs <dir>] [--project <name>] [--view owner] [--html <file>] [--plain]",
      "subcommands": [],
      "options": [
        "--packs <dir>",
        "--project <name>",
        "--view owner",
        "--html <file>",
        "--plain"
      ]
    },
    {
      "name": "serve",
      "group": "osservare",
      "title": "Open the local board",
      "description": "Serves a live view of project packs on a local port. This starts the board server, not a repair worker.",
      "effect": "Starts local server",
      "syntax": "northstar serve --packs <dir> [--port <n>]",
      "subcommands": [],
      "options": [
        "--packs <dir>",
        "--port <n>"
      ]
    },
    {
      "name": "durability",
      "group": "osservare",
      "title": "Back up or restore Factory state",
      "description": "Checks whether state has a mirror, copies the complete .factory directory, or restores it from a chosen mirror. Restore replaces local Factory state.",
      "effect": "Restore replaces state",
      "syntax": "northstar durability [status|mirror|restore] --pack <dir> [--from <dir>]",
      "subcommands": [
        "status",
        "mirror",
        "restore"
      ],
      "options": [
        "--from <dir>"
      ]
    },
    {
      "name": "memory",
      "group": "osservare",
      "title": "Reconcile engineering evidence",
      "description": "Imports bounded evidence from database, Git and diaries; links identifiers and reports reconciliation or mapping eligibility. Reads source repositories without modifying them.",
      "effect": "Writes imported evidence",
      "syntax": "northstar memory [import-db|import-git|import-diary|link|report|delta] --pack <dir> [--repo <dir> --repo-slug <owner/name>|--offline] [--docs <dir>]",
      "subcommands": [
        "import-db",
        "import-git",
        "import-diary",
        "link",
        "report",
        "delta"
      ],
      "options": [
        "--repo <dir>",
        "--repo-slug <owner/name>",
        "--docs <dir>",
        "--offline"
      ]
    }
  ]
}