ultimate-pi 0.19.1 → 0.22.0

package/.pi/harness/docs/practice-map.md

@@ -23,7 +23,7 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 1. **Parallelism law** — Parallel `subagent` `tasks` only when outputs are independent inputs to a later merge (implementation ∥ stack research; inspector ∥ adversary in `parallel_probes`). Never parallelize decompose ∥ hypothesis.
 2. **Two-pizza cap per batch** — Max 2 research lanes, max 1 optional `planning-context` subagent, max 1 executor, max 1 debate lane agent per `subagent` call (plan-verify may use 2 probes + integrator in separate batches).
 3. **No redundant thinkers** — If artifact X exists, downstream agents read it; they do not re-derive (e.g. decompose after `planning-context.yaml`).
-4. **Sequential dependency chain** — planning context → problem framing / decompose → hypothesis → research → synthesis/author → DAG → plan-verify → approve → execute → review → (steer)* → policy.
+4. **Sequential dependency chain** — task clarification → planning context → problem framing / decompose → hypothesis → research → synthesis/author → DAG → plan-verify → approve → execute → review → (steer)* → policy.
 5. **Plan-verify (agent-native)** — For `fast`/`standard`, parallel probes then integrator; parent is chair, not participant. Threaded debate remains for `full` until parity.
 6. **Tool intelligence** — Parent chooses graphify, sg, ccc; subprocesses optional. **Path-first:** disk is source of truth; tool args are pointers (ADR 0043).
 
@@ -31,8 +31,9 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 
 | Phase | Practice | Agent translation | Actor | Spawn |
 |-------|----------|---------------------|-------|-------|
-| 0 | Tooling / fast feedback | Pre-index once | Parent + `ccc` | Automatic |
-| 1 | Reconnaissance before WBS | **ContextPack** on disk | Parent tools or optional `planning-context` | No default subprocess |
+| 0 | Task clarification | Task contract on disk; code + web OK | Parent + `ask_user` | No subprocess |
+| 0a | Tooling / fast feedback | Pre-index once | Parent + `ccc` | Automatic |
+| 1 | Reconnaissance before WBS | **ContextPack** on disk | Parent tools or optional `planning-context` | After task-clarification gate |
 | 2a | Problem framing / lakes | Lake outcomes, not ticket tree | `decompose` or synthesizer section | Sequential after context gate |
 | 2b | Hypothesis-driven approach | Falsifiable claim grounded in framing | `hypothesis` or synthesizer | After `artifacts/decomposition.yaml` |
 | 3.5 | Spike / external research | Paths in research brief | Researchers optional | Artifacts required |
@@ -41,6 +42,8 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 | 4c | Deterministic quality gate | Script, not LLM | `validate-plan-dag.mjs` | Parent; hard stop |
 | 4d | Tailor process to risk | Probe depth, not meeting count | `harness_plan_debate_eligibility` | Pre plan-verify |
 | 4e | Architectural intent | Fitness-function spec | `harness/sentrux-steward` optional | When structural risk |
+| 4e″ | Structural repair plan | OSS diagnostics → actions | `harness/sentrux-repair-advisor` | `/harness-review` when violations/degraded |
+| 4e′ | Naming intent | Filename convention spec | `harness/ls-lint-steward` optional | New paths/extensions |
 | 5 | Plan-verify (Review Gate) | Parallel probes + integrator | Debate cast / probes | `parallel_probes` or threaded |
 | 6 | Baseline + approve | Path-only `approve_plan` | Parent | `approve_plan`, `create_plan` |
 
@@ -69,17 +72,29 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 | Step | Practice | Agent translation | Actor |
 |------|----------|-------------------|-------|
 | Gate | Change control | `plan_ready` required | Parent |
-| Pre-work | Fitness baseline | `sentrux gate --save` | Parent |
+| Pre-work | Fitness baseline | `sentrux gate --save` + ls-lint pre-check | Parent |
 | Work | Single implementer | `executor_strategy` | `harness/running/executor` |
-| Post-work | Observation | `sentrux check` / signal artifact | Parent |
+| Post-work | Observation | `harness-sentrux-report.mjs` + diagnostics; ls-lint signal | Parent |
 | Handoff | Generator–evaluator | `submit_executor_handoff` | Executor |
 | Next | Always verify | **`/harness-review`** (not replan on blocked) | Parent routing |
 
