@artale/pi-real-engineering 0.2.1 → 0.3.0

package/README.md

@@ -1,59 +1,70 @@
-# @artale/pi-real-engineering
-
-Plan → Build → Test → Review → Ship for Pi, with verifier guardrails and receipts.
-
-This is not a loose skills pack. It installs one workflow command plus the small skills that make the loop work.
-
-## Install
-
-```bash
-pi install npm:@artale/pi-real-engineering
-/reload
-```
-
-## Golden path
-
-```text
-idea → safety gate → ADW plan/build/test/review → receipt → guarded deploy
-```
-
-Run it:
-
-```text
-/real-engineering build the smallest safe version of <idea>
-```
-
-The command makes Pi:
-
-1. restate the idea
-2. run a safety gate before risky writes/commands/deploys
-3. plan/build/test/review in the smallest useful loop
-4. produce a receipt: changed files, commands run, test output, review result, deploy decision
-5. deploy only when explicitly requested and verified
-
-## Included skills
-
-| Skill | Purpose |
-|---|---|
-| `setup-artale-skills` | Create repo conventions: `AGENTS.md`, `CONTEXT.md`, `docs/adr/`, `.pi/plans/` |
-| `grill-with-docs` | Interview against docs/context before implementation |
-| `tdd` | Red-green-refactor one vertical slice at a time |
-| `diagnosing-bugs` | Reproduce, minimize, hypothesize, instrument, fix |
-| `domain-modeling` | Maintain shared language in `CONTEXT.md` and ADRs |
-| `codebase-design` | Design deep modules with small interfaces and clean seams |
-
-## Receipt format
-
-```md
-## Real Engineering Receipt
-- Idea:
-- Safety gate:
-- Plan:
-- Changed files:
-- Commands run:
-- Test output:
-- Review result:
-- Deploy decision:
-```
-
-No new infra. The workflow uses Pi commands, verifier discipline, and your existing deploy path.
+# @artale/pi-real-engineering
+
+Plan → Build → Test → Review → Ship for Pi, with verifier guardrails and receipts.
+
+This is not a loose skills pack. It installs one workflow command plus the small skills that make the loop work.
+
+## Install
+
+```bash
+pi install npm:@artale/pi-real-engineering
+/reload
+```
+
+## Golden path
+
+```text
+idea → safety gate → ADW plan/build/test/review → receipt → guarded deploy
+```
+
+Run it:
+
+```text
+/real-engineering build the smallest safe version of <idea>
+```
+
+The command makes Pi:
+
+1. restate the idea
+2. run a safety gate before risky writes/commands/deploys
+3. plan/build/test/review in the smallest useful loop
+4. produce a receipt: changed files, commands run, test output, review result, deploy decision
+5. deploy only when explicitly requested and verified
+
+## Included skills
+
+| Skill | Purpose |
+|---|---|
+| `setup-artale-skills` | Create repo conventions: `AGENTS.md`, `CONTEXT.md`, `docs/adr/`, `.pi/plans/` |
+| `grill-with-docs` | Interview against docs/context before implementation |
+| `tdd` | Red-green-refactor one vertical slice at a time |
+| `diagnosing-bugs` | Reproduce, minimize, hypothesize, instrument, fix |
+| `domain-modeling` | Maintain shared language in `CONTEXT.md` and ADRs |
+| `codebase-design` | Design deep modules with small interfaces and clean seams |
+
+## Receipt format
+
+```md
+## Real Engineering Receipt
+- Idea:
+- Safety gate:
+- Plan:
+- Changed files:
+- Commands run:
+- Test output:
+- Review result:
+- Deploy decision:
+```
+
+No new infra. The workflow uses Pi commands, verifier discipline, and your existing deploy path.
+
+## Package aliases
+
+Both packages install the same workflow:
+
+```bash
+pi install npm:pi-real-engineering
+pi install npm:@artale/pi-real-engineering
+```
+
+Prefer `npm:pi-real-engineering` for the short golden path install.

package/docs/receipts/singularity-proof-20260619.md

