procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/skills/PORTFOLIO.md

@@ -0,0 +1,134 @@
+# Five-skill portfolio: migration and qualification
+
+## Purpose and loading
+
+This is the actual instruction portfolio for coding agents: five complementary
+owners, not five mandatory stages and not a new CLI command. Open the chosen
+`skills/<name>/SKILL.md`, then read its conditional references relative to that
+package. An Agent Skills-compatible client's native discovery/file reader is
+sufficient; additional MCP search/resource features are optional, not required.
+
+- `procesio-cli`: approved platform operations and direct outcome verification.
+- `procesio-platform-advisor`: feasibility, architecture and sourced capacity advice.
+- `sql-server-optimizer`: measured tuning preserving SQL semantics and isolation.
+- `procesio-cli-maintainer`: source/manifests/tests and repository integration.
+- `agent-skill-engineer`: skill design, fixed rubrics, auditing and bounded improvement.
+
+The operational and maintainer packages assume a configured checkout of this
+repository when invoking `python scripts/...`. Run those commands from that
+checkout's root, not from the skill directory or an arbitrary project. Credentials
+and target authority are separate from installing a skill. A skill is not a sandbox.
+
+Python helpers need Python 3.11+. The audit additionally imports PyYAML. From this
+repository, `uv sync --all-extras` installs the development/test dependencies,
+including pytest. SQL helpers require an explicitly scoped SQL Server connection;
+they are never executed during installation, discovery or offline tests.
+
+## Proposed export-path migration — maintainer approval required
+
+This PR proposes an exception to CONTRIBUTING's no-move rule; it does not claim
+that the exception was accepted. Do not merge until the source/export owner agrees.
+
+- Retire `skills/procesio-expert/`: product advice moves conceptually to
+  `procesio-platform-advisor`; operations belong to `procesio-cli`. Do not keep
+  the old broad expert trigger active alongside the new bounded owners.
+- Retain `skills/sql-server-optimizer/` as the SQL skill, with revised guidance.
+- Move each of `export-tables.sql`, `export-indexes.sql`, and
+  `export-procs-and-functions.sql` from its `references/scripts/` directory to
+  `scripts/`, updating references. The table exporter is UTF-8 rather than the
+  old non-UTF-8 file. Publication adds scope warnings and a default-off server
+  trigger option, not a newly qualified exporter implementation.
+- Add the three remaining owner packages and their local helpers/cases.
+
+This is a standalone proposal against upstream main at
+`a731baf738ec5c90fe9ac67265e532907a212a0b`. It does not depend on the optional
+CLI/MCP discovery PR. No CLI handler, MCP server, credential store or platform
+execution implementation is replaced. Minimal manifest metadata fields support
+the offline governance checker; they do not enable runtime integrity admission.
+
+Keep the pre-migration commit until adoption is verified. A maintainer can revert
+this portfolio commit to restore old discovery paths; never run both ownership
+models accidentally. Clients referring to `procesio-expert` or old SQL paths need
+an explicit configuration update after the agreed migration.
+
+## Evidence contract
+
+The checked-in `portfolio-package-fingerprints.json` records the exact packaged
+files with SHA-256. It establishes source identity, not correctness, safety,
+behavioral uplift or release qualification. Tests recompute every package hash.
+
+Skill versions, `last_verified` dates and `baseline_version` SHAs retain historical
+source metadata. They are not current extraction-test timestamps and do not imply
+that those commits are in this PR's ancestry or available in an upstream clone.
+The packaged catalog/baseline JSON files are frozen historical **description-scorer
+fixtures**, not a measurement of improvement over current upstream main. Reproduce
+them offline from their embedded data; no fetch or historical private tree is needed.
+
+Per-package fixed-rubric cases and the global behavioral corpus are contracts, not
+observed agent responses. Field-boundary and closeout cases are development-only,
+not untouched holdouts. `procesio-cli/evals/workflows.json` is a development checklist.
+Static phrase-retention assertions and the audit's quality score prove neither
+runtime enforcement nor measured behavior. No historical passing runtime reports
+or private proof packets are imported as evidence for this extraction.
+
+The extraction-specific `gates.json` remains **release_eligible: false**. Its
+`infrastructure-complete` entries identify installed contracts, not passed field
+or behavioral gates. This proposal is for code/content review, not production
+certification. It carries no permission to run live qualification experiments.
+
+## Included offline validation
+
+From the repository root:
+
+```bash
+uv run pytest tools agents dashboard webplatform skills -q
+uv run python scripts/validate-skills.py --strict-warnings
+uv run python scripts/evaluate-skills.py --catalog skills/evals/baseline-catalog.json --verify-baseline skills/evals/baseline.json
+uv run python scripts/evaluate-skill-routing.py --catalog skills/evals/baseline-catalog.json --verify skills/evals/baseline-routing-v2.json
+uv run python scripts/evaluate-skill-routing.py --min-accuracy 0.95 --max-collision-rate 0
+uv run python scripts/check-skill-governance.py
+uv run python scripts/secret_scan.py
+uv run python scripts/build-router.py --check
+```
+
+`check-skill-governance.py --require-release-eligible` must fail until new matched
+proof is accepted. Default governance success only validates the blocked ledger's
+structure/metadata. The release-binding helper is tested with synthetic Git repos;
+it does not silently substitute current bytes for a missing evaluated commit.
+
+CI includes offline checks only: no model runner, SQL Server connection, PROCESIO
+field project or automatic platform run. Actual results belong in the PR/CI, not
+in a copied historical pass. Cross-platform and native-agent behavior must be
+verified on the intended client before portability claims are made.
+
+## Remaining source-owned limitations
+
+- **Approval and verifier runtime:** instructions do not repair argument-insensitive
+  MCP classification, failed/skipped verifier prerequisites or native confidentiality
+  enforcement. Obtain approval before calling either execution endpoint; inspect
+  actual persisted/output evidence rather than a successful aggregate status.
+- **Schedule projection:** check that the installed CLI supports the redacted read
+  before acquiring sensitive inputs. If absent, stop and arrange an approved safe
+  observation boundary. Raw output is not an equivalent fallback.
+- **SQL exporters:** broad metadata inspection only. Module definitions can carry
+  secrets; confirm acquisition scope before running. Server trigger collection is
+  separately opt-in. Index-family serialization and NULL-definition handling remain
+  incomplete; output is not a restoration/replay contract. No live SQL proof is
+  supplied and no automatic whole-database export is authorized.
+- **Optimizer:** the helper does not enforce one-shot terminal final-test custody
+  and can accept later final reports. Preserve independent external custody of the
+  untouched test; repeated submission is not new acceptance. Runtime repair needs
+  a separately scoped change and regression proof.
+- **Scaffold metadata:** the portable scaffold also accepts `stable` and `versioned`,
+  which this repository's manifest does not accept. For repository integration, use
+  its default `timestamped` or `generated`; run the included governance check before
+  adoption. The portable helper's wider vocabulary is not repository policy.
+- **Observation summaries:** the optional scorer rejects non-Boolean success values,
+  but cannot authenticate results or prove corpus completeness. It is not a release
+  acceptance gate; independent fixed-rubric evidence remains necessary.
+- **Qualification:** matched behavioral A/A/A/B, transfer, native field proof and
+  source-owner approval remain missing for the final packaged bytes.
+
+Private field projects, browser-capture experiments, showcase receipts, installation
+profiles, ontology state, machine-local logs and historical governance queues are
+intentionally outside this contribution.

