fde-workflow-cli 0.1.0__tar.gz

fde_workflow_cli-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) Marco Fura Mendoza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

fde_workflow_cli-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: fde-workflow-cli
+Version: 0.1.0
+Summary: Direction framework for FDE customer projects: North Star, KPIs with baselines, paths, stages and decisions, on top of any execution methodology.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,cli
+Author: Marco Fura Mendoza
+Requires-Python: >=3.13,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: pydantic (>=2.14,<3)
+Requires-Dist: pyyaml (>=6.0.3,<7)
+Requires-Dist: typer (>=0.27,<1.0)
+Project-URL: Homepage, https://github.com/mjfura/fde-workflow
+Project-URL: Issues, https://github.com/mjfura/fde-workflow/issues
+Project-URL: Repository, https://github.com/mjfura/fde-workflow
+Description-Content-Type: text/markdown
+
+# fde-workflow-cli
+
+Command line tool of the `fde-workflow` Claude Code plugin: it reads and writes a repository's
+FDE direction in `.fde/` and enforces the framework's rules.
+
+```sh
+uv tool install fde-workflow-cli    # or: pipx install fde-workflow-cli
+fde-workflow --version
+fde-workflow doctor                 # checks that everything is ready
+```
+
+| Command | Purpose |
+|---|---|
+| `init`, `detect` | Set up `.fde/`; inspect a repository's methodology and artifacts |
+| `status`, `context`, `validate` | Summaries for people and for Claude; rule checks |
+| `project set` | The project's name, customer and sponsor |
+| `northstar set\|confirm` | The North Star |
+| `kpi add\|update\|measure` | KPIs, their recipes and measurements |
+| `path add\|update\|move\|link\|confirm` | Paths and their links to execution work |
+| `stage set\|confirm\|criteria\|decide` | The project stage and its gates |
+| `decision add` | Other direction decisions |
+| `hook session-start` | Entry point of the plugin's SessionStart hook |
+
+Run `fde-workflow <command> --help` for the options. Requires Python 3.13 or newer. Source and
+plugin: https://github.com/mjfura/fde-workflow
+

fde_workflow_cli-0.1.0/README.md

@@ -0,0 +1,25 @@
+# fde-workflow-cli
+
+Command line tool of the `fde-workflow` Claude Code plugin: it reads and writes a repository's
+FDE direction in `.fde/` and enforces the framework's rules.
+
+```sh
+uv tool install fde-workflow-cli    # or: pipx install fde-workflow-cli
+fde-workflow --version
+fde-workflow doctor                 # checks that everything is ready
+```
+
+| Command | Purpose |
+|---|---|
+| `init`, `detect` | Set up `.fde/`; inspect a repository's methodology and artifacts |
+| `status`, `context`, `validate` | Summaries for people and for Claude; rule checks |
+| `project set` | The project's name, customer and sponsor |
+| `northstar set\|confirm` | The North Star |
+| `kpi add\|update\|measure` | KPIs, their recipes and measurements |
+| `path add\|update\|move\|link\|confirm` | Paths and their links to execution work |
+| `stage set\|confirm\|criteria\|decide` | The project stage and its gates |
+| `decision add` | Other direction decisions |
+| `hook session-start` | Entry point of the plugin's SessionStart hook |
+
+Run `fde-workflow <command> --help` for the options. Requires Python 3.13 or newer. Source and
+plugin: https://github.com/mjfura/fde-workflow