@@ -0,0 +1,159 @@
+# Codebase Singularity proof — 2026-06-19
+
+## Idea
+Prove the Pi/Artale agentic layer can run the golden path with live truth:
+
+```text
+idea → safety gate → ADW plan/build/test/review → receipt → guarded deploy decision
+```
+
+## Safety gate
+Allowed:
+
+- one local receipt file write
+- read-only package/version checks
+- read-only command-contract grep
+- read-only factory status request
+- read-only live Docker count/list over SSH
+- read-only git diff/status checks
+
+Forbidden:
+
+- no deploy
+- no npm publish
+- no service/container restart
+- no secret access
+- no runtime/package code changes
+- no new infra
+
+## ADW plan/build/test/review
+
+### Plan
+Create exactly one receipt proving the current singularity substrate and recording the stale factory-status mismatch.
+
+### Build
+Created this file only:
+
+```text
+packages/pi-real-engineering/docs/receipts/singularity-proof-20260619.md
+```
+
+### Test
+Ran read-only checks and captured output below.
+
+### Review
+Diff must be limited to this receipt file. Any runtime/package file change means `ISSUES`.
+
+### Ship / deploy decision
+
+```text
+NO DEPLOY
+```
+
+Reason: this is documentation/proof only. Factory state is also partially stale (`factory-status` says 25 containers, live Docker says 13), so deploy is explicitly forbidden by the safety gate.
+
+## Commands run and outputs
+
+### Package version
+
+```bash
+node -e "const p=require('./packages/pi-real-engineering/package.json'); console.log(p.name, p.version)"
+```
+
+Output:
+
+```text
+@artale/pi-real-engineering 0.2.2
+```
+
+### Golden-path command contract
+
+```bash
+grep -n "idea → safety gate" packages/pi-real-engineering/extensions/real-engineering.ts
+```
+
+Output:
+
+```text
+9:idea → safety gate → ADW plan/build/test/review → receipt → guarded deploy
+```
+
+### Factory status endpoint
+
+```bash
+curl -fsS --max-time 5 http://77.42.112.29:8099/factory-status
+```
+
+Output:
+
+```json
+{"status": "ok", "phase": 4, "containers": 25, "agents": 6, "infra": 14, "monitoring": 5, "skills": 63}
+```
+
+### Live Docker count
+
+```bash
+ssh -o BatchMode=yes -o ConnectTimeout=8 engine 'docker ps --format "{{.Names}}" | wc -l'
+```
+
+Output:
+
+```text
+13
+```
+
+### Live Docker containers
+
+```bash
+ssh -o BatchMode=yes -o ConnectTimeout=8 engine 'docker ps --format "{{.Names}}" | sort'
+```
+
+Output:
+
+```text
+cloudflared
+deploy-webhook
+docs-site
+forgejo
+fullyhermes
+hermes
+mc-postgres
+mission-control
+openvoiceui
+qdrant
+redis
+site-fdsa-ai
+site-n-art-io
+```
+
+## Live-truth reconciliation
+
+```text
+STALE_FACTORY_STATE
+```
+
+`factory-status.containers=25` conflicts with `live_docker_count=13`.
+
+Rule: **live Docker/API probes beat memory and catalog summaries when they disagree.**
+
+## Verification criteria
+
+PASS only if:
+
+- package version is `@artale/pi-real-engineering 0.2.2`
+- `/real-engineering` command contract contains the golden path
+- this receipt exists
+- changed files are limited to this receipt unless explicitly approved
+- deploy decision is `NO DEPLOY`
+
+## Residual risks
+
+- `/factory-status` still reports stale container count.
+- No production deploy was attempted or proven in this proof.
+- This proves the receipt/golden-path discipline, not full autonomous production shipping.
+
+## Result
+
+PASS for documentation-only Codebase Singularity proof.
+
+ISSUES remain for factory-status live-state drift until the endpoint reports live container truth or explicitly labels catalog counts as advisory.

package/extensions/real-engineering.ts

@@ -8,12 +8,36 @@ export default function (pi: ExtensionAPI) {
 Golden path:
 idea → safety gate → ADW plan/build/test/review → receipt → guarded deploy
 
-Rules:
-1. Stop adding features outside the requested idea.
-2. Safety gate first: identify risky writes/commands/deploys and ask before dangerous actions.
-3. Use the smallest ADW loop that fits: plan → build → test → review.
-4. Produce a receipt with: changed files, commands run, test output, review result, deploy decision.
-5. Guarded deploy only if checks actually passed. If deploy is not requested or not verified, say so.
+Safety gate:
+- Identify writes, deletes, network calls, deploys, secret access, and shell commands before doing them.
+- Ask before dangerous or irreversible actions.
+- Stop if the requested outcome is unclear.
+
+ADW loop:
+1. Plan the smallest useful change.
+2. Build only that change.
+3. Test with one command that would fail if the change broke.
+4. Review the diff as if you did not write it.
+5. Ship/deploy only when explicitly requested and verified.
+
+Verifier rule:
+- PASS only when checks actually ran.
+- If tests, runtime, publish/install, or deploy state are not verified, say ISSUES/Unverifiable.
+- No loop: perform one pass per request and do not rework the same unresolved issue indefinitely; if a loop would continue without new evidence, stop and report \`ISSUES/No progress loop\`.
+- Deployment is evidence-scoped: if you claim any \`auto_patch_proven\` status, cite a concrete receipt path and the exact recovery command/output that proves it.
+
+Receipt required:
+## Real Engineering Receipt
+- Idea:
+- Safety gate:
+- Plan:
+- Changed files:
+- Commands run:
+- Test output:
+- Review result:
+- Auto-patch proof receipts (if applicable):
+- Deploy decision:
+- Residual risks:
 
 Start by restating the idea and the safety gate.`,
   });

package/package.json

@@ -1,34 +1,35 @@
-{
-  "name": "@artale/pi-real-engineering",
-  "version": "0.2.1",
-  "description": "Real Engineering Workflow for Pi: Plan \u2192 Build \u2192 Test \u2192 Review \u2192 Ship with verifier guardrails and receipts.",
-  "license": "MIT",
-  "type": "module",
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "pi-skill",
-    "real-engineering",
-    "adw",
-    "verifier",
-    "receipts"
-  ],
-  "files": [
-    "README.md",
-    "extensions/**/*",
-    "skills/**/*",
-    "docs/receipts/**/*"
-  ],
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
-  },
-  "pi": {
-    "extensions": [
-      "./extensions"
-    ],
-    "skills": [
-      "./skills"
-    ]
-  }
-}
+{
+  "name": "@artale/pi-real-engineering",
+  "version": "0.3.0",
+  "description": "Real Engineering Workflow for Pi: Plan → Build → Test → Review → Ship with verifier guardrails and receipts.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-skill",
+    "real-engineering",
+    "adw",
+    "verifier",
+    "receipts"
+  ],
+  "files": [
+    "README.md",
+    "extensions/**/*",
+    "skills/**/*",
+    "docs/receipts/**/*"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.44.0"
+  },
+  "pi": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"],
+    "commands": ["real-engineering"]
+  },
+  "scripts": {
+    "build": "cd ../../ && npx tsc --noEmit --skipLibCheck --project tsconfig.json",
+    "test": "pi -ne --no-tools -e extensions/real-engineering.ts -p \"real-engineering loaded\""
+  }
+}