engineering-process 0.1.0__py3-none-any.whl

engineering_process-0.1.0.data/data/share/engineering-process/skills/maintain-docs/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: maintain-docs
+description: Maintain durable documentation, diagrams, links, status text, routing, and ownership without duplicating product or process decisions. Use when guidance changes, when renamed or retired concepts may drift, or when documentation consistency must be verified.
+---
+
+# Maintain Documentation
+
+## Goal
+
+Keep one authoritative owner per fact and make every dependent document point to it.
+
+## Workflow
+
+1. Classify the content as product behavior, architecture, process, enforcement,
+   operations, navigation, or generated output.
+2. Locate the project-declared owner. Preserve the domain decision supplied by that
+   owner; documentation maintenance does not invent it.
+3. Edit the owner once, replace duplicate rules with links, and remove stale names,
+   session history, temporary status, and superseded instructions.
+4. Update diagrams or generated documentation from their declared source rather than
+   editing derived output independently.
+5. Run the smallest documentation checks declared by the project verification
+   profiles. Validate changed links and anchors when their targets moved.
+6. Apply the retirement sweep and report unresolved ownership or generation gaps.
+
+## Hard gates
+
+- Do not move product, architecture, or release authority into a documentation skill.
+- Do not keep approval provenance or conversational history as durable policy.
+- Do not duplicate a reusable process rule in a consumer project.
+
+## Output
+
+Return the owner changed, duplicates removed, generated artifacts, retirement sweep,
+verification evidence, and unresolved ownership decisions.

engineering_process-0.1.0.data/data/share/engineering-process/skills/plan-change/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: plan-change
+description: Build and register an executable implementation plan from a specified change contract. Use after change specification and required sign-off, before editing implementation files for any non-trivial engineering change.
+---
+
+# Plan a Change
+
+## Goal
+
+Convert accepted outcomes and project policy into one bounded, reviewable execution
+plan without changing implementation source.
+
+## Workflow
+
+1. Read lifecycle status, the registered change contract, nearest AGENTS.md, and only
+   the project owners needed for the affected surface.
+2. Trace callers, consumers, trust boundaries, tests, migrations, generated outputs,
+   documentation, and retirement work far enough to define complete work items.
+3. Record ordered work items with owned paths and verification profiles. Map every
+   acceptance criterion to at least one work item and project-owned profile.
+4. Record concrete risks and mitigations. Leave behavior-changing ambiguity as an
+   open decision; do not plan around it.
+5. Validate the plan with processctl contract validate --kind plan, then register it
+   with processctl change plan. Implementation remains blocked while required
+   sign-off or open decisions remain.
+
+## Hard gates
+
+- Do not edit implementation files during planning.
+- Do not omit required security, compatibility, data, accessibility, rollout, or
+  rollback work merely to reduce scope.
+- Do not invent project commands; select profiles from .process/project.json.
+
+## Output
+
+Return change id, lifecycle phase, ordered work items, acceptance mapping, risks,
+open decisions, required profiles, and next owner.

engineering_process-0.1.0.data/data/share/engineering-process/skills/publish-change/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: publish-change
+description: Publish or update a branch, pull request, or equivalent review object after the engineering lifecycle completes. Use only when the user authorizes a remote publication action or asks to change publication metadata.
+---
+
+# Publish a Change
+
+## Goal
+
+Publish one approved immutable checkpoint through the project-owned remote workflow
+without duplicating implementation, verification, or review.
+
+## Workflow
+
+1. Classify the exact authorized remote action and read the project publication
+   policy and current lifecycle status.
+2. For source publication, require a current completion record whose checkpoint and
+   workspace fingerprint match the source being published.
+3. Populate the managed PR-description sections with project-specific facts. Run
+   processctl publication validation for branch, commit range, PR title, body, and
+   draft/ready state; then run any stronger project-declared publication checks.
+4. Perform only the authorized remote action. Preserve draft state unless ready state
+   was explicitly requested.
+5. Record the remote identifier and status. Treat any later source change as a new
+   lifecycle cycle with invalidated publication readiness.
+
+## Hard gates
+
+- Never infer authorization to commit, push, open, merge, release, or deploy.
+- Do not publish source with stale evidence or unresolved required findings.
+- Do not replace, omit, or weaken the managed publication sections or standard
+  requirements; projects may append stricter metadata and checklists.
+- Metadata-only work may skip code implementation only when project policy permits it.
+
+## Output
+
+Return action, change id, checkpoint, completion evidence, metadata validation,
+remote state, and blockers.

