mirror of
https://github.com/openprose/prose.git
synced 2026-09-19 05:55:05 +08:00
irl-dan
63c8ce4b23
Move the standard library (previously `github.com/openprose/std`) and
the company-as-prose library (previously local dir
`/Users/sl/code/openprose/company-as-prose`) into this repository
under `packages/std/` and `packages/co/` respectively.
Motivation: concentrate attention on one repository so stars,
discussions, and issues aggregate. `openprose/std` was a genuinely
useful asset nobody could find because ~50 stars on its own repo
told a much worse story than 1,106 stars on `openprose/prose`
would have. Same logic applies to co.
Layout choice: `packages/{std,co}/` rather than `std/` + `co/` at
the repo root. Root siblings accumulate over time, and a flat
top-level made future libraries (hub, kit, dev, etc.) compete with
spec infrastructure. `packages/` is bounded — new libraries land
there without cluttering root. Matches pnpm/Deno/monorepo tooling
conventions.
Changes:
- New: `packages/std/` (copied from openprose/std, `.git` excluded)
- New: `packages/co/` (copied from company-as-prose, README updated
for new name and location)
- `packages/std/README.md`: updated shorthand expansion reference
- `packages/co/README.md`: renamed "company-as-prose" to "co" in
self-references, added std-vs-co split heuristic, updated
`prose run` examples to use `co/` shorthand
- `skills/open-prose/deps.md`:
- `std/` shorthand now expands to
`github.com/openprose/prose/packages/std/`
- `co/` shorthand added, expands to
`github.com/openprose/prose/packages/co/`
- Both shorthands resolve into the same clone of
`openprose/prose` under `.deps/github.com/openprose/prose/`;
`packages/std/` and `packages/co/` are sibling subdirectories
- `prose.lock` format row updated to `host/owner/repo sha`
(matches the explicit-host resolution that landed in #35)
- `.deps/` directory structure example redrawn to show the
`{host}/{owner}/{repo}/packages/{std,co}/...` shape
- Error message and Interaction tables refreshed accordingly
- Resolution Algorithm step 1 now documents both shorthands
- `skills/open-prose/forme.md`: Step 2 resolution list updated to
include co/ shorthand and the host-keyed `.deps/` layout
- `skills/open-prose/help.md`: Q&A "How do dependencies work?"
rewritten to name both shorthands and the new explicit-host model
- `skills/open-prose/state/filesystem.md`: `.deps/` directory
tree re-drawn to include the `{host}/` layer with std/co as
sibling packages inside the clone
- `skills/open-prose/guidance/patterns.md`,
`skills/open-prose/guidance/antipatterns.md`: examples now use
the `std/` shorthand or explicit `github.com/...` rather than
the deprecated bare `openprose/std/` form
- `skills/open-prose/examples/registry-import/index.md`: sample
service reference switched to `std/evals/inspector`
- `README.md`: Stdlib badge replaced with internal `packages/std/`
link plus new `packages/co/` link; "Standard Library" section
rewritten as "Libraries" with both packages described
Out of scope for this PR (deliberately):
- Tooling changes to `prose install` and Forme's `.deps/` writer
to adopt the `{host}/{owner}/{repo}/` layout in practice — this
PR is spec-only. Existing tooling continues to work against
whatever layout it currently implements; the spec now describes
the target.
- Retiring the `openprose/std` GitHub repo. Delete that repo
separately after this merges.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
123 lines
5.8 KiB
Markdown
123 lines
5.8 KiB
Markdown
---
|
|
name: program-improver
|
|
kind: program
|
|
---
|
|
|
|
# Program Improver
|
|
|
|
Given an inspection report and the inspected program's source, analyze the program for improvement opportunities and produce ranked proposals with diffs. This program operates on Prose v1 programs (.md format) and understands the full contract surface: requires, ensures, errors, invariants, strategies, environment, and shapes.
|
|
|
|
### Services
|
|
|
|
- locator
|
|
- analyst
|
|
- implementer
|
|
|
|
### Requires
|
|
|
|
- inspection: run — a completed inspector run whose output identifies issues with a program
|
|
- source-path: path to the program's source directory (the .md files)
|
|
|
|
### Ensures
|
|
|
|
- improvements: ranked list of improvement opportunities, each containing:
|
|
- rank: priority position (1 = highest impact)
|
|
- category: one of "contract" (ensures/requires quality), "strategy" (missing or vague strategies), "shape" (delegation boundary violations), "structure" (service decomposition issues), "error-handling" (missing error declarations or conditional ensures), "efficiency" (unnecessary services or missing parallelization)
|
|
- description: what the problem is
|
|
- evidence: specific reference to inspection findings and program source
|
|
- diff: proposed change as a unified diff against the source file
|
|
- risk: "low" (safe refactor), "medium" (changes contract surface), or "high" (changes program behavior)
|
|
- if no improvements found: empty list with explanation of why the program is sound
|
|
|
|
### Errors
|
|
|
|
- source-not-found: the source-path does not contain valid Prose program files
|
|
- inspection-invalid: the inspection run output is not a valid inspector report
|
|
|
|
### Strategies
|
|
|
|
- when analyzing contracts: check that every ensures clause is specific enough to evaluate — vague ensures like "a good report" are improvement targets
|
|
- when analyzing strategies: check that strategies cover the program's known failure modes — if the inspection shows failures, the program should have strategies to handle them
|
|
- when analyzing shapes: verify that services with shape.delegates actually delegate (not collapse), and services with shape.prohibited do not violate boundaries
|
|
- when proposing diffs: make minimal changes — one concern per diff. Never rewrite a program wholesale.
|
|
- when ranking: prioritize contract violations and missing error handling over efficiency improvements
|
|
|
|
---
|
|
|
|
## locator
|
|
|
|
Find and read the program source files. Validate that the source path contains a valid Prose program.
|
|
|
|
### Requires
|
|
|
|
- source-path: path to the program's source directory
|
|
- inspection: the inspection run binding
|
|
|
|
### Ensures
|
|
|
|
- program-source: the entry point file content (the file with `kind: program`)
|
|
- service-sources: map of service name to file content for each service in the program
|
|
- inspection-output: the inspection report extracted from the inspection run's bindings
|
|
|
|
### Errors
|
|
|
|
- source-not-found: source-path does not exist or contains no `kind: program` file
|
|
- inspection-invalid: cannot find or parse the inspection output from the run
|
|
|
|
### Strategies
|
|
|
|
- look for the entry point by scanning .md files for `kind: program` in frontmatter
|
|
- resolve service files relative to the entry point's directory
|
|
- read the inspection output from the run's bindings directory
|
|
|
|
---
|
|
|
|
## analyst
|
|
|
|
Examine the program source against the inspection findings. Identify every improvement opportunity with evidence from both sources.
|
|
|
|
### Requires
|
|
|
|
- program-source: entry point content from locator
|
|
- service-sources: service file contents from locator
|
|
- inspection-output: inspection report from locator
|
|
|
|
### Ensures
|
|
|
|
- analysis: list of improvement opportunities, each with category, description, evidence, affected file, and estimated impact
|
|
- each opportunity has: a reference to the specific inspection finding that motivates it AND a reference to the specific source location that needs changing
|
|
|
|
### Strategies
|
|
|
|
- check contract quality: are ensures clauses specific and evaluable? are requires clauses typed clearly? are error conditions declared for plausible failure modes?
|
|
- check strategy coverage: does every service that could fail have relevant strategies? do strategies reference concrete conditions, not vague heuristics?
|
|
- check shape consistency: do shape.self lists match what the service actually does? do shape.delegates match the services list? are shape.prohibited entries respected in the service body?
|
|
- check structural efficiency: are independent services wired for parallel execution? are there services that could be merged or split?
|
|
- check error handling: does the program have conditional ensures for each declared error? are degradation paths specified?
|
|
- when the inspection shows a "pass" verdict: still look for improvements — a passing program can still have quality issues
|
|
- when the inspection shows a "fail" verdict: prioritize the root cause of failure above all other improvements
|
|
|
|
---
|
|
|
|
## implementer
|
|
|
|
Transform analysis results into concrete diffs. Each diff must be minimal, correct, and independently applicable.
|
|
|
|
### Requires
|
|
|
|
- analysis: improvement opportunities from analyst
|
|
- program-source: entry point content from locator
|
|
- service-sources: service file contents from locator
|
|
|
|
### Ensures
|
|
|
|
- improvements: the final ranked list matching the program's top-level ensures schema, with diffs generated for each opportunity
|
|
|
|
### Strategies
|
|
|
|
- when generating diffs: use unified diff format with enough context lines (3+) to unambiguously locate the change
|
|
- when multiple improvements affect the same file: ensure diffs are independently applicable (no conflicts if applied in isolation)
|
|
- when a change affects the contract surface (requires/ensures): flag as "medium" risk since downstream consumers may depend on the current contract
|
|
- when a change only affects strategies or internal service content: flag as "low" risk
|
|
- when proposing new services or removing existing ones: flag as "high" risk
|