fde_workflow_cli-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "fde-workflow-cli"
+version = "0.1.0"
+description = "Direction framework for FDE customer projects: North Star, KPIs with baselines, paths, stages and decisions, on top of any execution methodology."
+authors = [{ name = "Marco Fura Mendoza" }]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["claude-code", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+requires-python = ">=3.13,<4.0"
+dependencies = [
+    "typer (>=0.27,<1.0)",
+    "pydantic (>=2.14,<3)",
+    "pyyaml (>=6.0.3,<7)",
+]
+
+[project.scripts]
+fde-workflow = "fde_workflow_cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/mjfura/fde-workflow"
+Repository = "https://github.com/mjfura/fde-workflow"
+Issues = "https://github.com/mjfura/fde-workflow/issues"
+
+[tool.poetry]
+packages = [{ include = "fde_workflow_cli", from = "src" }]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.1"
+ruff = "^0.16"
+mypy = "^2.3"
+types-pyyaml = "^6.0.12.20260906"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "UP", "SIM", "RUF", "S", "PT"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fde_workflow_cli-0.1.0/src/fde_workflow_cli/__init__.py

@@ -0,0 +1 @@
+"""The fde-workflow command line tool."""

fde_workflow_cli-0.1.0/src/fde_workflow_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m fde_workflow_cli`."""
+
+from fde_workflow_cli.main import app
+
+app(prog_name="fde-workflow")

fde_workflow_cli-0.1.0/src/fde_workflow_cli/clock.py

@@ -0,0 +1,7 @@
+"""Today's date, in one place so tests can fix it."""
+
+import datetime as dt
+
+
+def today() -> dt.date:
+    return dt.date.today()

fde_workflow_cli-0.1.0/src/fde_workflow_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""The CLI's command groups."""

fde_workflow_cli-0.1.0/src/fde_workflow_cli/commands/common.py

@@ -0,0 +1,87 @@
+"""Helpers shared by the commands."""
+
+import datetime as dt
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+
+from fde_workflow_cli import clock
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import Decision, DecisionType, Direction, DirectionPath, Kpi
+from fde_workflow_cli.store import Store, describe_validation_error, locate
+
+RootOption = Annotated[
+    Path | None,
+    typer.Option(
+        "--root",
+        help="Repository with .fde/ (default: the closest one from the current directory).",
+    ),
+]
+
+
+def open_store(root: Path | None) -> Store:
+    return Store(root.resolve() if root else locate(Path.cwd()))
+
+
+@contextmanager
+def user_errors() -> Iterator[None]:
+    """Turn problems the user can fix into a one-line error and exit code 1."""
+    try:
+        yield
+    except FdeError as error:
+        typer.echo(f"Error: {error}", err=True)
+        raise typer.Exit(1) from error
+    except ValidationError as error:
+        typer.echo(f"Error: {describe_validation_error('The input', error)}", err=True)
+        raise typer.Exit(1) from error
+
+
+def require(value: str | None, option: str, why: str) -> str:
+    if not value:
+        raise FdeError(f"{option} is required {why}.")
+    return value
+
+
+def parse_date(text: str, option: str) -> dt.date:
+    try:
+        return dt.date.fromisoformat(text)
+    except ValueError as error:
+        raise FdeError(f"{option} must be a date like 2026-10-12, not {text!r}.") from error
+
+
+def find_kpi(direction: Direction, kpi_id: str) -> Kpi:
+    kpi = direction.kpi(kpi_id)
+    if kpi is None:
+        raise FdeError(f"There is no KPI {kpi_id}.")
+    return kpi
+
+
+def find_path(direction: Direction, path_id: str) -> DirectionPath:
+    path = direction.path(path_id)
+    if path is None:
+        raise FdeError(f"There is no path {path_id}.")
+    return path
+
+
+def record(
+    store: Store,
+    decision_type: DecisionType,
+    summary: str,
+    reason: str,
+    approved_by: str = "",
+    refs: list[str] | None = None,
+) -> None:
+    store.append_decision(
+        Decision(
+            date=clock.today(),
+            type=decision_type,
+            summary=summary,
+            reason=reason,
+            approved_by=approved_by,
+            refs=refs or [],
+        )
+    )

fde_workflow_cli-0.1.0/src/fde_workflow_cli/commands/decision.py

@@ -0,0 +1,31 @@
+"""`fde-workflow decision`: record a direction decision no other command records."""
+
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli.commands.common import RootOption, open_store, record, user_errors
+from fde_workflow_cli.model import DecisionType
+
+app = typer.Typer(help="Record direction decisions.", no_args_is_help=True)
+
+
+@app.command()
+def add(
+    summary: Annotated[str, typer.Option(help="What was decided.")],
+    reason: Annotated[str, typer.Option(help="Why.")],
+    decision_type: Annotated[
+        DecisionType, typer.Option("--type", help="Kind of decision.")
+    ] = DecisionType.OTHER,
+    approved_by: Annotated[str, typer.Option("--approved-by", help="Who approved it.")] = "",
+    ref: Annotated[
+        list[str] | None, typer.Option("--ref", help="Related id or URL; repeat it.")
+    ] = None,
+    root: RootOption = None,
+) -> None:
+    """Record a decision, e.g. a scope change."""
+    with user_errors():
+        store = open_store(root)
+        store.load()
+        record(store, decision_type, summary, reason, approved_by, ref or [])
+    typer.echo("Decision recorded.")

fde_workflow_cli-0.1.0/src/fde_workflow_cli/commands/hook.py

@@ -0,0 +1,52 @@
+"""`fde-workflow hook`: entry points of the plugin's hooks. A hook never fails a session."""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import typer
+
+from fde_workflow_cli import rules, summary
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.store import Store, locate
+
+app = typer.Typer(help="Entry points of the Claude Code plugin hooks.", no_args_is_help=True)
+
+
+def session_context(payload: str) -> str | None:
+    """The context for a new session, or None when the repository has no .fde/."""
+    try:
+        data = json.loads(payload) if payload.strip() else {}
+    except json.JSONDecodeError:
+        data = {}
+    cwd = data.get("cwd") if isinstance(data, dict) else None
+    start = Path(cwd) if isinstance(cwd, str) else Path(os.environ.get("CLAUDE_PROJECT_DIR", "."))
+    store = Store(locate(start))
+    if not store.exists():
+        return None
+    try:
+        direction = store.load()
+        measurements = store.measurements()
+    except FdeError as error:
+        return (
+            f"{summary.CONTEXT_HEADER}\n\n.fde/ cannot be read: {error}\n"
+            "Run `fde-workflow validate`."
+        )
+    issues = rules.check(direction, measurements, store.dir)
+    return summary.context(direction, measurements, issues, brief=True)
+
+
+@app.command("session-start")
+def session_start() -> None:
+    """Print the direction as SessionStart context (reads the hook's JSON on stdin)."""
+    try:
+        text = session_context(sys.stdin.read())
+    except Exception as error:  # a hook must never interrupt the session
+        typer.echo(f"fde-workflow hook: {error}", err=True)
+        return
+    if text:
+        output = {
+            "hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": text}
+        }
+        typer.echo(json.dumps(output))

fde_workflow_cli-0.1.0/src/fde_workflow_cli/commands/kpi.py

@@ -0,0 +1,210 @@
+"""`fde-workflow kpi`: define KPIs and record their measurements."""
+
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli import clock, recipes, rules
+from fde_workflow_cli.commands.common import (
+    RootOption,
+    find_kpi,
+    open_store,
+    parse_date,
+    record,
+    require,
+    user_errors,
+)
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import (
+    BaselineType,
+    Better,
+    DecisionType,
+    Kpi,
+    KpiKind,
+    Measurement,
+    Recipe,
+    RecipeType,
+)
+from fde_workflow_cli.summary import number
+
+app = typer.Typer(help="Define KPIs and record their measurements.", no_args_is_help=True)
+
+
+@app.command()
+def add(
+    kpi_id: Annotated[str, typer.Argument(help="Kebab-case id, e.g. resolution-time.")],
+    name: Annotated[str, typer.Option(help="Human-readable name.")],
+    kind: Annotated[KpiKind, typer.Option(help="primary, secondary or guardrail.")],
+    definition: Annotated[str, typer.Option(help="What it measures and its formula.")],
+    source: Annotated[str, typer.Option(help="Where the data comes from.")],
+    better: Annotated[Better, typer.Option("--direction", help="Which way is better.")],
+    target: Annotated[
+        float, typer.Option(help="Numeric target; for a guardrail, the worst acceptable value.")
+    ],
+    recipe_type: Annotated[RecipeType, typer.Option("--recipe-type", help="How to measure it.")],
+    recipe_file: Annotated[
+        str, typer.Option("--recipe-file", help="Inside .fde/, e.g. measures/resolution-time.sql.")
+    ],
+    unit: Annotated[str, typer.Option(help="Unit, e.g. min or %.")] = "",
+    window: Annotated[str, typer.Option(help="Measurement window in days, e.g. 28d.")] = "28d",
+    root: RootOption = None,
+) -> None:
+    """Define a KPI; its recipe file must already exist."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        if direction.kpi(kpi_id):
+            raise FdeError(f"KPI {kpi_id} already exists: use `fde-workflow kpi update`.")
+        direction.kpis.append(
+            Kpi(
+                id=kpi_id,
+                name=name,
+                kind=kind,
+                definition=definition,
+                source=source,
+                unit=unit,
+                direction=better,
+                target=target,
+                window=window,
+                recipe=Recipe(type=recipe_type, file=recipe_file),
+            )
+        )
+        store.save(direction)
+    typer.echo(f"Added KPI {kpi_id}.")
+
+
+@app.command()
+def update(
+    kpi_id: Annotated[str, typer.Argument()],
+    name: Annotated[str | None, typer.Option()] = None,
+    kind: Annotated[KpiKind | None, typer.Option()] = None,
+    definition: Annotated[str | None, typer.Option()] = None,
+    source: Annotated[str | None, typer.Option()] = None,
+    better: Annotated[Better | None, typer.Option("--direction")] = None,
+    target: Annotated[float | None, typer.Option()] = None,
+    unit: Annotated[str | None, typer.Option()] = None,
+    window: Annotated[str | None, typer.Option()] = None,
+    recipe_type: Annotated[RecipeType | None, typer.Option("--recipe-type")] = None,
+    recipe_file: Annotated[str | None, typer.Option("--recipe-file")] = None,
+    reason: Annotated[str | None, typer.Option(help="Why the target changes.")] = None,
+    approved_by: Annotated[
+        str | None, typer.Option("--approved-by", help="Who approves a target change.")
+    ] = None,
+    root: RootOption = None,
+) -> None:
+    """Change a KPI; changing its target records a decision."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        kpi = find_kpi(direction, kpi_id)
+        fields = {
+            "name": name,
+            "kind": kind,
+            "definition": definition,
+            "source": source,
+            "direction": better,
+            "target": target,
+            "unit": unit,
+            "window": window,
+        }
+        changes: dict[str, object] = {k: v for k, v in fields.items() if v is not None}
+        if recipe_type or recipe_file:
+            changes["recipe"] = Recipe(
+                type=recipe_type or kpi.recipe.type, file=recipe_file or kpi.recipe.file
+            )
+        target_changed = target is not None and target != kpi.target
+        if target_changed:
+            reason = require(reason, "--reason", "to change a target")
+            approved_by = require(approved_by, "--approved-by", "to change a target")
+        direction.kpis[direction.kpis.index(kpi)] = kpi.model_copy(update=changes)
+        store.save(direction)
+        if target_changed and target is not None:
+            record(
+                store,
+                DecisionType.TARGET_CHANGE,
+                f"Target of {kpi_id}: {number(kpi.target)} → {number(target)}",
+                reason or "",
+                approved_by or "",
+                [kpi_id],
+            )
+    typer.echo(f"Updated KPI {kpi_id}.")
+
+
+@app.command()
+def measure(
+    kpi_id: Annotated[str, typer.Argument()],
+    baseline: Annotated[
+        BaselineType | None, typer.Option(help="Record it as the KPI's baseline.")
+    ] = None,
+    window_end: Annotated[
+        str | None,
+        typer.Option("--window-end", help="Last day measured, YYYY-MM-DD (default: today)."),
+    ] = None,
+    value: Annotated[float | None, typer.Option(help="The measured value.")] = None,
+    source: Annotated[str | None, typer.Option(help="Where the value came from.")] = None,
+    factors: Annotated[
+        str, typer.Option(help="External factors that may have moved the value.")
+    ] = "",
+    run: Annotated[
+        bool, typer.Option("--run", help="Run a script recipe and record its output.")
+    ] = False,
+    root: RootOption = None,
+) -> None:
+    """Record a measurement; without --value or --run, show how to take it."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        kpi = find_kpi(direction, kpi_id)
+        start, end = kpi.window_ending(
+            parse_date(window_end, "--window-end") if window_end else clock.today()
+        )
+        if end > clock.today():
+            raise FdeError(f"--window-end {end} is in the future.")
+        fingerprint = recipes.fingerprint(store.dir, kpi.recipe)
+        if fingerprint is None:
+            raise FdeError(f"Recipe .fde/{kpi.recipe.file} does not exist: write it first.")
+        if kpi.recipe.type is RecipeType.SCRIPT:
+            if value is not None:
+                raise FdeError("Script recipes are run, not typed: use --run.")
+            if not run:
+                typer.echo(
+                    f"Would run .fde/{kpi.recipe.file} with FDE_WINDOW_START={start} "
+                    f"FDE_WINDOW_END={end}.\nAdd --run to execute it and record the result."
+                )
+                return
+            value = recipes.run_script(store.dir, kpi.recipe, start, end)
+            source = source or f"script .fde/{kpi.recipe.file}"
+        else:
+            if run:
+                raise FdeError(f"Only script recipes run; {kpi.id} has a {kpi.recipe.type} recipe.")
+            if value is None:
+                text = recipes.render(store.dir, kpi.recipe, start, end)
+                typer.echo(
+                    f"{kpi.recipe.type} recipe of {kpi.id}, window {start} to {end}:\n\n{text}\n"
+                    "Take the measurement, then record it with --value N --source TEXT."
+                )
+                return
+            source = require(source, "--source", "to record a measurement")
+        previous = rules.latest_baseline(store.measurements(), kpi.id)
+        store.append_measurement(
+            Measurement(
+                kpi=kpi.id,
+                taken=clock.today(),
+                window_start=start,
+                window_end=end,
+                value=value,
+                baseline=baseline,
+                source=source,
+                external_factors=factors,
+                recipe_sha256=fingerprint,
+            )
+        )
+    unit = f" {kpi.unit}" if kpi.unit else ""
+    label = f"{baseline} baseline" if baseline else "measurement"
+    typer.echo(f"Recorded {label} {kpi.id} = {number(value)}{unit} (window {start} to {end}).")
+    if baseline is None and previous is None:
+        typer.echo(f"! {kpi.id} has no baseline yet: this measurement is not one.")
+    elif baseline is None and previous is not None and previous.recipe_sha256 != fingerprint:
+        typer.echo(
+            "! [K4] The recipe changed after the baseline: measure it again with --baseline."
+        )

fde_workflow_cli-0.1.0/src/fde_workflow_cli/commands/northstar.py

@@ -0,0 +1,90 @@
+"""`fde-workflow northstar`: define, change and confirm the North Star."""
+
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli.commands.common import RootOption, open_store, record, require, user_errors
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import DecisionType, NorthStar
+
+app = typer.Typer(help="Define, change and confirm the North Star.", no_args_is_help=True)
+
+
+@app.command("set")
+def set_(
+    statement: Annotated[
+        str | None, typer.Option(help="The outcome, for someone; never a solution.")
+    ] = None,
+    beneficiary: Annotated[str | None, typer.Option(help="Who gets the outcome.")] = None,
+    problem: Annotated[str | None, typer.Option(help="The problem it solves.")] = None,
+    non_goal: Annotated[
+        list[str] | None,
+        typer.Option("--non-goal", help="Out of scope; repeat it, the list is replaced."),
+    ] = None,
+    primary_kpi: Annotated[
+        str | None, typer.Option("--primary-kpi", help="Id of the primary KPI.")
+    ] = None,
+    inferred: Annotated[
+        bool, typer.Option("--inferred", help="Inferred from existing work; needs confirmation.")
+    ] = False,
+    reason: Annotated[str | None, typer.Option(help="Why a confirmed North Star changes.")] = None,
+    approved_by: Annotated[
+        str | None, typer.Option("--approved-by", help="Who approves the change (the sponsor).")
+    ] = None,
+    root: RootOption = None,
+) -> None:
+    """Create the North Star, or change it; changing a confirmed one records a decision."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        current = direction.north_star
+        if current is None:
+            new = NorthStar(
+                statement=require(statement, "--statement", "to create the North Star"),
+                beneficiary=beneficiary or "",
+                problem=problem or "",
+                non_goals=non_goal or [],
+                primary_kpi=primary_kpi,
+                confirmed=not inferred,
+            )
+        else:
+            fields = {
+                "statement": statement,
+                "beneficiary": beneficiary,
+                "problem": problem,
+                "non_goals": non_goal,
+                "primary_kpi": primary_kpi,
+            }
+            changes: dict[str, object] = {k: v for k, v in fields.items() if v is not None}
+            if inferred:
+                changes["confirmed"] = False
+            new = current.model_copy(update=changes)
+        is_change = current is not None and current.confirmed and new != current
+        if is_change:
+            reason = require(reason, "--reason", "to change a confirmed North Star")
+            approved_by = require(approved_by, "--approved-by", "to change a confirmed North Star")
+        direction.north_star = new
+        store.save(direction)
+        if is_change:
+            record(
+                store,
+                DecisionType.NORTH_STAR_CHANGE,
+                f"North Star: {new.statement}",
+                reason or "",
+                approved_by or "",
+            )
+    typer.echo("North Star changed." if is_change else "North Star saved.")
+
+
+@app.command()
+def confirm(root: RootOption = None) -> None:
+    """Mark an inferred North Star as confirmed."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        if direction.north_star is None:
+            raise FdeError("There is no North Star to confirm.")
+        direction.north_star.confirmed = True
+        store.save(direction)
+    typer.echo("North Star confirmed.")