engineering_process-0.1.0.data/data/share/engineering-process/skills/review-change/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: review-change
+description: Independently review an immutable verified change against its contract, plan, project policy, diff, and current evidence, then produce structured findings and an approval or changes-requested verdict. Use only from a reviewer actor and isolated context that did not implement the reviewed cycle.
+---
+
+# Review a Change
+
+## Goal
+
+Evaluate correctness, security, compatibility, maintainability, and evidence at a
+specific checkpoint without changing the reviewed source.
+
+## Workflow
+
+1. Accept the review only in a reviewer actor and isolated context that did not
+   implement the current cycle. Use the host's isolated-review mechanism or a
+   separate human reviewer; if separation cannot be attested, report blocked.
+2. Register the assignment with processctl change review start. Confirm its
+   checkpoint, comparison base, contract, plan, and required verification reports
+   refer to the same immutable source.
+3. Read the diff and only the project-owned contracts needed to evaluate affected
+   behavior and trust boundaries.
+4. Record actionable findings with severity, exact location, evidence, and status.
+   Separate defects from questions, optional improvements, and unsupported claims.
+   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.
+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
+   it with processctl change review submit. A coordinator may transport the assigned
+   reviewer's exact artifact; the host or human attester owns its authenticity. The
+   CLI rejects implementation identity reuse at assignment, stale evidence, missing
+   carried findings, assignment mismatches, and checkpoint mismatches.
+7. Return findings to the implementation owner. Review never silently edits,
+   publishes, or expands the accepted scope.
+
+## Hard gates
+
+- Do not approve stale, indirect, missing, or blocked evidence.
+- Do not treat review prose as more authoritative than project contracts.
+- A reviewer must not intentionally mutate the checkpoint under review.
+- The reviewer actor id and context id must both be independent from every
+  implementation actor and context recorded for the current cycle.
+
+## Output
+
+Return the structured report, attested reviewer identity, verdict, reviewed
+checkpoint and base, unresolved findings, lifecycle phase, and invalidated evidence.

engineering_process-0.1.0.data/data/share/engineering-process/skills/run-change/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: run-change
+description: Orchestrate a non-trivial engineering change through specification, planning, implementation, checkpoint verification, independent review, finding resolution, and completion. Use as the default entry skill whenever a project change must be delivered rather than merely explained or diagnosed.
+---
+
+# Run a Change
+
+## Goal
+
+Drive one canonical lifecycle from request to auditable completion while project
+owners retain product decisions, domain policy, commands, and publication authority.
+
+## Required reference
+
+Read [references/execution.md](references/execution.md) completely before starting or
+resuming a change. It defines universal execution, blocker, evidence, and delegation
+semantics shared by every project.
+
+## Lifecycle
+
+1. Run processctl doctor and inspect processctl change status when a change id exists.
+2. Route the current phase without creating a parallel plan or checklist:
+   - no registered change: use define-change-contract;
+   - specified: use plan-change;
+   - planned or changes-requested: use implement-change;
+   - implementing: use verify-change after a clean immutable checkpoint exists;
+   - verified: obtain a separate reviewer through review-change;
+   - review-pending: wait for the assigned reviewer; do not self-review;
+   - approved: use finish-change;
+   - completed: stop unless publication was separately authorized.
+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
+   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.
+   Never call a task complete from prose alone.
+
+## Hard gates
+
+- Do not edit implementation before specification, required sign-off, and planning.
+- Do not review work produced by the same actor or context.
+- Do not convert missing, stale, failed, timed-out, or blocked evidence into a pass.
+- Do not publish, merge, release, deploy, or perform destructive cleanup unless the
+  user separately authorized that project-owned action.
+
+## Output
+
+Return change id, phase, cycle, decisions, current evidence, gaps, blockers, next
+owner, and completion record when finished.