+
+### Executor edit discipline (ADR 0051)
+
+| Practice | Agent rule |
+|----------|------------|
+| Hash-anchored targeting | `read` → `Anchor§line`; `edit` uses anchors (default harness tools) |
+| Batching | All edits per file in one `edit`; independent files same turn when safe |
+| Pre-handoff verify | Run `acceptance_checks`; clear lens blockers; then `submit_executor_handoff` |
+| Structural refactor | `sg -p` locate → read slice → anchored edit — no `replace_symbol` tools |
+| Code search | `sg` / `ccc` only — not `grep`/`find` on executor |
+
 ## `/harness-review` — Monitoring and Controlling
 
 | Phase | Practice | Agent translation | Actor |
 |-------|----------|-------------------|-------|
 | 1 | Automated QC + fitness | Deterministic first | Parent scripts |
+| 1b | Structural repair plan | OSS diagnostics → actions | `sentrux-repair-advisor` |
 | 2 | Measure vs plan | Benchmark on disk | `evaluator` benchmark |
 | 3 | Policy audit | Verdict (no fail-fast skip) | `evaluator` verdict |
 | 4 | Red team | Tiered: full attempt 1, lite 2+ steer | `adversary` |
@@ -100,6 +115,7 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 
 ## Anti-patterns
 
+- **Do not** write `planning-context.yaml` or spawn planning subagents before `artifacts/task-clarification.yaml` is `ready` (enforced in `write_harness_yaml`, spawn topology, `approve_plan`).
 - **Do not** spawn `decompose` and `hypothesis` in the same parallel `tasks` batch.
 - **Do not** run `graphify query` in `decompose` when planning-context coverage is ok (ADR 0041).
 - **Do not** parallelize threaded debate lanes in one batch (except `parallel_probes` inspector ∥ adversary per ADR 0042).

package/.pi/harness/evals/smoke/ls-lint-stub.json

@@ -0,0 +1,10 @@
+{
+	"schema_version": "1.0.0",
+	"run_id": "smoke",
+	"lint_pass": true,
+	"violation_count": 0,
+	"status": "pass",
+	"quality_signal_summary": "smoke stub for harness-verify when no run signal",
+	"recorded_at": "2026-05-26T00:00:00.000Z",
+	"phase": "evaluate"
+}

package/.pi/harness/evolution/self-healing-rules.json

@@ -23,6 +23,22 @@
 				"drift_score_gte": 0.65
 			},
 			"suggestion": "User must harness-drift-replan or harness-drift-proceed with ack."
+		},
+		{
+			"id": "sentrux-gate-degraded",
+			"match": {
+				"customType": "harness-sentrux-signal",
+				"gate_status": "degraded"
+			},
+			"suggestion": "Run /harness-review Phase 1b (sentrux-repair-advisor); steer on implementation_gap; do not tune manifest on one noisy gate."
+		},
+		{
+			"id": "sentrux-check-fail",
+			"match": {
+				"customType": "harness-sentrux-signal",
+				"check_pass": false
+			},
+			"suggestion": "Read artifacts/sentrux-diagnostics.json; spawn sentrux-repair-advisor or sentrux-steward if boundary/layer rules need intent change."
 		}
 	]
 }

package/.pi/harness/ls-lint/naming.manifest.json

@@ -0,0 +1,128 @@
+{
+	"schema_version": "1.0.0",
+	"project": "ultimate-pi",
+	"global_rules": {
+		".*": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".md": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".ts": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".tsx": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".mjs": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".js": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".json": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".yaml": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".yml": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".toml": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".py": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".sh": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".css": "regex:^[a-z]+(?:-[a-z]+)*$",
+		".html": "regex:^[a-z]+(?:-[a-z]+)*$"
+	},
+	"scoped_rules": [
+		{
+			"path": ".pi/harness/docs/adrs",
+			"rules": {
+				".md": "regex:^\\d{4}-[a-z-]+$|^template$"
+			}
+		},
+		{
+			"path": ".agents/skills",
+			"rules": {
+				".dir": "kebab-case",
+				".md": "regex:^SKILL\\.md$"
+			}
+		},
+		{
+			"path": "scripts",
+			"rules": {
+				".dir": "kebab-case"
+			}
+		},
+		{
+			"path": "docs",
+			"rules": {
+				".dir": "kebab-case"
+			}
+		},
+		{
+			"path": ".pi/scripts",
+			"rules": {
+				".dir": "snake_case"
+			}
+		},
+		{
+			"path": ".pi/agents",
+			"rules": {
+				".dir": "kebab-case"
+			}
+		}
+	],
+	"ignores": [
+		".git",
+		"node_modules",
+		"graphify-out",
+		"graphify-books-out",
+		"vendor",
+		"dist",
+		"build",
+		"coverage",
+		".web",
+		".cursor",
+		".github",
+		".agents",
+		".pi/npm",
+		".pi/harness/runs",
+		".pi/harness/debates",
+		".pi/harness/.lens",
+		".pi/wiki-search",
+		".cocoindex_code",
+		".sentrux",
+		".ls-lint",
+		".searxng",
+		".vault-meta",
+		".raw",
+		"raw",
+		"data",
+		"**/__pycache__/**",
+		"submissions",
+		"jobs",
+		"pl",
+		"**/*.png",
+		"**/*.jpg",
+		"**/*.jpeg",
+		"**/*.gif",
+		"**/*.webp",
+		"**/*.ico",
+		"**/*.svg",
+		"package-lock.json",
+		"pnpm-lock.yaml",
+		"yarn.lock",
+		"*.lock",
+		"README.md",
+		"**/README.md",
+		"SKILL.md",
+		"**/SKILL.md",
+		"CHANGELOG.md",
+		"LICENSE",
+		"AGENTS.md",
+		"CONTRIBUTING.md",
+		"THIRD_PARTY_NOTICES.md",
+		".env.example",
+		"skills-lock.json",
+		".fallow-baseline.json",
+		".graphify_detect.json",
+		".graphify_python",
+		".graphify_root",
+		".graphify_incremental.json",
+		".pi/SYSTEM.md",
+		".pi/PACKAGING.md",
+		"**/.*",
+		".pi/sounds",
+		".pi/harness/evals",
+		".pi/extensions/00-harness-project-control.ts",
+		"DOCS_BY_AUDIENCE.md",
+		"GLOSSARY.md",
+		"REPO_MAP.md",
+		"START_HERE.md",
+		"WORKFLOW_CHEAT_SHEET.md"
+	]
+}

