feat(harness): support monorepo workspace topology - #21
Merged
Conversation
Introduce a frozen workspace-topology contract and thread package scope through evidence collection, provider sessions, inherited assets, findings, rendering, and repair routing. Implements docs/specs/2026-07-25-monorepo-workspace-support.md. The change keeps legacy findings readable, fails closed on incomplete or cross-package ownership, and was validated with npm test, npm run pack:verify, direct doc-link checks, and preview endpoint smoke tests.
There was a problem hiding this comment.
Pull request overview
This PR introduces a versioned, Git-aware workspace topology (repo-root / workspace-member / repo-subtree / standalone) and threads that frozen topology + path-scoped analysis contract through evidence bundling, session providers, report rendering, and finding repair/record flows so monorepo targets and owners are explicit end-to-end.
Changes:
- Add
scripts/workspace-topology/*(contract, inventory + manifest discovery, target validation, CLI) to resolve and freeze topology + analysis scope. - Introduce structured
finding.target(contract v26) with validation and fail-closed owner/package routing across projection, rendering, and fix-output recording. - Update session providers + core-change-watch to support topology-scoped session/workspace qualification and path-scoped Git analysis.
Reviewed changes
Copilot reviewed 68 out of 68 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| test/task-loop-source.test.mjs | Updates practice coverage expectations to include inherited Skills. |
| test/task-loop-report.test.mjs | Bumps report contract assertions to v26 and adds structured target / owner routing tests. |
| test/session-workspace-match.test.mjs | Adds coverage for workspace match topology validation and privacy-safe diagnostics (incl. Windows paths). |
| test/scripts-refactor-contract.test.mjs | Updates frozen CLI output SHA256 expectations. |
| test/plugin-manifests.test.mjs | Ensures workspace-topology scripts are present in npm packaging manifest verification. |
| test/maturity-models.test.mjs | Aligns maturity model constants with new report contract v26 + target contract constant. |
| test/host-plugin-artifact.test.mjs | Ensures runtime bundle includes workspace-topology scripts. |
| test/harness-report-render-cli.test.mjs | Adds render CLI tests for legacy vs v26 findings and structured target enforcement. |
| test/harness-findings-repair.test.mjs | Verifies repairs preserve valid structured finding targets. |
| test/harness-canvas-validation.test.mjs | Ensures installed-like Canvas validation includes workspace-topology scripts. |
| test/fixtures/scripts-refactor-contract/root-help.txt | Updates CLI help fixture to include workspace-topology subcommand. |
| test/fixtures/scripts-refactor-contract/harness-help.txt | Updates harness subcommand help fixture and examples for topology command. |
| test/better-harness-skill.test.mjs | Asserts skill docs mention frozen topology target fields and provider agreement requirements. |
| test/better-harness-evidence-bundle.test.mjs | Bumps evidence bundle schema to v2 and adds tests for one-shot topology resolution + failure modes. |
| test/better-harness-cli.test.mjs | Verifies CLI command inventory exposes workspace-topology and handles spaced paths. |
| test/agent-lint-monorepo.test.mjs | Adds monorepo fixtures validating topology-backed agent instruction discovery and scoping. |
| test/agent-asset-baseline.test.mjs | Updates baseline expectations for truncation/partial status and inherited owner routing in monorepos. |
| skills/better-harness/SKILL.md | Updates guidance to require reading frozen topology target fields before delegation. |
| skills/better-harness/references/finding-bound-fix.md | Adds explicit topology binding rules and structured target fail-closed requirements for repairs. |
| scripts/workspace-topology/manifests.mjs | Implements manifest- and convention-based member + instruction-scope discovery with safety checks. |
| scripts/workspace-topology/inventory.mjs | Adds bounded Git + filesystem fallback inventory collection for topology discovery. |
| scripts/workspace-topology/index.mjs | Adds topology resolver, analysis scope derivation, and exports for finding targets. |
| scripts/workspace-topology/finding-target.mjs | Defines/validates structured finding targets against frozen topology. |
| scripts/workspace-topology/contract.mjs | Defines workspace topology schema, route normalization/containment, and freezing/validation helpers. |
| scripts/workspace-topology/cli.mjs | Adds workspace-topology CLI entrypoint (text/json output). |
| scripts/session-analysis/platforms/cursor.mjs | Adds workspace CWD candidate binding + topology-aware preflight/truncation behavior. |
| scripts/session-analysis/platforms/codex.mjs | Adds topology-aware workspace qualification/hydration and marks read coverage/truncation. |
| scripts/session-analysis/platforms/claude.mjs | Adds topology-aware transcript probing, CWD candidate binding, and read preflight coverage. |
| scripts/npm-package/verify-pack.mjs | Requires workspace-topology scripts in packed artifacts and runtime bundles. |
| scripts/harness-analysis/validate-canvas.mjs | Validates structured finding.target and expands practice scopes to include Inherited. |
| scripts/harness-analysis/task-loop-source.mjs | Threads analysisScope/topology through scanning and adds default findingTarget from topology. |
| scripts/harness-analysis/task-loop-repository-evidence.mjs | Makes repo evidence scanning respect analysis scopes and handle non-git/standalone topologies. |
| scripts/harness-analysis/task-loop-report.mjs | Adds target to findings contract, projects fallback target, and validates finding targets. |
| scripts/harness-analysis/report-source/source.mjs | Validates repositoryEvidence.findingTarget in report source schema. |
| scripts/harness-analysis/report-run.mjs | Passes topology + analysisScope into report-source generation. |
| scripts/harness-analysis/report-data-schema.mjs | Validates finding targets during report normalization/render based on topology + v26 threshold. |
| scripts/harness-analysis/repair-findings-json.mjs | Updates repair normalization to include target and to prefer ownerRoute when inferring target paths. |
| scripts/harness-analysis/renderers/better-harness.mjs | Permits/validates target in findings consumed by Better Harness renderer. |
| scripts/harness-analysis/render-report.mjs | Resolves topology for render target and enforces structured target requirements for v26/package workspaces. |
| scripts/harness-analysis/record-fix-output.mjs | Adds topology-bound validation so fix-output can’t target sibling/out-of-owner paths. |
| scripts/harness-analysis/practice-findings.mjs | Adds topology-aware grouping and structured targets for practice findings with owner routing. |
| scripts/harness-analysis/learning-capture-evidence.mjs | Scopes git log collection to analysisScope pathspecs and filters commit file lists accordingly. |
| scripts/harness-analysis/fluency-dimensions.mjs | Introduces FINDING_TARGET_REPORT_CONTRACT_VERSION and sets report contract to v26. |
| scripts/harness-analysis/evidence-bundle/session-evidence.mjs | Passes frozen topology + analysisScope into session evidence collection. |
| scripts/harness-analysis/evidence-bundle/project-harness.mjs | Runs project harness evidence with topology/analysis scope (and returns partial when evidence pack is non-ok). |
| scripts/harness-analysis/evidence-bundle/index.mjs | Resolves topology once, freezes it into context, and fails/partials bundles when topology is incomplete. |
| scripts/harness-analysis/evidence-bundle/contract.mjs | Bumps schema to v2 and enforces workspace/topology/analysis-scope binding invariants. |
| scripts/harness-analysis/evidence-bundle/agent-customize.mjs | Passes topology + analysisScope into agent customization evidence collection. |
| scripts/core-change-watch/project-profile.mjs | Makes project profiling analysis-scope aware and exports analysisScope in results. |
| scripts/core-change-watch/git-history-profile.mjs | Makes history profiling analysis-scope aware and handles unborn repos as empty history. |
| scripts/core-change-watch/evidence-pack.mjs | Threads analysisScope through all evidence-pack sub-analyses and source command strings. |
| scripts/core-change-watch/diff-impact.mjs | Scopes diff impact analysis to analysisScope and adds compatibility checks. |
| scripts/core-change-watch/core-candidates.mjs | Scopes core-candidate detection to analysisScope and normalizes paths accordingly. |
| scripts/core-change-watch/common.mjs | Introduces structured analysisScope helpers and makes Git failures explicit (typed errors). |
| scripts/core-change-watch/change-drift.mjs | Scopes drift analysis + companion candidate discovery to analysisScope pathspecs. |
| scripts/coding-agent-practices/inventory.mjs | Adds inherited surfaces and routes origin metadata into practice coverage rows. |
| scripts/coding-agent-practices/asset-baseline.mjs | Adds inherited inventory merging, truncation reporting, and partial status when envelopes truncate. |
| scripts/better-harness-cli/registry.mjs | Registers harness workspace-topology subcommand in the CLI registry. |
| scripts/better-harness-cli/cli.mjs | Adds workspace-topology example to group examples. |
| scripts/agent-lint/index.mjs | Adds topology-backed entrypoint discovery and populates package/owner routes on findings. |
| scripts/agent-customize/core/items.mjs | Allows inherited sources for project/workspace scope kinds. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Canonicalize both sides of filesystem identity checks so symlink, case, and Windows 8.3 path aliases do not escape package scope or reject a valid render target. Parse explicit topology CLI boolean values strictly instead of relying on string truthiness. Updates docs/specs/2026-07-25-monorepo-workspace-support.md with AC13. The focused regressions passed 102/102, the full suite passed 926/926, and pack, doc-link, and preview smoke checks passed. Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>
Extend the monorepo topology spec with current-host parity, exact frozen-context binding, and hermetic Git fixture acceptance criteria before implementation. The new AC14-AC15 scope the review findings against the current main branch and preserve the existing AC1-AC13 evidence.\n\nSpec: docs/specs/2026-07-25-monorepo-workspace-support.md\n\nCo-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>
Merge the current host-adapter and documentation changes from main while preserving workspace-topology propagation, combined CLI snapshots, and both monorepo and Pi asset-baseline coverage.\n\nValidated the conflict resolutions with 58 focused tests across Evidence Bundle, task-loop source, asset baseline, and CLI contracts.\n\nCo-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>
Preserve monorepo instruction discovery and package-session qualification for Qwen Code, GitHub Copilot, and Pi after syncing current main. Reject forged topology and analysis-scope bindings, and isolate Git fixtures from developer-global ignore rules. The AC1-AC15 spec maps the changed provider, topology, bundle, and fixture contracts. The final default-environment suite passed 977/977; pack verification, direct doc and Skill checks, and preview endpoint smoke tests also passed. Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>
14 tasks
Git for Windows rejects Node os.devNull as a GIT_CONFIG_GLOBAL path because it expands to the Win32 device form. Use the native NUL alias while preserving the existing hermetic global-config isolation on other platforms. The affected fixture suite passed 12/12 and the full local suite passed 977/977. The Windows GitHub Actions job provides the cross-platform verification for this branch. Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>
Merge origin/main commit 24ce791 into the workspace-topology PR. Combine lazy Home resolution with topology-root and ownerRoute validation so Project output remains independent of Home without weakening package-scoped containment. The change preserves docs/specs/2026-07-30-project-output-home-resolution.md alongside the AC1-AC15 topology spec. Focused regressions passed 98/98, the full suite passed 979/979, and pack verification passed with 332 npm and 355 runtime-zip entries. Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>
phodal
marked this pull request as ready for review
July 30, 2026 10:36
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Why
Flat-workspace assumptions could omit inherited instructions, widen package evidence to sibling packages, misattribute root-CWD sessions, or route a finding repair to the wrong owner. After current
mainadded three host adapters, topology parity and frozen-context validation also needed to fail closed instead of silently falling back to flat-CWD collection.Impact
One bundle still analyzes one target, but repository-root, workspace-member, repository-subtree, and standalone identities are explicit. New package findings use report contract v26; report contracts 1-25 remain readable. Root-CWD sessions require bounded, trusted target-only path evidence and are omitted when mixed, ambiguous, or truncated.
Traceability
docs/specs/2026-07-25-monorepo-workspace-support.mdValidation
npm test— 979/979npm run pack:verify— npm 332 entries, runtime zip 355 entries/healthreturnedok;/canvas-module.jsreturned JavaScript with HTTP 200git diff --checkmainmerged locally; conflict resolution preserves lazy Home lookup and package ownerRoute containmentRisk and rollback
Key risks are package-scope widening, root-session contamination, host storage drift, path traversal, and incomplete coverage claims. Tests cover cross-package and partial topology cases, exact topology/scope binding, symlink escape, special-character routes, all seven session providers, legacy finding rendering, and large-session hydration. Revert this PR as one change set to restore the previous flat-workspace behavior.