engineering-process 0.3.0__tar.gz → 0.4.0__tar.gz

{engineering_process-0.3.0/engineering_process.egg-info → engineering_process-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engineering-process
-Version: 0.3.0
+Version: 0.4.0
 Summary: Agent-neutral end-to-end engineering lifecycle and deterministic process CLI
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/phuongnse/engineering-process
@@ -85,6 +85,9 @@ distribution: the POSIX backend owns a new process session/group and the Windows
 backend owns a kill-on-close Job Object. Consumer manifests, evidence, and exit codes
 do not branch by operating system. If an outer Windows Job applies incompatible
 nesting or UI limits, target creation fails closed instead of running uncontained.
+After a command root exits, both backends allow at most 250 milliseconds for child
+accounting to drain naturally. A process still present after that bound is terminated
+and makes the command fail; commands with no remaining child return immediately.
 
 This task boundary intentionally separates finite commands from services and
 interactive protocols. `processctl exec`, requirement probes, setup command actions,

{engineering_process-0.3.0 → engineering_process-0.4.0}/PRODUCTION_STANDARD.md

@@ -59,6 +59,24 @@ its schema-2 profile reports. The remote artifact id and service-computed digest
 preserved with review evidence. These reports supplement the public N-1 lifecycle
 authority; code under verification never promotes itself to lifecycle authority.
 
+## Failure to invariant
+
+A validated command, gate, release, adoption, or external-integration failure must
+preserve exact bounded evidence and classify its owner before corrective mutation as
+project-local, shared-process, operations-or-external, or missing product or
+authorization input. Dependent candidates stay blocked. Shared defects are corrected
+in the producer rather than wrapped or duplicated by consumers; project behavior
+remains project-owned unless a portable class is proven.
+
+Every correction proves valid behavior and the corresponding fail-closed class at the
+lowest reliable owner boundary. Shared corrections additionally require producer
+profiles and reproduction at affected consumer boundaries before release. A transient
+operations/external recovery is allowed only with unchanged source and configuration;
+attempts are bounded, idempotent, diagnostic-preserving, and stop on deterministic
+failure. Source, branch, version, credentials, and controls are never changed merely
+to cause another attempt. Independent review treats violation of these ownership and
+evidence boundaries as completion-blocking.
+
 ## Resource and generated-state policy
 
 Every operation over repository-controlled or remote input has explicit limits for

{engineering_process-0.3.0 → engineering_process-0.4.0}/README.md

@@ -50,6 +50,9 @@ distribution: the POSIX backend owns a new process session/group and the Windows
 backend owns a kill-on-close Job Object. Consumer manifests, evidence, and exit codes
 do not branch by operating system. If an outer Windows Job applies incompatible
 nesting or UI limits, target creation fails closed instead of running uncontained.
+After a command root exits, both backends allow at most 250 milliseconds for child
+accounting to drain naturally. A process still present after that bound is terminated
+and makes the command fail; commands with no remaining child return immediately.
 
 This task boundary intentionally separates finite commands from services and
 interactive protocols. `processctl exec`, requirement probes, setup command actions,

{engineering_process-0.3.0 → engineering_process-0.4.0}/engineering_process/__init__.py

@@ -1,3 +1,3 @@
 """Agent-neutral engineering process."""
 
-VERSION = "0.3.0"
+VERSION = "0.4.0"

{engineering_process-0.3.0 → engineering_process-0.4.0}/engineering_process/_supervisor_posix.py

@@ -9,7 +9,7 @@ import subprocess
 import time
 from typing import Mapping
 
-from .supervision import CleanupOutcome
+from .supervision import CleanupOutcome, NATURAL_DRAIN_GRACE_MILLISECONDS
 
 
 def _process_group_exists(process_group: int) -> bool:
@@ -156,7 +156,20 @@ class PosixProcessSupervisor:
         grace_seconds: float,
     ) -> CleanupOutcome:
         # The group id remains valid while any descendant from the owned session is