package/.pi/harness/sentrux/architecture.manifest.json

@@ -4,7 +4,7 @@
 	"constraints": {
 		"max_cycles": 0,
 		"max_coupling": "B",
-		"max_cc": 35,
+		"max_cc": 25,
 		"no_god_files": true
 	},
 	"layers": [

package/.pi/harness/specs/auto-commit.schema.json

@@ -0,0 +1,63 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/auto-commit.schema.json",
+	"title": "AutoCommitConfig",
+	"description": "Harness auto-commit: co-author trailers, message templates, branch/push hints.",
+	"type": "object",
+	"additionalProperties": true,
+	"properties": {
+		"dryRun": { "type": "boolean" },
+		"coAuthor": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["login", "email"],
+			"properties": {
+				"login": { "type": "string", "minLength": 1 },
+				"email": { "type": "string", "minLength": 3 },
+				"required": { "type": "boolean" }
+			}
+		},
+		"branch": {
+			"type": "object",
+			"additionalProperties": true,
+			"properties": {
+				"strategy": { "type": "string" },
+				"protected": {
+					"type": "array",
+					"items": { "type": "string" }
+				}
+			}
+		},
+		"push": {
+			"type": "object",
+			"additionalProperties": true,
+			"properties": {
+				"allowedRemotes": {
+					"type": "array",
+					"items": { "type": "string" }
+				}
+			}
+		},
+		"submodules": {
+			"type": "object",
+			"additionalProperties": true,
+			"properties": {
+				"ignore": { "type": "boolean" }
+			}
+		},
+		"message": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["template", "coAuthorTrailer"],
+			"properties": {
+				"template": { "type": "string", "minLength": 1 },
+				"templateNoScope": { "type": "string", "minLength": 1 },
+				"typeDefault": { "type": "string", "minLength": 1 },
+				"scopeDefault": { "type": "string" },
+				"bodySeparator": { "type": "string" },
+				"coAuthorTrailer": { "type": "string", "minLength": 1 },
+				"maxSubjectLength": { "type": "integer", "minimum": 20, "maximum": 200 }
+			}
+		}
+	}
+}

package/.pi/harness/specs/ls-lint-manifest-proposal.schema.json

@@ -0,0 +1,80 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/ls-lint-manifest-proposal.schema.json",
+	"title": "LsLintManifestProposal",
+	"description": "Graphify-grounded proposal to evolve naming.manifest.json (intent layer). Chair applies after approval.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"change_class",
+		"summary",
+		"evidence",
+		"manifest_patch",
+		"adr_required",
+		"human_required"
+	],
+	"properties": {
+		"schema_version": {
+			"type": "string",
+			"const": "1.0.0"
+		},
+		"change_class": {
+			"type": "string",
+			"enum": [
+				"none",
+				"tune_rule",
+				"add_scoped_rule",
+				"add_ignore",
+				"change_global"
+			]
+		},
+		"summary": {
+			"type": "string",
+			"minLength": 1
+		},
+		"evidence": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["source", "ref", "summary"],
+				"properties": {
+					"source": {
+						"type": "string",
+						"enum": ["graphify", "sg", "ls-lint", "plan", "manifest"]
+					},
+					"ref": {
+						"type": "string",
+						"minLength": 1
+					},
+					"summary": {
+						"type": "string",
+						"minLength": 1
+					}
+				}
+			}
+		},
+		"manifest_patch": {
+			"type": "object",
+			"description": "JSON Merge Patch (RFC 7396) ops against naming.manifest.json",
+			"additionalProperties": true
+		},
+		"adr_required": {
+			"type": "boolean"
+		},
+		"adr_draft": {
+			"type": "string"
+		},
+		"human_required": {
+			"type": "boolean"
+		},
+		"open_questions": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			}
+		}
+	}
+}

