fde-workflow-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fde-workflow-cli
-Version: 0.1.0
+Version: 0.2.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
@@ -35,14 +35,20 @@ fde-workflow doctor                 # checks that everything is ready
 |---|---|
 | `init`, `detect` | Set up `.fde/`; inspect a repository's methodology and artifacts |
 | `status`, `context`, `validate` | Summaries for people and for Claude; rule checks |
+| `drift` | Specs, plans or other artifacts that no path links |
+| `report status\|close` | Markdown reports in `.fde/reports/` for the sponsor |
+| `portfolio`, `portfolio forget` | Every repository on this machine that uses the framework |
 | `project set` | The project's name, customer and sponsor |
 | `northstar set\|confirm` | The North Star |
-| `kpi add\|update\|measure` | KPIs, their recipes and measurements |
+| `kpi add\|update\|measure\|due` | KPIs, their recipes, measurements and the ones due |
 | `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 |
+| `hook session-start\|post-tool-use` | Entry points of the plugin's hooks |
 
-Run `fde-workflow <command> --help` for the options. Requires Python 3.13 or newer. Source and
+Run `fde-workflow <command> --help` for the options. `init`, `status`, `validate`, `context` and
+the SessionStart hook add the repository to the portfolio registry,
+`$XDG_CONFIG_HOME/fde-workflow/projects.json` (default `~/.config/fde-workflow/projects.json`),
+which holds repository paths only. Requires Python 3.13 or newer. Source and
 plugin: https://github.com/mjfura/fde-workflow
 

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/README.md

@@ -13,13 +13,19 @@ fde-workflow doctor                 # checks that everything is ready
 |---|---|
 | `init`, `detect` | Set up `.fde/`; inspect a repository's methodology and artifacts |
 | `status`, `context`, `validate` | Summaries for people and for Claude; rule checks |
+| `drift` | Specs, plans or other artifacts that no path links |
+| `report status\|close` | Markdown reports in `.fde/reports/` for the sponsor |
+| `portfolio`, `portfolio forget` | Every repository on this machine that uses the framework |
 | `project set` | The project's name, customer and sponsor |
 | `northstar set\|confirm` | The North Star |
-| `kpi add\|update\|measure` | KPIs, their recipes and measurements |
+| `kpi add\|update\|measure\|due` | KPIs, their recipes, measurements and the ones due |
 | `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 |
+| `hook session-start\|post-tool-use` | Entry points of the plugin's hooks |
 
-Run `fde-workflow <command> --help` for the options. Requires Python 3.13 or newer. Source and
+Run `fde-workflow <command> --help` for the options. `init`, `status`, `validate`, `context` and
+the SessionStart hook add the repository to the portfolio registry,
+`$XDG_CONFIG_HOME/fde-workflow/projects.json` (default `~/.config/fde-workflow/projects.json`),
+which holds repository paths only. Requires Python 3.13 or newer. Source and
 plugin: https://github.com/mjfura/fde-workflow

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fde-workflow-cli"
-version = "0.1.0"
+version = "0.2.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"

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

@@ -0,0 +1,107 @@
+"""`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 detect, registry, 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 parse(payload: str) -> dict[str, object]:
+    """The hook's JSON input, or an empty mapping when it is missing or malformed."""
+    try:
+        data = json.loads(payload) if payload.strip() else {}
+    except json.JSONDecodeError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def store_for(data: dict[str, object]) -> Store:
+    cwd = data.get("cwd")
+    start = Path(cwd) if isinstance(cwd, str) else Path(os.environ.get("CLAUDE_PROJECT_DIR", "."))
+    return Store(locate(start))
+
+
+def session_context(payload: str) -> str | None:
+    """The context for a new session, or None when the repository has no .fde/."""
+    store = store_for(parse(payload))
+    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)
+    registry.register(store.root)
+    return summary.context(direction, measurements, issues, brief=True)
+
+
+def post_tool_use_context(payload: str) -> str | None:
+    """A nudge when Write created an execution artifact that no path links (rule L1)."""
+    data = parse(payload)
+    tool_input = data.get("tool_input")
+    if data.get("tool_name") != "Write" or not isinstance(tool_input, dict):
+        return None
+    file_path = tool_input.get("file_path")
+    if not isinstance(file_path, str):
+        return None
+    written = Path(file_path)
+    if not written.is_absolute():
+        written = store_for(data).root / written
+    store = Store(locate(written.parent))
+    if not store.exists():
+        return None
+    if not written.resolve().is_relative_to(store.root.resolve()):
+        return None
+    relative = written.resolve().relative_to(store.root.resolve()).as_posix()
+    try:
+        direction = store.load()
+    except FdeError:
+        return None
+    if relative not in detect.drift(store.root, direction):
+        return None
+    return (
+        f"fde-workflow: {relative} is an execution artifact that no path links. Ask the user "
+        "which path it serves and link it (`fde-workflow path link <path-id> "
+        f"{relative}`), or say plainly that it is outside the direction (drift). The path skill "
+        "covers this."
+    )
+
+
+@app.command("post-tool-use")
+def post_tool_use() -> None:
+    """Nudge about an unlinked execution artifact (reads the hook's JSON on stdin)."""
+    try:
+        text = post_tool_use_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": "PostToolUse", "additionalContext": text}}
+        typer.echo(json.dumps(output))
+
+
+@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 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/commands/kpi.py