-        # alive, even after the original process has exited.
+        # alive, even after the original process has exited. Give descendants that
+        # were synchronously asked to stop one short bounded interval to disappear
+        # naturally before classifying them as abandoned background work.
+        if not _process_group_exists(process.pid):
+            return CleanupOutcome(bounded=True)
+        natural_drain_seconds = min(
+            grace_seconds,
+            NATURAL_DRAIN_GRACE_MILLISECONDS / 1000,
+        )
+        if natural_drain_seconds > 0 and _wait_for_process_group(
+            process.pid,
+            natural_drain_seconds,
+        ):
+            return CleanupOutcome(bounded=True)
         return _terminate_group(process.pid, grace_seconds)
 
 

{engineering_process-0.3.0 → engineering_process-0.4.0}/engineering_process/supervision.py

@@ -14,6 +14,9 @@ import subprocess
 from typing import Mapping, Protocol
 
 
+NATURAL_DRAIN_GRACE_MILLISECONDS = 250
+
+
 @dataclass(frozen=True)
 class CleanupOutcome:
     """Result of a bounded process-tree cleanup operation."""

{engineering_process-0.3.0 → engineering_process-0.4.0/engineering_process.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engineering-process
-Version: 0.3.0
+Version: 0.4.0
 Summary: Agent-neutral end-to-end engineering lifecycle and deterministic process CLI
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/phuongnse/engineering-process
@@ -85,6 +85,9 @@ distribution: the POSIX backend owns a new process session/group and the Windows
 backend owns a kill-on-close Job Object. Consumer manifests, evidence, and exit codes
 do not branch by operating system. If an outer Windows Job applies incompatible
 nesting or UI limits, target creation fails closed instead of running uncontained.
+After a command root exits, both backends allow at most 250 milliseconds for child
+accounting to drain naturally. A process still present after that bound is terminated
+and makes the command fail; commands with no remaining child return immediately.
 
 This task boundary intentionally separates finite commands from services and
 interactive protocols. `processctl exec`, requirement probes, setup command actions,

{engineering_process-0.3.0 → engineering_process-0.4.0}/process_assets/skills/evolve-process/SKILL.md

@@ -14,18 +14,26 @@ incident history into permanent ceremony.
 
 1. Start from a reproducer, escaped defect, false positive, review finding, or measured
    workflow cost. Do not generalize from speculation alone.
-2. Classify the evidence as a project-local defect, reusable process rule,
-   deterministic invariant, portability gap, or obsolete rule.
-3. Fix local behavior in the project owner. Change shared skills only for portable
+2. Apply the run-change failure-to-invariant protocol. Classify the owning boundary as
+   project-local, shared-process, operations-or-external, or missing product or
+   authorization input before corrective mutation; then classify the reusable class
+   as a process rule, deterministic invariant, portability gap, or obsolete rule.
+3. Fix local behavior in the project owner. When the defect belongs to shared process
+   semantics, keep the consumer candidate blocked and remove any provisional consumer
+   wrapper or duplicate implementation. Change shared skills only for portable
    semantics. Add CLI or schema enforcement only when deterministic.
-4. Add a regression case at the lowest reliable boundary. For skill behavior, run a
-   realistic forward test without providing the expected answer.
+4. Add regression cases at the lowest reliable owner boundary for both valid behavior
+   and the fail-closed class. A shared fix also requires producer profiles and a real
+   affected-consumer reproduction before release authorization. For skill behavior,
+   run a realistic forward test without providing the expected answer.
 5. Validate backward compatibility, version impact, consumer locks, and migration
    needs. Remove superseded guidance instead of preserving duplicate paths.
    Check the full `production-v1` boundary and derive every release identity surface
    from the release contract so a local fix cannot create a new cross-surface drift.
 6. Measure whether the change improves task fidelity without disproportionate
    workflow cost.
+7. For an operations or external transient, require bounded idempotent recovery with
+   retained per-attempt diagnostics. Never mutate source or version merely to retry.
 
 ## Hard gates
 

{engineering_process-0.3.0 → engineering_process-0.4.0}/process_assets/skills/review-change/SKILL.md

@@ -33,6 +33,9 @@ specific checkpoint without changing the reviewed source.
    Resolved, deferred, and false-positive findings require resolution evidence.
    Deferred remains unresolved and completion-blocking unless a future process
    contract introduces an explicit owner-approved exception.
+   Treat owner mismatch, consumer workaround for a shared defect, evidence-free rerun,
+   missing valid/fail-closed regression proof, or missing affected-consumer proof for
+   a shared correction as required completion-blocking findings.
 5. Request changes when any required finding remains open or deferred. Approve only
    when required outcomes and evidence are complete for the reviewed checkpoint.
 6. Validate the report with processctl contract validate --kind review, then submit

{engineering_process-0.3.0 → engineering_process-0.4.0}/process_assets/skills/run-change/SKILL.md

@@ -31,10 +31,14 @@ semantics shared by every project.
 3. Apply the nearest AGENTS.md and domain skill inside each phase. Project policy may
    add stronger gates but cannot remove lifecycle phases, baseline profiles,
    independent review, evidence freshness, or finding closure.
-4. After a valid finding, preserve the reviewed checkpoint, begin the next
+4. When a command, gate, release, adoption, or external integration fails, apply the
+   failure-to-invariant protocol in the required execution reference before any
+   corrective mutation. Keep dependent candidates blocked until the owning boundary
+   and required proof are explicit.
+5. After a valid finding, preserve the reviewed checkpoint, begin the next
    implementation cycle, resolve the finding, and repeat every invalidated profile
    and independent review.
-5. Report the processctl phase, cycle, current evidence, blockers, and next owner.
+6. Report the processctl phase, cycle, current evidence, blockers, and next owner.
    Never call a task complete from prose alone.
 
 ## Hard gates

{engineering_process-0.3.0 → engineering_process-0.4.0}/process_assets/skills/run-change/references/execution.md

@@ -54,6 +54,37 @@ When progress depends on user-controlled or external state:
 5. Report `Blocker`, `Evidence`, `Boundary`, `User action or decision needed`, and
    `Safe next step after confirmation`.
 
+## Failure-to-invariant protocol
+
+Apply this protocol before corrective mutation whenever a command, gate, release,
+adoption, or external integration produces a validated failure:
+
+1. Preserve the smallest reliable reproducer, exact command/event, immutable source
+   identity, environment, exit status, bounded output, and available service evidence.
+   Do not use an evidence-free rerun as diagnosis.
+2. Classify the owning boundary as `project-local`, `shared-process`,
+   `operations-or-external`, or `missing-product-or-authorization-input`. State the
+   evidence that excludes the other boundaries before selecting a fix.
+3. Keep every dependent candidate blocked. A shared-process defect must be fixed in
+   the shared producer; do not add a consumer-owned wrapper, duplicate algorithm,
+   alternate authority, relaxed control, or environment substitution to keep moving.
+   A project-local behavior remains in the project owner and must not be promoted to
+   portable core without evidence of a reusable class.
+4. Add regression evidence at the lowest reliable owner boundary for both the valid
+   behavior and the corresponding persistent, invalid, timeout, or interruption case
+   that must remain fail closed.
+5. For a shared correction, require producer profiles and a reproduction at every
+   affected consumer boundary before release authorization. Consumer proof supplements
+   producer evidence; neither substitutes for the other.
+6. Treat operations or external propagation as transient only when source and
+   configuration are already proven unchanged. Recovery must be bounded, idempotent,
+   preserve per-attempt diagnostics, and stop on a deterministic failure. Do not
+   change source, branch, version, credentials, or controls merely to cause another
+   attempt.
+7. Reopen or create the owning change lifecycle when scope moves across a boundary,
+   then repeat invalidated verification and independent review on one exact final
+   checkpoint. Record the reusable invariant, not just the incident chronology.
+
 ## Independent review
 
 Review begins only after all baseline and change-required profiles pass on one clean

{engineering_process-0.3.0 → engineering_process-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "engineering-process"
-version = "0.3.0"
+version = "0.4.0"
 description = "Agent-neutral end-to-end engineering lifecycle and deterministic process CLI"
 readme = "README.md"
 license = "MIT"

engineering_process-0.4.0/release.json

@@ -0,0 +1,55 @@
+{
+  "schemaVersion": 3,
+  "previousVersion": "0.3.0",
+  "version": "0.4.0",
+  "classification": "minor",
+  "compatibility": "backward-compatible",
+  "schemaImpact": "unchanged",
+  "migration": null,
+  "identity": {
+    "package": "engineering-process",
+    "distribution": "engineering_process",
+    "tag": "v0.4.0",
+    "releaseName": "v0.4.0",
+    "runtimeVersion": {
+      "path": "engineering_process/__init__.py",
+      "variable": "VERSION"
+    },
+    "artifacts": [
+      "engineering_process-0.4.0-py3-none-any.whl",
+      "engineering_process-0.4.0.tar.gz"
+    ],
+    "receiptAsset": "engineering-process-v0.4.0-evidence.json",
+    "authorizationAsset": null
+  },
+  "provenance": {
+    "mode": "governed",
+    "statement": "The public N-1 lifecycle receipt and reviewed Release PR authorize this release.",
+    "lifecycleReceipt": {
+      "asset": "engineering-process-v0.4.0-evidence.json",
+      "project": "engineering-process",
+      "changeId": "release-0-4-0",
+      "cycle": 1
+    }
+  },
+  "changes": [
+    {
+      "id": "failure-to-invariant",
+      "type": "capability",
+      "surfaces": [
+        "governance",
+        "skills"
+      ],
+      "rationale": "Require future failures to preserve evidence, classify the correct owner, repair a reusable invariant, prove valid and fail-closed behavior, and obtain affected-consumer proof before shared release."
+    },
+    {
+      "id": "natural-descendant-drain",
+      "type": "fix",
+      "surfaces": [
+        "execution",
+        "supervision"
+      ],
+      "rationale": "Allow short, bounded child-process shutdown to drain naturally on POSIX just as it already does under the Windows Job Object, while persistent descendants remain terminated and completion-blocking."
+    }
+  ]
+}

{engineering_process-0.3.0 → engineering_process-0.4.0}/tests/test_environment.py

@@ -101,6 +101,40 @@ def project_document(*, setup: bool = True, dependency: bool = False):
 
 
 class EnvironmentTests(unittest.TestCase):
+    @unittest.skipUnless(os.name == "posix", "POSIX process-group regression")
+    def test_successful_command_allows_short_natural_descendant_drain(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            child_started = root / "child.started"
+            child_code = (
+                "from pathlib import Path; import sys, time; "
+                "Path(sys.argv[1]).write_text('started'); time.sleep(0.08)"
+            )
+            parent_code = (
+                "import subprocess, sys, time; from pathlib import Path; "
+                "subprocess.Popen([sys.executable, '-c', sys.argv[1], sys.argv[2]]); "
+                "marker=Path(sys.argv[2]); deadline=time.monotonic()+5; "
+                "\nwhile not marker.exists() and time.monotonic() < deadline: time.sleep(0.01)\n"
+                "raise SystemExit(0 if marker.exists() else 2)"
+            )
+
+            report = execute_command(
+                root,
+                identifier="natural-drain",
+                run=(
+                    sys.executable,
+                    "-c",
+                    parent_code,
+                    child_code,
+                    str(child_started),
+                ),
+                timeout_seconds=10,
+                working_directory=".",
+            )
+
+        self.assertEqual("passed", report["status"])
+        self.assertEqual(0, report["exitCode"])
+
     def test_managed_command_binding_preserves_logical_evidence_without_a_shell(self):
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)

{engineering_process-0.3.0 → engineering_process-0.4.0}/tests/test_skills.py

@@ -10,6 +10,27 @@ PROCESS_ROOT = Path(__file__).resolve().parent.parent
 
 
 class SkillTests(unittest.TestCase):
+    def test_failure_to_invariant_protocol_is_distribution_owned(self):
+        skills = PROCESS_ROOT / "process_assets" / "skills"
+        execution = (skills / "run-change" / "references" / "execution.md").read_text(
+            encoding="utf-8"
+        )
+        run_change = (skills / "run-change" / "SKILL.md").read_text(encoding="utf-8")
+        evolve = (skills / "evolve-process" / "SKILL.md").read_text(encoding="utf-8")
+        review = (skills / "review-change" / "SKILL.md").read_text(encoding="utf-8")
+        production = (PROCESS_ROOT / "PRODUCTION_STANDARD.md").read_text(encoding="utf-8")
+
+        self.assertIn("## Failure-to-invariant protocol", execution)
+        self.assertIn("`project-local`, `shared-process`", execution)
+        self.assertIn("A shared-process defect must be fixed in", execution)
+        self.assertIn("valid\n   behavior", execution)
+        self.assertIn("bounded, idempotent", execution)
+        self.assertIn("failure-to-invariant protocol", run_change)
+        self.assertIn("keep the consumer candidate blocked", evolve)
+        self.assertIn("real\n   affected-consumer reproduction", evolve)
+        self.assertIn("Treat owner mismatch", review)
+        self.assertIn("## Failure to invariant", production)
+
     def test_repository_skills_are_portable(self):
         self.assertEqual(
             validate_skills(PROCESS_ROOT / "process_assets" / "skills"), []

{engineering_process-0.3.0 → engineering_process-0.4.0}/tests/test_supervision.py

@@ -4,11 +4,12 @@ import sys
 import tempfile
 import unittest
 import subprocess
+from unittest.mock import Mock, patch
 
 from engineering_process._supervisor_posix import PosixProcessSupervisor
 from engineering_process._supervisor_windows import resolve_windows_application
 from engineering_process.helper_launch import isolated_helper_command
-from engineering_process.supervision import process_supervisor
+from engineering_process.supervision import CleanupOutcome, process_supervisor
 
 
 class ProcessSupervisionTests(unittest.TestCase):
@@ -33,6 +34,66 @@ class ProcessSupervisionTests(unittest.TestCase):
         )
         self.assertEqual(Path(sys.executable).resolve(), application)
 
+    def test_posix_finalization_returns_immediately_without_descendants(self):
+        process = Mock(pid=123)
+        supervisor = PosixProcessSupervisor()
+        with (
+            patch(
+                "engineering_process._supervisor_posix._process_group_exists",
+                return_value=False,
+            ),
+            patch("engineering_process._supervisor_posix._wait_for_process_group") as wait,
+            patch("engineering_process._supervisor_posix._terminate_group") as terminate,
+        ):
+            outcome = supervisor.finalize(process, grace_seconds=1)
+
+        self.assertEqual(CleanupOutcome(bounded=True), outcome)
+        wait.assert_not_called()
+        terminate.assert_not_called()
+
+    def test_posix_finalization_allows_bounded_natural_drain(self):
+        process = Mock(pid=123)
+        supervisor = PosixProcessSupervisor()
+        with (
+            patch(
+                "engineering_process._supervisor_posix._process_group_exists",
+                return_value=True,
+            ),
+            patch(
+                "engineering_process._supervisor_posix._wait_for_process_group",
+                return_value=True,
+            ) as wait,
+            patch("engineering_process._supervisor_posix._terminate_group") as terminate,
+        ):
+            outcome = supervisor.finalize(process, grace_seconds=1)
+
+        self.assertEqual(CleanupOutcome(bounded=True), outcome)
+        wait.assert_called_once_with(123, 0.25)
+        terminate.assert_not_called()
+
+    def test_posix_finalization_rejects_descendant_after_natural_drain_bound(self):
+        process = Mock(pid=123)
+        supervisor = PosixProcessSupervisor()
+        expected = CleanupOutcome(bounded=True, descendants_found=True)
+        with (
+            patch(
+                "engineering_process._supervisor_posix._process_group_exists",
+                return_value=True,
+            ),
+            patch(
+                "engineering_process._supervisor_posix._wait_for_process_group",
+                return_value=False,
+            ),
+            patch(
+                "engineering_process._supervisor_posix._terminate_group",
+                return_value=expected,
+            ) as terminate,
+        ):
+            outcome = supervisor.finalize(process, grace_seconds=1)
+
+        self.assertEqual(expected, outcome)
+        terminate.assert_called_once_with(123, 1)
+
     @unittest.skipUnless(os.name == "posix", "POSIX executable permission semantics")
     def test_posix_relative_path_entries_are_resolved_from_command_working_directory(self):
         with tempfile.TemporaryDirectory() as directory:

{engineering_process-0.3.0 → engineering_process-0.4.0}/tests/test_windows_job.py

@@ -9,6 +9,7 @@ import unittest
 from unittest.mock import patch
 
 from engineering_process import _windows_job
+from engineering_process.supervision import NATURAL_DRAIN_GRACE_MILLISECONDS
 
 
 class NativeCall:
@@ -153,6 +154,12 @@ class FakeKernel32:
 
 
 class WindowsJobTests(unittest.TestCase):
+    def test_natural_drain_uses_the_portable_supervision_bound(self):
+        self.assertEqual(
+            NATURAL_DRAIN_GRACE_MILLISECONDS,
+            _windows_job.NATURAL_DRAIN_GRACE_MILLISECONDS,
+        )
+
     def test_target_is_assigned_atomically_during_process_creation(self):
         kernel32 = FakeKernel32()
 

engineering_process-0.3.0/release.json

@@ -1,54 +0,0 @@
-{
-  "schemaVersion": 3,
-  "previousVersion": "0.2.1",
-  "version": "0.3.0",
-  "classification": "minor",
-  "compatibility": "backward-compatible",
-  "schemaImpact": "unchanged",
-  "migration": null,
-  "identity": {
-    "package": "engineering-process",
-    "distribution": "engineering_process",
-    "tag": "v0.3.0",
-    "releaseName": "v0.3.0",
-    "runtimeVersion": {
-      "path": "engineering_process/__init__.py",
-      "variable": "VERSION"
-    },
-    "artifacts": [
-      "engineering_process-0.3.0-py3-none-any.whl",
-      "engineering_process-0.3.0.tar.gz"
-    ],
-    "receiptAsset": "engineering-process-v0.3.0-evidence.json",
-    "authorizationAsset": null
-  },
-  "provenance": {
-    "mode": "governed",
-    "statement": "The public N-1 lifecycle receipt and reviewed Release PR authorize this release.",
-    "lifecycleReceipt": {
-      "asset": "engineering-process-v0.3.0-evidence.json",
-      "project": "engineering-process",
-      "changeId": "release-0-3-0",
-      "cycle": 1
-    }
-  },
-  "changes": [
-    {
-      "id": "consumer-process-boundary-cleanup",
-      "type": "capability",
-      "surfaces": [
-        "ci-bootstrap",
-        "workflow"
-      ],
-      "rationale": "Provide one immutable producer-owned CI installation action so consumers can remove copied process algorithms without weakening exact hash locks or bounded registry propagation recovery."
-    },
-    {
-      "id": "reopen-stale-verification",
-      "type": "fix",
-      "surfaces": [
-        "lifecycle"
-      ],
-      "rationale": "Allow a verified change invalidated by later remote evidence or a source correction to begin a new implementation cycle while preserving prior evidence and still forbidding current verified work from bypassing independent review."
-    }
-  ]
-}