morphisms 0.1.0-beta.1

package/templates/contract/schemas/plan-review.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "description": "Rigorous-lane plan review. PASS is the closing artifact for ready rigorous plans; REVISE loops to scoping.",
+  "required": ["review_round", "reviewed_plan_round", "gate", "review_summary"],
+  "additionalProperties": false,
+  "properties": {
+    "review_round": {"type": "integer", "minimum": 1, "description": "Monotone review attempt number for this rigorous issue."},
+    "reviewed_plan_round": {"type": "integer", "minimum": 1, "description": "The scoped_plan.plan_round this review evaluates."},
+    "gate": {"type": "string", "enum": ["PASS", "REVISE"]},
+    "review_summary": {"type": "string", "minLength": 1},
+    "review_outcome": {"type": "string", "enum": ["ready_for_execution"]},
+    "required_changes": {"type": "array", "items": {"type": "string", "minLength": 1}, "default": []},
+    "risk_notes": {"type": "array", "items": {"type": "string", "minLength": 1}, "default": []}
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"gate": {"const": "PASS"}}, "required": ["gate"]},
+      "then": {"required": ["review_outcome"], "properties": {"review_outcome": {"const": "ready_for_execution"}}}
+    },
+    {
+      "if": {"properties": {"gate": {"const": "REVISE"}}, "required": ["gate"]},
+      "then": {"required": ["required_changes"], "properties": {"required_changes": {"minItems": 1}}}
+    }
+  ]
+}

package/templates/contract/schemas/scoped-plan.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "description": "Scoped front-half plan and handoff prompt, or a blocked outcome with explanation.",
+  "required": ["plan_round", "plan_outcome", "problem", "evidence", "approach", "acceptance_criteria", "handoff_prompt"],
+  "additionalProperties": false,
+  "properties": {
+    "plan_round": {"type": "integer", "minimum": 1, "description": "Monotone review-loop round for rigorous lane; increment after each REVISE."},
+    "based_on_review_round": {"type": "integer", "minimum": 1, "description": "Prior REVISE review_round this plan answers, when applicable."},
+    "plan_outcome": {"type": "string", "enum": ["ready_for_execution", "blocked"]},
+    "problem": {"type": "string", "minLength": 1},
+    "evidence": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "approach": {"type": "string", "minLength": 1},
+    "acceptance_criteria": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "handoff_prompt": {"type": "string", "minLength": 1},
+    "blocker": {"type": "string", "minLength": 1},
+    "non_goals": {"type": "array", "items": {"type": "string", "minLength": 1}, "default": []}
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"plan_outcome": {"const": "blocked"}}, "required": ["plan_outcome"]},
+      "then": {"required": ["blocker"]}
+    }
+  ]
+}

package/templates/contract/schemas/triage-decision.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "description": "Triage evidence choosing the issue lane or closing as discarded/duplicate.",
+  "required": ["decision", "rationale"],
+  "additionalProperties": false,
+  "properties": {
+    "decision": {"type": "string", "enum": ["quick", "standard", "rigorous", "discard", "duplicate"]},
+    "rationale": {"type": "string", "minLength": 1},
+    "signals": {"type": "array", "items": {"type": "string", "minLength": 1}, "default": []},
+    "closing_outcome": {"type": "string", "enum": ["discarded", "duplicate"]},
+    "duplicate_of": {"type": "string", "minLength": 1},
+    "operator_question": {"type": "string", "minLength": 1}
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"decision": {"const": "discard"}}, "required": ["decision"]},
+      "then": {"required": ["closing_outcome"], "properties": {"closing_outcome": {"const": "discarded"}}}
+    },
+    {
+      "if": {"properties": {"decision": {"const": "duplicate"}}, "required": ["decision"]},
+      "then": {"required": ["closing_outcome", "duplicate_of"], "properties": {"closing_outcome": {"const": "duplicate"}}}
+    }
+  ]
+}

package/templates/instructions/starter-issues-agent-manual.md