procesio_cli/skills/__init__.py

@@ -0,0 +1,6 @@
+"""Skills category — discoverable instruction/reference bundles.
+
+Each subfolder is a self-contained skill whose `SKILL.md` YAML frontmatter
+(`name` + `description`) acts as its manifest. Discovered by `registry.list_skills`
+and loaded by `scripts/get-skill.py`. See README.md for the contract.
+"""

procesio_cli/skills/agent-skill-engineer/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: agent-skill-engineer
+description: >-
+  Engineer reusable Agent Skill packages and SKILL.md routing and evaluation systems.
+  Use when the primary deliverable is an Agent Skill: turn a repeated agent workflow
+  into a skill, author or revise a SKILL.md or a domain skill such as the SQL optimizer
+  skill, change a skill description or trigger boundary, split skill content into
+  progressive references, scripts, or assets, build fixed-rubric baselines and A/A or
+  A/B skill evaluations, or audit a skill package. Do not use for ordinary repository
+  implementation, workspace operations, unrelated CLI design, image creation, or
+  one-off content.
+version: 2.0.4
+compatibility: Agent Skills compatible clients; Python 3.11+ for bundled helpers.
+owner: procesio-cli maintainers
+last_verified: 2026-09-09
+baseline_version: a47135373c4c0598391e808939397cd139234afd
+eval_suite: evals/evals.json
+source_policy: timestamped
+routing:
+  triggers:
+    - create, update, split, merge, refactor, or audit an Agent Skill or SKILL.md package
+    - optimize skill descriptions, routing boundaries, progressive disclosure, context cost, or safety
+    - design fixed-rubric skill evaluations, baselines, A/A noise checks, A/B comparisons, or field trials
+  primary_action: engineer
+  example: get-skill.py agent-skill-engineer --content
+---
+
+# Engineer Agent Skills
+
+Create the smallest skill package that reliably changes agent behavior and proves the change. Treat a skill as an auditable intervention on a frozen agent, not as a persuasive document, topic encyclopedia, or prestige persona.
+
+## Boundary
+
+- Use this skill when the primary artifact is an Agent Skill, its routing contract, its resources, or its evaluation and optimization system.
+- Use `procesio-cli-maintainer` when the primary work is repository code, manifests, MCP, CI, or generated integration; return here for the skill-specific design and evidence.
+- Use the domain skill when the user wants the domain task performed rather than encoded for reuse.
+- Do not create a skill for a one-off answer, volatile facts, or behavior that a type, API, lint, test, script, permission boundary, or tool can enforce more reliably.
+
+## Non-negotiables
+
+1. **Evidence before prose.** Start from repeated trajectories, observed failures, costly risks, or validated examples. Do not invent a problem to justify a skill.
+2. **Skill as intervention.** State the causal behavior the skill should change. Measure both repairs of baseline failures and regressions of baseline successes.
+3. **One intent, one owner.** Give every trigger region a clear owner and explicit non-trigger neighbors. Avoid universal skills and duplicate workflows.
+4. **Context is a budget.** Put only routing and always-needed decisions in `SKILL.md`; load conditional references on demand and move deterministic repetition into scripts.
+5. **Match freedom to fragility.** Use judgment for open-ended work, structured templates for preferred patterns, and executable helpers for narrow error-prone operations.
+6. **Freeze evidence contracts before results.** Lock cases, split membership, rubric IDs, pass conditions, objective hierarchy, edit budget, and stopping rules before formal optimization.
+7. **Protect the holdout.** Optimize on training evidence, promote on held-out validation, and inspect the final test set only after choosing the candidate. Never edit evals to make a candidate win.
+8. **Prefer bounded changes.** After the first grounded design, propose small add/delete/replace edits, preserve the best-known version, and record rejected edits so failures are not rediscovered.
+9. **Safety is lexicographic.** Hard correctness, permission, privacy, and non-regression constraints pass before quality, token, latency, or elegance objectives are compared.
+10. **Prove the real outcome.** Static validity and fluent output are proxies. Exercise the actual user path when the skill controls an executable or externally observable workflow.
+11. **Encode recurring lessons structurally.** A repeated correction belongs in a validator, script, schema, test, runtime guard, or source-owned reference before it becomes another paragraph.
+12. **Calibrate expertise.** Use independent expert lenses and evidence, preserve dissent, and require accountable human review where law, medicine, safety, finance, compliance, or organizational authority demands it.
+13. **Never claim readiness without evidence.** Label unexecuted work as draft or provisional and name the missing proof.
+14. **Field gates are fixed contracts.** Predeclare required check IDs, permitted gaps and fallbacks, cleanup, and the full causal side-effect budget. Host code—not the acting agent—decides pass; preserve a failed report and use separately approved remediation instead of relabeling it.
+
+## Select the mode
+
+- **Create:** qualify a repeatable capability, acquire domain truth, define its boundary, then build and test a new package.
+- **Improve:** snapshot the old package, reproduce a concrete failure, and change the smallest causal instruction or resource.
+- **Optimize:** train the package through bounded trajectory-driven edits, held-out promotion, rejected-edit memory, and an immutable final test.
+- **Description tune:** preserve body behavior; optimize discovery only with positive, negative, overlap, pressure, and portfolio collision cases.
+- **Audit:** inspect structure, routing, safety, portability, evaluation validity, and real-proof coverage without rewriting by default.
+- **Portfolio design:** split, merge, retire, or compose skills so each user intent has one bounded owner.
+- **Domain synthesis:** turn primary sources, expert demonstrations, critical incidents, and operational evidence into a calibrated decision model before authoring instructions.
+
+## Read only what the current mode needs
+
+- Read `references/decision-framework.md` before deciding whether a skill should exist or how a portfolio should be divided.
+- Read `references/domain-evidence-protocol.md` before encoding specialized or high-consequence expertise.
+- Read `references/authoring-standard.md` before drafting or restructuring a skill package.
+- Read `references/optimization-protocol.md` before iterative or automated skill optimization.
+- Read `references/optimizer-contract.md` before operating the deterministic optimizer controller or producing its reports.
+- Read `references/evaluation-standard.md` before writing cases, rubrics, baselines, juries, or performance claims.
+- Read `references/field-gate-standard.md` before designing a staged field trial, acceptance gate, execution budget, degraded mode, or remediation.
+- Read `references/review-standard.md` before approval, publication, or a production-ready claim.
+- Read `references/expert-lenses.md` for non-trivial or cross-domain review.
+- Read `references/portability-standard.md` when the skill must work across clients, operating systems, or repositories.
+- Read `references/research-basis.md` when refreshing this methodology or resolving disagreement about its design choices.
+
+Use the bundled helpers when appropriate:
+
+- Run `scripts/scaffold_skill.py` to create a path-confined draft without overwriting an existing package.
+- Run `scripts/audit_skill.py` for deterministic structure, resource, secret, metadata, and fixed-rubric checks.
+- Run `scripts/optimize_skill.py` for fingerprinted snapshots, bounded edits, paired validation and rejected-edit history; final test separation requires external one-shot custody, not just this helper.
+
+```bash
+python skills/agent-skill-engineer/scripts/scaffold_skill.py <name> \
+  --root skills --description "<capability and trigger boundary>"
+
+python skills/agent-skill-engineer/scripts/audit_skill.py \
+  skills/<name> --strict
+
+python skills/agent-skill-engineer/scripts/optimize_skill.py init \
+  --skill-root skills/<name> \
+  --workspace .skill-optimization/<name> \
+  --objective objective.json \
+  --baseline-report baseline-validation.json
+```
+
+The scaffold never overwrites an existing path. The audit is deterministic. The optimizer controller makes no model or network calls; it checks snapshot fingerprints, path allowlists, edit budgets and validation promotion. It does **not** enforce one-shot final test custody: `finalize` permits resubmission and overwrites its saved final-test report. An external owner must freeze test identity, hold the untouched cases, authorize one final run after selection, archive the first report immutably and block retries after either pass or failure. Treat autonomous one-shot enforcement as a qualification blocker, not a runtime guarantee; see `references/optimizer-contract.md`.
+
+## Workflow
+
+### 1. Ground the need
+
+Inspect the repository, artifacts, transcripts, tool schemas, current skill behavior, and existing portfolio before asking for information already available. Collect realistic examples in these classes:
+
+- clear positive trigger;
+- clear negative or abstention;
+- nearest overlap with another skill;
+- missing-context case;
+- pressure case inviting an unsafe shortcut or false completion;
+- representative successful outcome;
+- baseline success that the new skill must not break.
+
+Record the no-skill behavior for a new capability or preserve an immutable old-portfolio snapshot for an existing one.
+
+### 2. Acquire and calibrate domain truth
+
+For specialized work, build a claim-and-decision ledger before writing instructions. Separate facts, invariants, heuristics, local policy, preferences, unknowns, and decision rights. Prefer primary sources, real artifacts, successful and failed trajectories, and critical incidents over generic summaries.
+
+Select independent expert lenses by failure consequence, not prestige. Give them the same evidence packet. Require each finding to name evidence, scope, confidence, disconfirming conditions, and the design decision it changes. Preserve unresolved dissent and escalate to an accountable human when simulation is not sufficient.
+
+### 3. Freeze the contract and experiment
+
+Write a compact skill brief containing:
+
+- observable user outcome and non-goals;
+- trigger and explicit non-trigger boundary;
+- inputs, outputs, dependencies, permissions, and side effects;
+- invariants, unknown-outcome semantics, and irreversible failure modes;
+- source ownership and freshness policy;
+- target clients and compatibility assumptions;
+- evidence tier and direct proof;
+- training, validation, test, and field-case ownership;
+- primary metric, hard constraints, secondary costs, minimum effect, edit budget, and stopping rule.
+
+Turn behavioral requirements into ordered atomic criterion IDs with binary pass conditions. Keep routing selection separate from task quality. Keep formal rubrics hidden from the response-producing candidate.
+
+For operational field work, also freeze ordered acceptance check IDs, permitted degraded modes, cleanup, resource/write/trigger limits, and the full parent/child execution budget. Make the controller validate reports and compute promotion; do not let the acting agent choose its own pass criteria.
+
+### 4. Explore the design space
+
+For non-trivial skills, produce at least two structurally distinct designs from the same brief. Vary package boundary, degree of freedom, control flow, and resource split—not cosmetic wording. Include a minimal design and a plausible alternative.
+
+Review candidates independently through the selected expert lenses and an adversarial pre-mortem. Choose one coherent base using the frozen objective hierarchy. Graft only compatible strengths. Record rejected alternatives and the evidence that ruled them out.
+
+If candidates diverge wildly, the brief or domain model is underspecified. Re-ground instead of averaging incompatible designs.
+
+### 5. Build the minimum package
+
+Create only files that improve execution:
+
+- `SKILL.md`: discovery metadata, boundary, invariants, core decisions, workflow, resource router, and completion contract;
+- `references/`: stable detail, variants, schemas, or domain evidence loaded only when needed;
+- `scripts/`: deterministic, repeated, safety-critical, or format-fragile operations with bounded interfaces;
+- `assets/`: templates or media used in outputs, never hidden instructions;
+- `evals/`: realistic cases with fixed rubrics, split ownership, and immutable baseline intent.
+
+Target fewer than 250 body lines and treat 500 as a hard ceiling. Remove generic advice the model already knows, duplicated source material, research diaries, decorative personas, and instructions that cannot affect a decision.
+
+### 6. Prove structure, routing, and security
+
+Run the local audit and the host repository's native validator. Resolve every reference, validate frontmatter and resource confinement, scan for secrets and placeholders, and execute scripts on supported platforms. Treat downloaded skills and scripts as supply-chain code: inspect provenance, permissions, network behavior, and mutation scope.
+
+Run discovery cases against the full portfolio, not the candidate in isolation. Include equivalent paraphrases and irrelevant-detail variants. Zero forbidden collisions is the default bar.
+
+### 7. Optimize behavior without contaminating the test
+
+Collect paired trajectories from the frozen target agent. Contrast baseline successes, baseline failures, candidate repairs, candidate regressions, and near-successes. Convert repeated evidence into one explicit intervention hypothesis.
+
+After the initial design, use a bounded textual learning rate: small add/delete/replace edits with an exact file and line budget. Screen on training cases, then promote only when held-out validation strictly clears the registered improvement and every hard constraint. Preserve the best version and add rejected edits with their hypotheses and failure evidence to the ledger.
+
+Prefer deletion and substitution over accumulation. When several candidates trade quality, cost, and latency, retain only non-dominated candidates after hard constraints; do not hide safety inside a weighted average. Stop on plateau, exhausted budget, evaluator instability, or evidence that the problem belongs to another layer.
+
+When trustworthy ground truth is unavailable, use blinded pairwise comparison plus an independent behavior extractor, validation gating, and human review of discordant pairs. Do not convert self-preference into certainty.
+
+### 8. Prove the final candidate
+
+Run the untouched test set once after candidate selection. Report repairs and regressions, paired effect size, uncertainty, cost, and all hard-constraint outcomes. Then test at least one adjacent model or target client when portability is claimed.
+
+For operational skills, run a controlled end-to-end task through the same surface a real agent uses. Preview mutations, obtain approval, execute once, and observe the actual resulting state or output. Perform approved safety containment even when output verification fails; preserve evidence before authorized destructive cleanup. A screenshot, HTTP success, compile, lint, or self-report is insufficient when stronger direct observation exists.
+
+When a required field outcome fails, keep the original report blocked or failed. Classify the causal layer, archive the evidence, version a narrower remediation contract with fresh approval, rerun only the missing claims, and let deterministic host validation promote the result. Never weaken a completed gate after seeing a platform limitation.
+
+For subjective skills, use blinded human comparison and concrete preference evidence instead of fabricated objective assertions.
+
+### 9. Release and learn
+
+Keep a change only when it fixes a demonstrated integrity defect or improves the frozen objective beyond measured noise without unacceptable regressions. Update version, ownership, freshness, routing corpus, fixed rubrics, generated indexes, translations, governance records, and source register as required by the host repository.
+
+After release, collect sanitized field trajectories and explicit user corrections. Route each signal to its causal layer. Reopen optimization only with a new versioned experiment contract; never silently train on the final test set.
+
+## Failure attribution
+
+Before changing instructions, classify the failure:
+
+| Layer | Typical evidence | Correct response |
+|---|---|---|
+| Need/ownership | capability is one-off, duplicated, or better enforced elsewhere | retire, merge, or choose a stronger artifact |
+| Domain model | source conflict, expert disagreement, wrong invariant, missing edge condition | repair evidence and decision model |
+| Routing | wrong skill or no skill selected | tune metadata or portfolio boundary |
+| Instruction | right skill, wrong decision or sequence | change the smallest causal instruction |
+| Resource | missing, stale, or over-loaded reference, helper, or template | repair source ownership or resource routing |
+| Tool/runtime | command, API, auth, or environment failure | fix the executable system, not skill prose |
+| Observation | proxy proof disagrees with real state | strengthen direct verification |
+| Evaluation | leakage, unstable jury, wrong counterfactual, or ambiguous criterion | repair the experiment and restart affected evidence |
+| Field contract | acting agent invents checks, grants an unregistered gap, or ignores nested side effects | fix host-enforced checks and budgets; preserve the result and remediate |
+| Optimization | edit overfits training, regresses a baseline success, or only adds length | reject, record, and try a bounded alternative |
+
+## Verification
+
+A publishable result must identify:
+
+- mode, skill boundary, target clients, and evidence tier;
+- baseline fingerprint and reproduced failure or leverage case;
+- domain evidence, uncertainties, expert-lens findings, and accountable signoffs where required;
+- files created, changed, retired, or deliberately omitted;
+- structural, routing, security, behavioral, test, transfer, and field evidence appropriate to the tier;
+- fixed rubric and experiment versions, edit budget, accepted and rejected hypotheses, and stopping rule;
+- field acceptance check IDs, permitted gaps, complete causal execution counts, cleanup, and any remediation lineage;
+- repairs, regressions, effect size, uncertainty, context and runtime costs;
+- residual risk and proof that remains unavailable;
+- exact commands, artifacts, and fingerprints a maintainer can rerun.
+
+A concise draft with honest missing evidence is acceptable. An unverified claim of exceptional quality is not.