package/.pi/harness/specs/ls-lint-signal.schema.json

@@ -0,0 +1,47 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/ls-lint-signal.schema.json",
+	"title": "LsLintSignal",
+	"description": "Per-run ls-lint CLI observation for evaluator and harness-verify promotion.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"run_id",
+		"lint_pass",
+		"status",
+		"recorded_at"
+	],
+	"properties": {
+		"schema_version": {
+			"type": "string",
+			"const": "1.0.0"
+		},
+		"run_id": {
+			"type": "string",
+			"minLength": 1
+		},
+		"lint_pass": {
+			"type": "boolean"
+		},
+		"violation_count": {
+			"type": "integer",
+			"minimum": 0
+		},
+		"status": {
+			"type": "string",
+			"enum": ["pass", "fail", "skipped", "not_installed"]
+		},
+		"quality_signal_summary": {
+			"type": "string"
+		},
+		"recorded_at": {
+			"type": "string",
+			"format": "date-time"
+		},
+		"phase": {
+			"type": "string",
+			"enum": ["execute", "evaluate", "review"]
+		}
+	}
+}

package/.pi/harness/specs/naming-manifest.schema.json

@@ -0,0 +1,54 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/naming-manifest.schema.json",
+	"title": "NamingManifest",
+	"description": "Canonical harness source for .ls-lint.yml (filename and directory naming).",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schema_version", "project", "global_rules", "ignores"],
+	"properties": {
+		"schema_version": {
+			"type": "string",
+			"const": "1.0.0"
+		},
+		"project": {
+			"type": "string",
+			"minLength": 1
+		},
+		"global_rules": {
+			"type": "object",
+			"additionalProperties": {
+				"type": "string",
+				"minLength": 1
+			}
+		},
+		"scoped_rules": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["path", "rules"],
+				"properties": {
+					"path": {
+						"type": "string",
+						"minLength": 1
+					},
+					"rules": {
+						"type": "object",
+						"additionalProperties": {
+							"type": "string",
+							"minLength": 1
+						}
+					}
+				}
+			}
+		},
+		"ignores": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			}
+		}
+	}
+}

package/.pi/harness/specs/plan-task-clarification.schema.json

@@ -0,0 +1,88 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-task-clarification.schema.json",
+	"title": "PlanTaskClarification",
+	"description": "Upfront task contract before harness plan reconnaissance (Phase 0).",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"status",
+		"source_task",
+		"clarified_task",
+		"success_definition",
+		"in_scope",
+		"out_of_scope",
+		"acceptance_checks_draft",
+		"assumptions",
+		"risk_level",
+		"unresolved_questions",
+		"clarification_rounds",
+		"task_input_hash"
+	],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"status": {
+			"type": "string",
+			"enum": ["draft", "needs_user", "ready"]
+		},
+		"source_task": { "type": "string", "minLength": 1 },
+		"clarified_task": { "type": "string", "minLength": 1 },
+		"success_definition": { "type": "string", "minLength": 1 },
+		"in_scope": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"out_of_scope": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"acceptance_checks_draft": {
+			"type": "array",
+			"minItems": 1,
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"assumptions": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"risk_level": {
+			"type": "string",
+			"enum": ["low", "med", "high"]
+		},
+		"constraints": {
+			"type": "object",
+			"properties": {
+				"hard": { "type": "array", "items": { "type": "string" } },
+				"soft": { "type": "array", "items": { "type": "string" } }
+			},
+			"additionalProperties": true
+		},
+		"unresolved_questions": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"clarification_rounds": { "type": "integer", "minimum": 0 },
+		"task_input_hash": { "type": "string", "minLength": 1 },
+		"evidence_refs": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"grounding": {
+			"type": "object",
+			"properties": {
+				"repo_mentions": {
+					"type": "array",
+					"items": { "type": "string" }
+				},
+				"urls": { "type": "array", "items": { "type": "string" } },
+				"tools_used": {
+					"type": "array",
+					"items": { "type": "string" }
+				},
+				"summary": { "type": "string" }
+			},
+			"additionalProperties": true
+		}
+	}
+}