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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fde-workflow-cli
-Version: 0.1.0
+Version: 0.1.1
 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

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

@@ -1,6 +1,6 @@
 [project]
 name = "fde-workflow-cli"
-version = "0.1.0"
+version = "0.1.1"
 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.1.0 → fde_workflow_cli-0.1.1}/src/fde_workflow_cli/commands/kpi.py

@@ -148,6 +148,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 +167,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 +198,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 +211,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.1.1}/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.1.1}/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.1.0 → fde_workflow_cli-0.1.1}/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.1.1}/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.1.1}/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.1.0 → fde_workflow_cli-0.1.1}/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 []