engineering_process-0.1.0.data/data/share/engineering-process/skills/run-change/references/execution.md

@@ -0,0 +1,88 @@
+# Portable Execution Contract
+
+Apply these semantics throughout every change lifecycle.
+
+## Universal gates
+
+1. Read the full active skill, this reference, the nearest AGENTS.md, and the affected
+   project owners before editing.
+2. Follow phase order. A stated stop condition blocks dependent work.
+3. Defer a specific accepted outcome only with explicit approval and an owner. A skip
+   never waives dependent gates implicitly.
+4. Reuse evidence only while its artifact, checkpoint, workspace fingerprint,
+   command, environment, and acceptance boundary remain current.
+5. Remove superseded implementation and guidance when compatibility is not required.
+   Do not preserve a retired path as an undocumented safety default.
+6. Separate development completion from commit creation, publication, merge, release,
+   deployment, and destructive data operations.
+
+## Change-driven scope
+
+Map affected paths, callers, consumers, trust boundaries, migrations, generated
+artifacts, documentation, and evidence-required dependencies to complete work items.
+Run the smallest profile that proves each accepted outcome. Use a broader profile only
+when cross-cutting invalidation, inseparable dependencies, or project policy requires
+it. Do not infer broad completion from a focused check.
+
+## Engineering method
+
+1. Trace the governing contract and real flow before choosing an owner or design.
+2. Prefer no change, existing code, the standard library, native platform behavior,
+   and installed dependencies before custom mechanisms, while preserving required
+   safety and acceptance behavior.
+3. For a defect, prove the smallest reliable failure first, state one hypothesis, test
+   one variable, implement the root-cause fix, and prove the behavior afterward.
+4. Treat a proposed path as a workaround when it changes the required owner, runtime,
+   authority, trust boundary, invariant, or evidence boundary merely to keep moving.
+   Return to specification and planning instead.
+5. Keep one writer for overlapping source. Delegate bounded disjoint work only when
+   the host supports it and the handoff preserves exact scope, permissions, stop
+   conditions, and evidence ownership.
+
+## Blocker protocol
+
+When progress depends on user-controlled or external state:
+
+1. Classify repository defect, missing product decision, or external-state blocker.
+2. Reproduce through the smallest permitted boundary and preserve the exact command,
+   exit status, error, environment, and missing authority.
+3. Continue safe read-only diagnosis, but stop mutation at authentication, consent,
+   permission, host setup, destructive action, or approval boundaries.
+4. Do not substitute a different command, library, runtime, environment, proxy,
+   credential path, disabled control, or indirect API as evidence for the required
+   boundary.
+5. Report `Blocker`, `Evidence`, `Boundary`, `User action or decision needed`, and
+   `Safe next step after confirmation`.
+
+## Independent review
+
+Review begins only after all baseline and change-required profiles pass on one clean
+immutable checkpoint. The reviewer must be a read-only actor and context unused by
+the current implementation cycle. The agent host or human organization attests that
+identity separation; processctl validates the attestation structure and rejects
+identity reuse or stale evidence.
+
+A running or pending reviewer means review pending, not failure or approval. The
+reviewer reads the assignment, diff, contracts, plan, and existing evidence; it runs
+only a focused reproducer for a concrete finding or evidence gap. It never edits
+tracked source or Git state. Any source mutation invalidates the assignment.
+
+An open required finding produces changes-requested. Preserve its checkpoint and
+evidence, classify the finding against the owning contract, implement the smallest
+correct resolution in a new cycle, and repeat invalidated verification and review.
+
+## Completion audit
+
+Map every acceptance criterion to current source and required verification. Require
+an approved independent review for the exact same checkpoint and workspace
+fingerprint, with no open required finding. Missing, stale, indirect, or blocked
+evidence remains incomplete. processctl completion is an engineering result, not
+publication or release authorization.
+
+## Process improvement
+
+Classify a validated defect or finding as local behavior, reusable process semantics,
+deterministic enforcement, portability gap, or obsolete guidance. Fix the smallest
+correct owner, add regression proof for deterministic behavior, and remove duplicate
+or superseded rules. Do not memorialize an incident as ceremony without evidence of
+the reusable class.