@@ -130,6 +130,18 @@ def update(
     typer.echo(f"Updated KPI {kpi_id}.")
 
 
+@app.command()
+def due(root: RootOption = None) -> None:
+    """List the KPIs that are due: last measured a full window ago or more."""
+    with user_errors():
+        store = open_store(root)
+        found = rules.due_kpis(store.load(), store.measurements())
+    if not found:
+        typer.echo("No KPI is due.")
+    for kpi, last in found:
+        typer.echo(f"{kpi.id}: last measured on {last.taken} (window {kpi.window})")
+
+
 @app.command()
 def measure(
     kpi_id: Annotated[str, typer.Argument()],
@@ -148,6 +160,10 @@ def measure(
     run: Annotated[
         bool, typer.Option("--run", help="Run a script recipe and record its output.")
     ] = False,
+    reason: Annotated[
+        str | None,
+        typer.Option(help="Why a new baseline replaces one measured with the same recipe."),
+    ] = None,
     root: RootOption = None,
 ) -> None:
     """Record a measurement; without --value or --run, show how to take it."""
@@ -163,6 +179,15 @@ def measure(
         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.")
+        previous = rules.latest_baseline(store.measurements(), kpi.id)
+        rebaseline_reason: str | None = None
+        if baseline is not None and previous is not None:
+            if previous.recipe_sha256 == fingerprint:
+                rebaseline_reason = require(
+                    reason, "--reason", "to replace a baseline measured with the same recipe"
+                )
+            else:
+                rebaseline_reason = reason or "The recipe changed after the previous baseline."
         if kpi.recipe.type is RecipeType.SCRIPT:
             if value is not None:
                 raise FdeError("Script recipes are run, not typed: use --run.")
@@ -185,7 +210,6 @@ def measure(
                 )
                 return
             source = require(source, "--source", "to record a measurement")
-        previous = rules.latest_baseline(store.measurements(), kpi.id)
         store.append_measurement(
             Measurement(
                 kpi=kpi.id,
@@ -199,6 +223,14 @@ def measure(
                 recipe_sha256=fingerprint,
             )
         )
+        if rebaseline_reason is not None:
+            record(
+                store,
+                DecisionType.BASELINE_CHANGE,
+                f"New {baseline} baseline of {kpi.id}: {number(value)}",
+                rebaseline_reason,
+                refs=[kpi.id],
+            )
     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}).")

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/commands/northstar.py

@@ -78,13 +78,30 @@ def set_(
 
 
 @app.command()
-def confirm(root: RootOption = None) -> None:
-    """Mark an inferred North Star as confirmed."""
+def confirm(
+    reason: Annotated[
+        str, typer.Option(help="Why it is confirmed.")
+    ] = "Confirmed a North Star inferred from existing work.",
+    approved_by: Annotated[str, typer.Option("--approved-by", help="Who agreed it.")] = "",
+    root: RootOption = None,
+) -> None:
+    """Mark an inferred North Star as confirmed; records a decision."""
     with user_errors():
         store = open_store(root)
         direction = store.load()
-        if direction.north_star is None:
+        north_star = direction.north_star
+        if north_star is None:
             raise FdeError("There is no North Star to confirm.")
-        direction.north_star.confirmed = True
+        if north_star.confirmed:
+            typer.echo("North Star already confirmed.")
+            return
+        north_star.confirmed = True
         store.save(direction)
+        record(
+            store,
+            DecisionType.NORTH_STAR_CHANGE,
+            f"Confirm North Star: {north_star.statement}",
+            reason,
+            approved_by,
+        )
     typer.echo("North Star confirmed.")

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/commands/path.py

@@ -245,6 +245,9 @@ def confirm(
         store = open_store(root)
         direction = store.load()
         path = find_path(direction, path_id)
+        if path.confirmed:
+            typer.echo(f"Path {path_id} already confirmed.")
+            return
         path.confirmed = True
         store.save(direction)
         record(

fde_workflow_cli-0.2.0/src/fde_workflow_cli/commands/portfolio.py

@@ -0,0 +1,72 @@
+"""`fde-workflow portfolio`: every repository on this machine that uses the framework."""
+
+import shlex
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli import registry, rules, summary
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.store import Store
+
+app = typer.Typer(
+    help="Every repository on this machine that uses the framework.",
+    invoke_without_command=True,
+)
+
+
+def project_line(root: Path) -> str:
+    store = Store(root)
+    if not store.exists():
+        command = f"fde-workflow portfolio forget {shlex.quote(str(root))}"
+        return f"{root} · no .fde/ any more: `{command}`"
+    try:
+        direction = store.load()
+        measurements = store.measurements()
+    except FdeError as error:
+        first_line = next(iter(str(error).splitlines()), "")
+        return f"{root} · .fde/ cannot be read: {first_line}"
+    issues = rules.check(direction, measurements, store.dir)
+    errors = sum(issue.level == "error" for issue in issues)
+    primary_id = direction.north_star.primary_kpi if direction.north_star else None
+    primary = direction.kpi(primary_id) if primary_id else None
+    kpi = summary.kpi_line(primary, measurements) if primary else "no primary KPI"
+    due = len(rules.due_kpis(direction, measurements))
+    stage = str(direction.stage.current) + (" (on hold)" if direction.stage.on_hold else "")
+    return (
+        f"{summary.clean(direction.project.name)} · {stage} · {kpi} · {due} due · "
+        f"{errors} error(s), {len(issues) - errors} warning(s) · {root}"
+    )
+
+
+@app.callback()
+def show(ctx: typer.Context) -> None:
+    """One line per project: stage, primary KPI, due KPIs, errors and warnings."""
+    if ctx.invoked_subcommand:
+        return
+    try:
+        projects = registry.registered()
+    except registry.RegistryError as error:
+        typer.echo(f"The portfolio registry {error}")
+        return
+    if not projects:
+        typer.echo("No projects registered yet: run `fde-workflow init` in a repository.")
+    for root in projects:
+        typer.echo(project_line(root))
+
+
+@app.command()
+def forget(
+    path: Annotated[Path, typer.Argument(help="The repository to remove from the portfolio.")],
+) -> None:
+    """Remove a repository from the portfolio (its .fde/ is not touched)."""
+    try:
+        forgotten = registry.forget(path)
+    except registry.RegistryError as error:
+        typer.echo(f"Error: the portfolio registry {error}", err=True)
+        raise typer.Exit(1) from error
+    if forgotten:
+        typer.echo(f"Forgot {path.resolve()}.")
+    else:
+        typer.echo(f"{path.resolve()} was not in the portfolio.")

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/commands/project.py

@@ -6,7 +6,7 @@ from typing import Annotated
 
 import typer
 
-from fde_workflow_cli import clock, detect, rules, summary
+from fde_workflow_cli import clock, detect, registry, rules, summary
 from fde_workflow_cli.commands.common import RootOption, open_store, user_errors
 from fde_workflow_cli.errors import FdeError
 from fde_workflow_cli.model import Artifacts, Direction, Project, StageState
@@ -47,6 +47,7 @@ def init(
                 artifacts=Artifacts(globs=globs),
             )
         )
+    registry.register(store.root)
     typer.echo(
         f"Created {store.dir} (stage discovery; artifact globs: {', '.join(globs) or 'none'})."
     )
@@ -60,11 +61,20 @@ def detect_command(root: RootOption = None) -> None:
         typer.echo(json.dumps(detect.report(store.root, direction), indent=2))
 
 
+def drift(root: RootOption = None) -> None:
+    """List execution artifacts that no path links and that are not pre-framework (rule L1)."""
+    with user_errors():
+        store = open_store(root)
+        found = detect.drift(store.root, store.load())
+    typer.echo("\n".join(found) if found else "No drift.")
+
+
 def validate(root: RootOption = None) -> None:
     """Check .fde/ against the framework's rules; exit 1 when a rule is broken."""
     with user_errors():
         store = open_store(root)
         issues = rules.check(store.load(), store.measurements(), store.dir)
+    registry.register(store.root)
     for issue in issues:
         typer.echo(f"{'✗' if issue.level == 'error' else '!'} [{issue.rule}] {issue.message}")
     errors = sum(issue.level == "error" for issue in issues)
@@ -82,6 +92,7 @@ def status(root: RootOption = None) -> None:
         direction = store.load()
         measurements = store.measurements()
         issues = rules.check(direction, measurements, store.dir)
+    registry.register(store.root)
     typer.echo(summary.render(direction, measurements, issues))
 
 
@@ -95,6 +106,7 @@ def context(
         direction = store.load()
         measurements = store.measurements()
         issues = rules.check(direction, measurements, store.dir)
+    registry.register(store.root)
     typer.echo(summary.context(direction, measurements, issues, brief=brief))
 
 

fde_workflow_cli-0.2.0/src/fde_workflow_cli/commands/report.py

@@ -0,0 +1,65 @@
+"""`fde-workflow report`: write a status or closing report to `.fde/reports/`."""
+
+import datetime as dt
+import re
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli import clock, detect, report, rules
+from fde_workflow_cli.commands.common import RootOption, open_store, parse_date, user_errors
+from fde_workflow_cli.report import ReportKind
+
+STATUS_FILE = re.compile(r"^(\d{4}-\d{2}-\d{2})-status(?:-\d+)?\.md$")
+
+
+def previous_status_date(reports: Path, today: dt.date) -> dt.date | None:
+    """Date of the latest status report before today: regenerating one keeps its period."""
+    dates = [
+        date
+        for path in reports.glob("*.md")
+        if (match := STATUS_FILE.match(path.name))
+        and (date := dt.date.fromisoformat(match.group(1))) < today
+    ]
+    return max(dates, default=None)
+
+
+def free_path(reports: Path, stem: str) -> Path:
+    path, number = reports / f"{stem}.md", 2
+    while path.exists():
+        path, number = reports / f"{stem}-{number}.md", number + 1
+    return path
+
+
+def report_command(
+    kind: Annotated[ReportKind, typer.Argument(help="status (for the sponsor) or close.")],
+    since: Annotated[
+        str | None,
+        typer.Option(help="Decisions from this date (status default: the previous report)."),
+    ] = None,
+    root: RootOption = None,
+) -> None:
+    """Write a Markdown report to .fde/reports/ and print its path."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        measurements = store.measurements()
+        reports = store.dir / "reports"
+        reports.mkdir(exist_ok=True)
+        start = parse_date(since, "--since") if since else None
+        if start is None and kind is ReportKind.STATUS:
+            start = previous_status_date(reports, clock.today())
+        text = report.render(
+            kind,
+            direction,
+            measurements,
+            store.decisions(),
+            rules.check(direction, measurements, store.dir),
+            detect.drift(store.root, direction),
+            start,
+            rules.stale_baselines(direction, measurements, store.dir),
+        )
+        path = free_path(reports, f"{clock.today()}-{kind}")
+        path.write_text(text, encoding="utf-8")
+    typer.echo(str(path))

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/commands/stage.py

@@ -65,14 +65,25 @@ def set_(
 
 
 @app.command()
-def confirm(root: RootOption = None) -> None:
-    """Mark an inferred stage as confirmed."""
+def confirm(
+    reason: Annotated[
+        str, typer.Option(help="Why it is confirmed.")
+    ] = "Confirmed a stage inferred from evidence.",
+    approved_by: Annotated[str, typer.Option("--approved-by", help="Who agreed it.")] = "",
+    root: RootOption = None,
+) -> None:
+    """Mark an inferred stage as confirmed; records a decision."""
     with user_errors():
         store = open_store(root)
         direction = store.load()
-        direction.stage.confirmed = True
+        stage = direction.stage
+        if stage.confirmed:
+            typer.echo(f"Stage {stage.current} already confirmed.")
+            return
+        stage.confirmed = True
         store.save(direction)
-    typer.echo(f"Stage {direction.stage.current} confirmed.")
+        record(store, DecisionType.STAGE_SET, f"Confirm stage {stage.current}", reason, approved_by)
+    typer.echo(f"Stage {stage.current} confirmed.")
 
 
 @app.command()

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/detect.py

@@ -102,6 +102,15 @@ def linked_to(direction: Direction | None, relative: str) -> str | None:
     return None
 
 
+def drift(root: Path, direction: Direction) -> list[str]:
+    """L1: artifacts matching the globs that no path links and that are not pre-framework."""
+    return [
+        relative
+        for relative in artifact_files(root, direction.artifacts.globs)
+        if linked_to(direction, relative) is None
+    ]
+
+
 def report(root: Path, direction: Direction | None) -> dict[str, object]:
     methodology = detect_methodology(root)
     globs = direction.artifacts.globs if direction else PRESET_GLOBS[methodology]

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/doctor.py

@@ -32,9 +32,10 @@ def check_direction() -> CheckResult:
         return CheckResult(ok=True, message="No .fde/ here yet: the adopt skill sets one up")
     try:
         store.load()
+        store.measurements()
+        store.decisions()
     except FdeError as error:
-        first_line = str(error).splitlines()[0]
-        return CheckResult(ok=False, message=f".fde/ cannot be read: {first_line}")
+        return CheckResult(ok=False, message=f".fde/ cannot be read: {error}")
     return CheckResult(ok=True, message=f".fde/ uses schema {SCHEMA_VERSION}: {store.dir}")
 
 

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/main.py

@@ -6,7 +6,17 @@ from typing import Annotated
 import typer
 
 from fde_workflow_cli import doctor as checks
-from fde_workflow_cli.commands import decision, hook, kpi, northstar, path, project, stage
+from fde_workflow_cli.commands import (
+    decision,
+    hook,
+    kpi,
+    northstar,
+    path,
+    portfolio,
+    project,
+    report,
+    stage,
+)
 
 COMMAND = "fde-workflow"
 DIST_NAME = "fde-workflow-cli"
@@ -50,9 +60,11 @@ def doctor() -> None:
 
 app.command()(project.init)
 app.command("detect")(project.detect_command)
+app.command()(project.drift)
 app.command()(project.validate)
 app.command()(project.status)
 app.command()(project.context)
+app.command("report")(report.report_command)
 app.add_typer(project.app, name="project")
 app.add_typer(kpi.app, name="kpi")
 app.add_typer(northstar.app, name="northstar")
@@ -60,3 +72,4 @@ app.add_typer(path.app, name="path")
 app.add_typer(stage.app, name="stage")
 app.add_typer(decision.app, name="decision")
 app.add_typer(hook.app, name="hook")
+app.add_typer(portfolio.app, name="portfolio")

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/model.py

@@ -83,6 +83,7 @@ class DecisionType(StrEnum):
     PATH_DISCARD = "path-discard"
     STAGE_GATE = "stage-gate"
     STAGE_SET = "stage-set"
+    BASELINE_CHANGE = "baseline-change"
     SCOPE_CHANGE = "scope-change"
     OTHER = "other"
 

fde_workflow_cli-0.2.0/src/fde_workflow_cli/registry.py

@@ -0,0 +1,70 @@
+"""The portfolio registry: the repositories on this machine that use the framework.
+
+It lives outside every repository, in $XDG_CONFIG_HOME/fde-workflow/projects.json, and holds
+paths only. Registering must never make a command fail, so write errors are ignored.
+"""
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+
+class RegistryError(Exception):
+    """The registry file exists but cannot be read; it is never overwritten then."""
+
+
+def registry_file() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "fde-workflow" / "projects.json"
+
+
+def registered() -> list[Path]:
+    """The registered roots; raises RegistryError when the file exists but is unreadable."""
+    path = registry_file()
+    if not path.exists():
+        return []
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as error:
+        raise RegistryError(f"{path} cannot be read ({error}): fix or delete it.") from error
+    projects = data.get("projects") if isinstance(data, dict) else None
+    if not isinstance(projects, list):
+        raise RegistryError(f"{path} cannot be read (no projects list): fix or delete it.")
+    return [Path(item) for item in projects if isinstance(item, str)]
+
+
+def _write(projects: list[Path]) -> None:
+    path = registry_file()
+    text = json.dumps({"projects": [str(project) for project in projects]}, indent=2) + "\n"
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            "w", encoding="utf-8", dir=path.parent, suffix=".tmp", delete=False
+        ) as handle:
+            handle.write(text)
+    except OSError:
+        return
+    try:
+        os.replace(handle.name, path)
+    except OSError:
+        Path(handle.name).unlink(missing_ok=True)
+
+
+def register(root: Path) -> None:
+    root = root.resolve()
+    try:
+        projects = registered()
+    except RegistryError:
+        return
+    if root not in projects:
+        _write([*projects, root])
+
+
+def forget(root: Path) -> bool:
+    root = root.resolve()
+    projects = registered()
+    if root not in projects:
+        return False
+    _write([project for project in projects if project != root])
+    return True

fde_workflow_cli-0.2.0/src/fde_workflow_cli/report.py

@@ -0,0 +1,176 @@
+"""Markdown reports of a direction: a status report for the sponsor and the closing value report."""
+
+import datetime as dt
+from enum import StrEnum
+
+from fde_workflow_cli import clock
+from fde_workflow_cli.model import BaselineType, Better, Decision, Direction, Kpi, Measurement
+from fde_workflow_cli.rules import Issue, latest_baseline
+from fde_workflow_cli.summary import number
+
+LIMITATION = (
+    "Before/after comparisons do not prove causation: the external factors recorded with each "
+    "measurement are listed above."
+)
+
+
+class ReportKind(StrEnum):
+    STATUS = "status"
+    CLOSE = "close"
+
+
+TITLES = {ReportKind.STATUS: "Status report", ReportKind.CLOSE: "Closing report"}
+
+
+def cell(text: str) -> str:
+    """Whole text on one line, safe inside a Markdown table cell or list item."""
+    line = "".join(char for char in " ".join(text.split()) if char.isprintable())
+    return line.replace("|", "\\|")
+
+
+def _window(measurement: Measurement) -> str:
+    return f"{measurement.window_start} to {measurement.window_end}"
+
+
+def _latest(measurements: list[Measurement], kpi_id: str) -> Measurement | None:
+    return next((m for m in reversed(measurements) if m.kpi == kpi_id and m.baseline is None), None)
+
+
+def _kpi_row(kpi: Kpi, measurements: list[Measurement], stale: bool) -> str:
+    unit = f" {cell(kpi.unit)}" if kpi.unit else ""
+    baseline = latest_baseline(measurements, kpi.id)
+    latest = _latest(measurements, kpi.id)
+    sign = "≤" if kpi.direction is Better.DECREASE else "≥"
+    columns = [
+        kpi.id,
+        str(kpi.kind),
+        f"{number(baseline.value)}{unit} ({baseline.baseline}, {_window(baseline)})"
+        if baseline
+        else "—",
+        f"{number(latest.value)}{unit} ({_window(latest)})" if latest else "—",
+        f"{sign} {number(kpi.target)}{unit}",
+    ]
+    if stale:
+        columns.append("not comparable: recipe changed")
+    elif baseline and latest:
+        delta = latest.value - baseline.value
+        change = f"{delta:+g}{unit}"
+        if baseline.value:
+            change += f" ({delta / abs(baseline.value):+.1%})"
+        columns.append(change)
+    else:
+        columns.append("—")
+    if latest and not stale:
+        met = (
+            latest.value <= kpi.target
+            if kpi.direction is Better.DECREASE
+            else latest.value >= kpi.target
+        )
+        columns.append("yes" if met else "no")
+    else:
+        columns.append("—")
+    return "| " + " | ".join(columns) + " |"
+
+
+def render(
+    kind: ReportKind,
+    direction: Direction,
+    measurements: list[Measurement],
+    decisions: list[Decision],
+    issues: list[Issue],
+    drift: list[str],
+    since: dt.date | None,
+    stale: set[str] | None = None,
+) -> str:
+    """The report; `stale` names KPIs whose recipe changed after their baseline (rule K4)."""
+    project = direction.project
+    lines = [f"# {TITLES[kind]}: {cell(project.name)} — {clock.today()}", ""]
+    if project.customer:
+        lines.append(f"- Customer: {cell(project.customer)}")
+    if project.sponsor:
+        lines.append(f"- Sponsor: {cell(project.sponsor)}")
+
+    lines += ["", "## North Star", ""]
+    north_star = direction.north_star
+    if north_star is None:
+        lines.append("Not defined yet.")
+    else:
+        inferred = "" if north_star.confirmed else " (inferred)"
+        lines.append(f"Statement: {cell(north_star.statement)}{inferred}")
+        lines.append("")
+        if north_star.beneficiary:
+            lines.append(f"- Beneficiary: {cell(north_star.beneficiary)}")
+        if north_star.problem:
+            lines.append(f"- Problem: {cell(north_star.problem)}")
+        lines += [f"- Non-goal: {cell(goal)}" for goal in north_star.non_goals]
+        lines.append(f"- Primary KPI: {north_star.primary_kpi or 'not set'}")
+
+    stage = direction.stage
+    lines += ["", "## Stage", "", f"{stage.current} since {stage.entered}"]
+    if stage.outcome:
+        lines[-1] += f" ({stage.outcome})"
+    if stage.on_hold:
+        lines[-1] += " (on hold)"
+    if stage.gate_criteria:
+        lines += ["", "Gate criteria:"] + [f"- {cell(item)}" for item in stage.gate_criteria]
+
+    lines += ["", "## KPIs", ""]
+    if direction.kpis:
+        lines += [
+            "| KPI | Kind | Baseline | Latest | Target | Change | Target met |",
+            "|---|---|---|---|---|---|---|",
+        ]
+        lines += [_kpi_row(kpi, measurements, kpi.id in (stale or set())) for kpi in direction.kpis]
+        factors = [m for m in measurements if m.external_factors]
+        if factors:
+            lines += ["", "External factors:"]
+            lines += [f"- {m.kpi}, {m.taken}: {cell(m.external_factors)}" for m in factors]
+    else:
+        lines.append("None defined yet.")
+
+    lines += ["", "## Paths", ""]
+    if direction.paths:
+        lines += [
+            "| Path | Status | Hypothesis | Expects | Links | Learning |",
+            "|---|---|---|---|---|---|",
+        ]
+        for path in direction.paths:
+            expects = ", ".join(f"{k} → {number(v)}" for k, v in path.expects.items())
+            links = "<br>".join(cell(link) for link in path.links) or "—"
+            lines.append(
+                f"| {path.id} | {path.status} | {cell(path.hypothesis)} | {expects} "
+                f"| {links} | {cell(path.learning or '')} |"
+            )
+    else:
+        lines.append("None yet.")
+
+    lines += ["", "## Drift", ""]
+    lines += [f"- {item}" for item in drift] if drift else ["None."]
+    if direction.artifacts.pre_framework:
+        lines += ["", "## Before the framework", ""]
+        lines += [f"- {cell(item)}" for item in direction.artifacts.pre_framework]
+
+    shown = [d for d in decisions if since is None or d.date >= since]
+    lines += ["", f"## Decisions since {since}" if since else "## Decisions", ""]
+    for item in shown:
+        approved = f" (approved by {cell(item.approved_by)})" if item.approved_by else ""
+        lines.append(
+            f"- {item.date} · {item.type} · {cell(item.summary)} — {cell(item.reason)}{approved}"
+        )
+    if not shown:
+        lines.append("None.")
+
+    if issues:
+        lines += ["", "## Open issues", ""]
+        lines += [f"- [{issue.rule}] {cell(issue.message)}" for issue in issues]
+
+    lines += ["", "## Notes", ""]
+    for kpi in direction.kpis:
+        baseline = latest_baseline(measurements, kpi.id)
+        if baseline and baseline.baseline is BaselineType.LATE:
+            lines.append(
+                f"- {kpi.id}: the baseline is late (measured on {baseline.taken}, after the work "
+                "started), so impact achieved before it is not captured."
+            )
+    lines.append(f"- {LIMITATION}")
+    return "\n".join(lines) + "\n"

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/rules.py

@@ -5,11 +5,12 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal
 
-from fde_workflow_cli import recipes
+from fde_workflow_cli import clock, recipes
 from fde_workflow_cli.errors import FdeError
 from fde_workflow_cli.model import (
     Direction,
     DirectionPath,
+    Kpi,
     KpiKind,
     Measurement,
     PathStatus,
@@ -33,6 +34,14 @@ def check(direction: Direction, measurements: list[Measurement], fde_dir: Path)
         *_kpis(direction, measurements, fde_dir),
         *_paths(direction, measurements),
         *_stage(direction, measurements),
+        *(
+            Issue(
+                "warning",
+                "K6",
+                f"KPI {kpi.id} is due: last measured on {last.taken} (window {kpi.window}).",
+            )
+            for kpi, last in due_kpis(direction, measurements)
+        ),
     ]
     return sorted(issues, key=lambda issue: issue.level != "error")
 
@@ -43,6 +52,41 @@ def latest_baseline(measurements: list[Measurement], kpi_id: str) -> Measurement
     return baselines[-1] if baselines else None
 
 
+def stale_baselines(
+    direction: Direction, measurements: list[Measurement], fde_dir: Path
+) -> set[str]:
+    """K4: KPIs whose recipe changed after their latest baseline."""
+    stale = set()
+    for kpi in direction.kpis:
+        baseline = latest_baseline(measurements, kpi.id)
+        try:
+            current = recipes.fingerprint(fde_dir, kpi.recipe)
+        except FdeError:
+            continue
+        if baseline is not None and current is not None and baseline.recipe_sha256 != current:
+            stale.add(kpi.id)
+    return stale
+
+
+def due_kpis(
+    direction: Direction, measurements: list[Measurement]
+) -> list[tuple[Kpi, Measurement]]:
+    """K6: KPIs with a baseline whose last measurement was taken a full window ago or more."""
+    if direction.stage.current is StageName.CLOSED:
+        return []
+    today = clock.today()
+    due = []
+    for kpi in direction.kpis:
+        taken = [m for m in measurements if m.kpi == kpi.id]
+        if latest_baseline(taken, kpi.id) is None:
+            continue
+        last = max(taken, key=lambda m: m.taken)
+        start, _ = kpi.window_ending(today)
+        if last.taken < start:
+            due.append((kpi, last))
+    return due
+
+
 def has_evidence(path: DirectionPath, measurements: list[Measurement]) -> bool:
     """P2: a non-baseline measurement of a targeted KPI whose whole window follows activation."""
     activated = path.activated

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/store.py

@@ -1,5 +1,6 @@
 """Read and write `.fde/`. direction.yaml is validated, rules included, before every write."""
 
+import hashlib
 import os
 import tempfile
 from pathlib import Path
@@ -53,6 +54,7 @@ class Store:
         self.root = root
         self.dir = root / FDE_DIR
         self.direction_file = self.dir / DIRECTION_FILE
+        self._loaded_digest: str | None = None
 
     def exists(self) -> bool:
         return self.direction_file.is_file()
@@ -71,17 +73,29 @@ class Store:
             raise FdeError(
                 f"No .fde/ in {self.root}: run `fde-workflow init` (or the adopt skill) first."
             )
+        text = read_text(self.direction_file)
+        self._loaded_digest = _digest(text)
         try:
-            data = yaml.safe_load(read_text(self.direction_file))
+            data = yaml.safe_load(text)
         except yaml.YAMLError as error:
             raise FdeError(f"{self.direction_file} is not valid YAML: {error}") from error
         if not isinstance(data, dict):
             raise FdeError(f"{self.direction_file} must contain a YAML mapping.")
         version = data.get("schema_version")
+        if version is None:
+            raise FdeError(
+                f"{self.direction_file} has no schema_version: it is not an fde-workflow "
+                "direction file, or it was damaged."
+            )
+        if isinstance(version, int) and version > SCHEMA_VERSION:
+            raise FdeError(
+                f"{self.direction_file} has schema_version {version}; this fde-workflow "
+                f"supports {SCHEMA_VERSION}. Upgrade it: uv tool upgrade fde-workflow-cli."
+            )
         if version != SCHEMA_VERSION:
             raise FdeError(
                 f"{self.direction_file} has schema_version {version!r}; this fde-workflow "
-                f"supports {SCHEMA_VERSION}. Upgrade it: uv tool upgrade fde-workflow-cli."
+                f"reads only schema_version {SCHEMA_VERSION}."
             )
         try:
             return Direction.model_validate(data)
@@ -103,12 +117,27 @@ class Store:
         if errors:
             listed = "\n".join(f"  [{issue.rule}] {issue.message}" for issue in errors)
             raise FdeError(f"Not saved: the change breaks the framework's rules:\n{listed}")
+        if (
+            self._loaded_digest is not None
+            and self.direction_file.is_file()
+            and _digest(read_text(self.direction_file)) != self._loaded_digest
+        ):
+            raise FdeError(
+                f"{self.direction_file} changed since it was read (another fde-workflow "
+                "command?): run the command again."
+            )
         text = yaml.safe_dump(data, sort_keys=False, allow_unicode=True)
         with tempfile.NamedTemporaryFile(
             "w", encoding="utf-8", dir=self.dir, suffix=".tmp", delete=False
         ) as handle:
             handle.write(text)
-        os.replace(handle.name, self.direction_file)
+        try:
+            os.chmod(handle.name, 0o666 & ~_umask())
+            os.replace(handle.name, self.direction_file)
+        except OSError as error:
+            Path(handle.name).unlink(missing_ok=True)
+            raise FdeError(f"Cannot write {self.direction_file}: {error.strerror}.") from error
+        self._loaded_digest = _digest(text)
 
     def measurements(self) -> list[Measurement]:
         return _read_jsonl(self.dir / MEASUREMENTS_FILE, Measurement)
@@ -123,6 +152,16 @@ class Store:
         _append_jsonl(self.dir / DECISIONS_FILE, decision)
 
 
+def _digest(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _umask() -> int:
+    mask = os.umask(0)
+    os.umask(mask)
+    return mask
+
+
 def _read_jsonl[M: BaseModel](path: Path, model: type[M]) -> list[M]:
     if not path.is_file():
         return []

{fde_workflow_cli-0.1.0 → fde_workflow_cli-0.2.0}/src/fde_workflow_cli/summary.py

@@ -86,6 +86,9 @@ def render(
         expects = ", ".join(f"{kpi_id} → {number(v)}" for kpi_id, v in path.expects.items())
         lines.append(f"  {path.id} [{path.status}]{inferred}: {clean(path.hypothesis)} ({expects})")
 
+    if brief:
+        # Due KPIs stay visible: they are the reminder that replaces scheduled measurements.
+        issues = sorted(issues, key=lambda issue: (issue.level != "error", issue.rule != "K6"))
     shown = issues[:BRIEF_ISSUES] if brief else issues
     if shown:
         lines.append("Issues:")

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

@@ -1,52 +0,0 @@
-"""`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))