@@ -0,0 +1,232 @@
+# Starter issues distro instructions
+
+This is the S3 distro layer for `starter_issues_front_half/v1`.
+
+## Contract map
+
+- Store: `issues`; CLI alias: `issue`; ids: `ISS0001`, `ISS0002`, ...
+- Fields accepted at add time: `title`, `kind`, `summary`. `kind` is `bug | idea | feature`. `priority`, `reporter_context`, and `source_anchor` default at add time.
+- Dimensions:
+  - `journey`: `triage` initial; `investigating`; `scoping`; `plan_review`; `done` terminal.
+  - `attention`: `autonomous_entry` initial; `autonomous`; `awaiting_operator`.
+- Personas:
+  - `journey.triage` -> `triager`
+  - `journey.investigating` -> `investigator`
+  - `journey.scoping` -> `scoper`
+  - `journey.plan_review` -> `plan-reviewer`
+  - `attention.awaiting_operator` -> `operator-facing-intake`
+
+## Actionability
+
+- Human-only: `attention.awaiting_operator`. Stop, summarize the ambiguity, and wait for `operator_decision`.
+- Agent-actionable: `journey.triage`, `journey.investigating`, `journey.scoping`, `journey.plan_review`, `attention.autonomous_entry`, `attention.autonomous`.
+- Terminal: `journey.done` means this record's front-half journey is complete. Read the typed outcome evidence to know whether it was ready, blocked, duplicate, or discarded.
+- No automatic task materialization. This front half ends at `journey.done` with a typed outcome artifact and, for ready work, a `scoped_plan.handoff_prompt`.
+
+## Artifacts
+
+- `triage_decision`: `decision` is `quick | standard | rigorous | discard | duplicate`; include `rationale`, `signals[]` when useful, and `operator_question` only if human ambiguity must route through attention; use `closing_outcome` for discard/duplicate and `duplicate_of` for duplicate.
+- `investigation_report`: `finding` is `confirmed | not_reproduced | needs_scope | blocked`; include `summary`; `citations` must be non-empty with `{file,line,excerpt,why_it_matters}`; include `reproduction_steps[]` and `open_questions[]` as applicable.
+- `scoped_plan`: include `plan_round`, optional `based_on_review_round`, `plan_outcome` (`ready_for_execution | blocked`), `problem`, `evidence`, `approach`, `acceptance_criteria`, `handoff_prompt`; include `blocker` when blocked and `non_goals[]` when useful.
+- `plan_review`: rigorous lane only; include `review_round`, `reviewed_plan_round`, `gate` (`PASS | REVISE`), `review_summary`, and `risk_notes[]` (`[]` is acceptable); include `review_outcome=ready_for_execution` for PASS or `required_changes[]` for REVISE.
+- `operator_decision`: human answer for attention; `decision` is `resume | revise_scope`; include `rationale`, optional `instructions`, and `answered_questions[]`.
+
+Rigorous PASS example: `{"review_round":1,"reviewed_plan_round":1,"gate":"PASS","review_summary":"Ready with manageable risk.","review_outcome":"ready_for_execution","risk_notes":[]}`. Rigorous REVISE example: `{"review_round":1,"reviewed_plan_round":1,"gate":"REVISE","review_summary":"Needs narrower scope.","required_changes":["Split risky migration out."],"risk_notes":["Migration touches auth flow."]}`.
+
+## Edges
+
+Journey:
+
+- `journey.choose_quick_scope`: `triage` -> `scoping`, requires latest `triage_decision.decision=quick`.
+- `journey.choose_standard_investigation`: `triage` -> `investigating`, requires latest `triage_decision.decision=standard`.
+- `journey.choose_rigorous_investigation`: `triage` -> `investigating`, requires latest `triage_decision.decision=rigorous`.
+- `journey.close_discarded_from_triage`: `triage` -> `done`, requires `decision=discard` and `closing_outcome=discarded`.
+- `journey.close_duplicate_from_triage`: `triage` -> `done`, requires `decision=duplicate`, `closing_outcome=duplicate`, and `duplicate_of`.
+- `journey.submit_standard_investigation`: `investigating` -> `scoping`, requires standard `triage_decision` and latest `investigation_report`.
+- `journey.submit_rigorous_investigation`: `investigating` -> `scoping`, requires rigorous `triage_decision` and latest `investigation_report`.
+- `journey.complete_scoped_plan`: `scoping` -> `done`, requires `scoped_plan.plan_outcome=ready_for_execution` and quick or standard triage.
+- `journey.close_blocked_from_scoping`: `scoping` -> `done`, requires `scoped_plan.plan_outcome=blocked`.
+- `journey.submit_rigorous_plan_review`: `scoping` -> `plan_review`, requires rigorous triage, investigation, ready scoped plan, and a scoped plan fresh after the latest revise loop.
+- `journey.revise_rigorous_plan`: `plan_review` -> `scoping`, requires fresh `plan_review.gate=REVISE`.
+- `journey.approve_rigorous_plan`: `plan_review` -> `done`, requires fresh `plan_review.gate=PASS` and `review_outcome=ready_for_execution`.
+
+Attention:
+
+- `attention.start_autonomous`: `autonomous_entry` -> `autonomous`.
+- `attention.request_operator_from_entry`: `autonomous_entry` -> `awaiting_operator`.
+- `attention.request_operator`: `autonomous` -> `awaiting_operator`.
+- `attention.return_to_autonomous`: `awaiting_operator` -> `autonomous`, requires latest `operator_decision`.
+
+## Normal loop
+
+1. List frontier: `mor issue ls`.
+2. Hydrate current node: `mor issue hydrate <id> <dimension.state>`.
+3. Use the persona/context packet. Produce only the artifact this node is authorized to produce.
+4. Attach evidence: `mor issue enrich <id> <artifact_kind> --role <role> --payload <file>`.
+5. Walk one edge: `mor issue walk <id> <dimension.edge>`.
+6. Verify with `mor issue inspect <id>` or by hydrating the new node.
+
+## Concierge onboarding
+
+If `.mor/onboarding-complete` does **not** exist, you are in concierge mode. Do this before normal orchestration.
+
+### 1. Ask for one real annoyance
+
+Say:
+
+> Let's make this real. Give me one bug, annoyance, or confusing behavior in this repo. If you do not have one ready, I can scan the repo and propose one small first issue.
+
+If the human gives an issue, file it. If they ask you to scan, inspect files normally and choose a small truthful annoyance grounded in the repo.
+
+Create the first issue with only add-accepted fields:
+
+```json
+{"title":"<short title>","kind":"bug","summary":"<human words plus any repo clue>"}
+```
+
+```bash
+mor issue add --payload /tmp/morphisms-first-issue.json
+```
+
+Narrate: "I filed the first `issue` record. The graph should now show it at `journey.triage` and `attention.autonomous_entry` in Workbench: http://localhost:4400/#workbench."
+
+### 2. Hydrate and explain the packet
+
+Run:
+
+```bash
+mor issue hydrate <id> journey.triage
+```
+
+Narrate the first occurrence: "Hydration is the handoff packet: record fields, persona, context, legal edges, and missing witnesses. I follow this packet instead of guessing."
+
+### 3. Show one deliberate refusal
+
+Before attaching `triage_decision`, intentionally attempt the standard lane once:
+
+```bash
+mor issue walk <id> journey.choose_standard_investigation
+```
+
+Expect a blocked/refused result such as a missing `triage_decision` witness. Narrate: "This refusal is the safety rail. MOR will not let me move the graph until the typed evidence exists."
+
+### 4. Triage into a real investigation lane
+
+Attach a standard triage decision unless the issue truly needs rigorous review:
+
+```json
+{"decision":"standard","rationale":"Needs one file/line investigation before scoping.","signals":["<signal>"]}
+```
+
+```bash
+mor issue enrich <id> triage_decision --role triage_decision --payload /tmp/triage.json
+mor issue walk <id> journey.choose_standard_investigation
+mor issue hydrate <id> journey.investigating
+```
+
+Narrate the graph movement in Workbench.
+
+### 5. Investigate with citations
+
+Do a real repo read. The `investigation_report.citations` array must be non-empty and cite real file lines:
+
+```json
+{
+  "finding":"confirmed",
+  "summary":"<what the code showed>",
+  "citations":[{"file":"path/to/file","line":123,"excerpt":"<exact excerpt>","why_it_matters":"<why>"}],
+  "reproduction_steps":["<step>"],
+  "open_questions":[]
+}
+```
+
+```bash
+mor issue enrich <id> investigation_report --role investigation_report --payload /tmp/investigation.json
+mor issue walk <id> journey.submit_standard_investigation
+mor issue hydrate <id> journey.scoping
+```
+
+### 6. Scope to a typed front-half outcome
+
+Attach a scoped plan with a handoff prompt:
+
+```json
+{
+  "plan_round":1,
+  "plan_outcome":"ready_for_execution",
+  "problem":"<problem>",
+  "evidence":["path/to/file:123 <fact>"],
+  "approach":"<approach>",
+  "acceptance_criteria":["<criterion>"],
+  "handoff_prompt":"<prompt another agent can execute>",
+  "non_goals":[]
+}
+```
+
+```bash
+mor issue enrich <id> scoped_plan --role scoped_plan --payload /tmp/scoped-plan.json
+mor issue inspect <id>
+```
+
+If the honest outcome is blocked, set `plan_outcome=blocked` and include `blocker`; do not close the journey until after the human-collab step below.
+
+### 7. Route one real human-collab moment
+
+After the scoped plan is attached and before closing the journey, route the record to the human in the `attention` dimension. First inspect the current attention state:
+
+```bash
+mor issue inspect <id>
+```
+
+If `attention=autonomous_entry`, run:
+
+```bash
+mor issue walk <id> attention.request_operator_from_entry
+```
+
+If `attention=autonomous`, run:
+
+```bash
+mor issue walk <id> attention.request_operator
+```
+
+Tell the human: "The record is now waiting for YOU at `attention.awaiting_operator`. In an armed Workbench thread, this is the `Review now` moment; otherwise use the record card in Workbench: http://localhost:4400/#workbench. Please answer whether I should resume and close this scoped plan, or revise scope."
+
+Use the human's actual answer as the `operator_decision`; do not fabricate it. For a resume answer, attach:
+
+```json
+{"decision":"resume","rationale":"<human's answer>","instructions":"Proceed with the scoped plan outcome.","answered_questions":["Resume and close this scoped plan?"]}
+```
+
+```bash
+mor issue enrich <id> operator_decision --role operator_decision --payload /tmp/operator-decision.json
+mor issue walk <id> attention.return_to_autonomous
+```
+
+Narrate: "This is how future work pauses only when it needs you, then resumes after your typed decision."
+
+### 8. Close the journey
+
+For a ready quick/standard scoped plan, close with:
+
+```bash
+mor issue walk <id> journey.complete_scoped_plan
+mor issue inspect <id>
+```
+
+For a blocked scoped plan, close with:
+
+```bash
+mor issue walk <id> journey.close_blocked_from_scoping
+mor issue inspect <id>
+```
+
+### 9. Complete onboarding
+
+When the first record reaches `journey.done`, write the sentinel:
+
+```bash
+printf '%s %s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "<id>" > .mor/onboarding-complete
+```
+
+Tell the human: "Onboarding is complete. Normal Morphisms mode is now on; future records will start from the frontier loop."