engineering_process-0.1.0.data/data/share/engineering-process/skills/run-project-command/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: run-project-command
+description: Select, execute, and maintain reproducible project commands for setup, diagnosis, generation, testing, local development, verification, and continuous integration. Use when choosing an executable proof, changing command topology, or handling a blocked project prerequisite.
+---
+
+# Run a Project Command
+
+## Goal
+
+Use the smallest project-declared command that proves the required boundary and keep
+repeatable execution deterministic.
+
+## Workflow
+
+1. Classify the moment as setup, diagnosis, exploration, implementation proof,
+   lifecycle verification, publication, or continuous-integration reproduction.
+2. Read `.process/project.json` and the nearest project owner. Run `processctl doctor`
+   for the selected environment profile. Reuse current evidence while its checkpoint,
+   command, environment, and acceptance boundary remain valid.
+3. Select the narrowest declared command. Use a broad profile only for cross-cutting
+   invalidation, an inseparable dependency, or an explicit project requirement.
+4. Confirm the command is a finite, non-interactive foreground task. Execute declared
+   checks through `processctl verify`, or ad-hoc foreground tasks
+   through `processctl exec --profile ... -- ...` so verified managed-tool bindings
+   and paths are injected. Keep secrets out of arguments and
+   evidence. Do not run commands concurrently when they share mutable build outputs.
+5. On a missing prerequisite, use `processctl setup` to inspect the complete plan.
+   Apply it only with explicit approval for every declared mutation scope. On failure,
+   preserve the exact command, exit status, environment, and missing prerequisite. Do
+   not substitute another runtime or evidence boundary.
+6. Declare pinned portable tool artifacts with immutable checksums; acquisition,
+   verification, safe extraction, atomic installation, and command binding remain
+   distribution-owned. Add project-native dependency commands or deterministic checks
+   only in the manifest; consumers do not reimplement process machinery.
+
+## Hard gates
+
+- Native read-only inspection is not verification evidence unless declared as such.
+- Do not replace focused missing evidence with an unrelated broad suite.
+- Do not install tools, change host trust, or mutate external state without authority.
+- Treat `readOnly` and command mutation scopes as project-owner attestations, not a
+  sandbox. Reject an incomplete scope declaration instead of assuming confinement.
+- Run only foreground commands. A declared command must not daemonize, create a
+  detached session, or leave background work behind; portable POSIX execution cannot
+  contain a process that deliberately escapes its owned process group.
+- Keep detached services, interactive shells, log followers, watchers, and stdio
+  servers in their project-owned lifecycle. Do not force them through the finite-task
+  executor or use them as verification checks.
+- An installer exit code is not readiness evidence; the declared probe must pass after
+  setup.
+
+## Output
+
+Return moment, selected commands and reasons, results, reused evidence, omitted broad
+checks, blockers, and next verification boundary.

engineering_process-0.1.0.data/data/share/engineering-process/skills/specify-use-case/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: specify-use-case
+description: Create or repair an implementation-independent product use-case contract with actors, outcomes, flows, acceptance criteria, test boundaries, decisions, and scope. Use when requested behavior is missing, ambiguous, contradictory, or not ready for implementation.
+---
+
+# Specify a Use Case
+
+## Goal
+
+Produce a testable product contract without inventing behavior or mixing current
+implementation details into expected outcomes.
+
+## Workflow
+
+1. Locate the project-declared product owner and related contracts, code, tests, and
+   vocabulary. Surface conflicts instead of resolving them silently.
+2. Define the primary actor goal, preconditions, trigger, success and minimal
+   guarantees, main flow, alternate and failure flows, and explicit boundaries.
+3. Keep behavior observable and implementation-independent. Link shared technical
+   constraints to their architecture owner instead of copying them.
+4. Write cohesive acceptance criteria and map each to the lowest reliable acceptance
+   boundary. Keep unresolved behavior as a decision, not a required test.
+5. Define compatibility only from supported consumers and data. Record an intentional
+   clean replacement when overlap is not required.
+6. Validate the contract with project-declared documentation and link checks, then
+   register the approved scope through the shared change lifecycle.
+
+## Hard gates
+
+- Do not invent identifiers, authorization, integrations, data, or product behavior.
+- Do not begin implementation while a behavior-changing decision remains blocking.
+- Do not encode framework or storage choices unless interoperability is the outcome.
+
+## Output
+
+Return owner, readiness, actors, flows, acceptance scope, test boundaries, decisions,
+compatibility, validation evidence, and blockers.

engineering_process-0.1.0.data/data/share/engineering-process/skills/verify-change/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: verify-change
+description: Select and run project-owned verification profiles, preserve exact checkpoint evidence, and advance a planned change only when all required profiles pass. Use after implementation, after review fixes, or before an independent-review readiness claim.
+---
+
+# Verify a Change
+
+## Goal
+
+Produce current, reproducible evidence for the acceptance outcomes affected by the
+change while avoiding unrelated broad verification.
+
+## Workflow
+
+1. Read the lifecycle state, change contract, nearest AGENTS.md, and
+   .process/project.json.
+2. Map each affected acceptance outcome to the smallest project-owned profile that
+   proves it. Reuse still-current evidence and expand scope only when invalidation or
+   project policy requires it.
+3. Use processctl change verify for lifecycle evidence. Use processctl verify only
+   for exploratory or focused evidence that is not intended to advance the lifecycle.
+   Do not substitute a different command, runtime, trust boundary, or environment
+   when a required check is blocked.
+4. Bind evidence to the current repository checkpoint and workspace fingerprint.
+   Any relevant edit or source mutation during verification invalidates the evidence.
+5. Report failed, timed-out, missing, and blocked checks exactly; never convert them
+   into a pass or an implicit deferral.
+
+## Hard gates
+
+- Project manifests own commands; this skill must not invent replacement commands.
+- A focused check cannot prove a broader acceptance boundary than it exercises.
+- Verification does not publish, merge, deploy, or approve a change.
+
+## Output
+
+Return change id, cycle, profiles, checkpoint, check statuses, evidence report
+locations, lifecycle phase, gaps, and the next owner.

engineering_process-0.1.0.data/data/share/engineering-process/templates/AGENTS.process.md

@@ -0,0 +1,17 @@
+<!-- engineering-process:start -->
+## Engineering process
+
+Use the portable skills pinned by `.process/process.lock` for every non-trivial
+change. Enter through `run-change` and use `processctl change ...` for specification,
+planning, implementation registration, checkpoint verification, independent review,
+finding resolution, and completion.
+
+The project owns product decisions, domain contracts, exact verification commands,
+and publication authority. The process distribution owns lifecycle semantics and
+managed skills. Do not edit managed skills in this repository; update the pinned
+distribution and synchronize them instead.
+
+Independent review requires an attested read-only actor and context that did not
+implement the current cycle. No particular agent host is required. Missing or stale
+evidence, self-review, and publication without separate authorization are blocking.
+<!-- engineering-process:end -->

engineering_process-0.1.0.data/data/share/engineering-process/templates/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+<!-- engineering-process:pr-description:start -->
+## Summary
+
+<!-- State what changed and why. Use project language; do not list commits or CI jobs. -->
+
+## Contract and scope
+
+<!-- Link the owning spec, change contract, issue, or decision. State explicit N/A with a reason. -->
+
+## Impact and risk
+
+<!-- Describe user/developer impact, compatibility, migrations, rollout, and residual risk. -->
+
+## Verification
+
+<!-- List exact current commands/evidence and any blocked or intentionally omitted boundary. -->
+
+## Independent review
+
+<!-- Record reviewer separation, reviewed checkpoint, verdict, and required-finding status. -->
+
+## Requirements and rules followed
+
+- [ ] **Scope and contract** — accepted scope is implemented without unapproved expansion. [status: pending]
+- [ ] **Verification evidence** — required current profiles pass on the published checkpoint. [status: pending]
+- [ ] **Independent review** — a separate reviewer approved the published checkpoint with no open required finding. [status: pending]
+<!-- engineering-process:pr-description:end -->