package/templates/instructions/workspace-agent-manual.md

@@ -0,0 +1,22 @@
+# Morphisms workspace instructions
+
+This is the S2 workspace layer for a repo initialized by `morphisms init`. It applies across local distros in this repo.
+
+## Startup
+
+- Run `mor agent instructions` before orchestrating. Read the reported S1/S2/S3 files; use `mor agent instructions preview` only when you need the rendered stack.
+- Workbench is the lens: `http://localhost:4400/#workbench` unless `.morphisms-contract/config.json` says a different `workbench_port`.
+- Keep runtime state under `.mor/`. Do not edit SQLite files or registry material by hand.
+- Do not create `.mor/onboarding-complete`; the onboarding agent writes it only after the first real issue reaches `journey.done`.
+
+## Thread narration
+
+- If this session is inside a MOR Workbench thread capsule, reply in the thread with `mor-thread reply` and use `mor-thread suggest` for consent-gated viewer movement.
+- If this is a normal terminal agent session, narrate progress in the current conversation and include the Workbench deep-link.
+- Keep narration short: what node was hydrated, what evidence was attached, what edge was walked or refused, and where the record is now.
+
+## Local command posture
+
+- Prefer compact human output while narrating. Add `--json` only when you need machine parsing.
+- Use `mor --help` when syntax is uncertain. Do not guess command forms.
+- Treat MOR refusals as evidence gates working correctly. Never bypass with direct DB edits.

package/templates/manifest.json

@@ -0,0 +1,22 @@
+[
+  {
+    "src": "claude/skills/morphisms/SKILL.md",
+    "dest": "{repo}/.claude/skills/morphisms/SKILL.md",
+    "when": "claude"
+  },
+  {
+    "src": "agent/skills/morphisms/SKILL.md",
+    "dest": "{repo}/.agent/skills/morphisms/SKILL.md",
+    "when": "agent"
+  },
+  {
+    "src": "instructions/workspace-agent-manual.md",
+    "dest": "{repo}/.mor/agent-manual.md",
+    "when": "always"
+  },
+  {
+    "src": "instructions/starter-issues-agent-manual.md",
+    "dest": "{repo}/.morphisms-contract/issues_front_half/agent-manual.md",
+    "when": "always"
+  }
+]