Feature mapping: package-less nested TypeScript sources under packages/* can be unowned

Summary

ClawPatch v0.8.2's default deterministic mapper can skip a package-less TypeScript project under packages/* whose implementation lives directly in a nested folder rather than src// lib/. This leaves the file outside all ownedFiles feature records.

This may be an intentional boundary rather than a bug; raising a reproducible upstream-first mapping coverage gap rather than implementing a competing mapper.

Minimal synthetic reproduction (no private source)

mkdir -p feature-map-repro/packages/core/governance
cd feature-map-repro
printf '%s\n' '{"name":"portable-mapping-fixture","private":true,"type":"module"}' > package.json
printf '%s\n' 'packages:' "  - 'packages/*'" > pnpm-workspace.yaml
printf '%s\n' 'export type Policy = { enabled: boolean };' > packages/core/governance/types.ts
git init && git add .
clawpatch init
clawpatch map --source heuristic

Inspect .clawpatch/features/*.json and look for ownedFiles[].path === "packages/core/governance/types.ts".

Observed: the map completed successfully with 2 feature records, but none owns that path. Node 24, clawpatch@0.8.2, no provider/model calls. The fixture was exercised in a clean Linux GitHub Actions job with an exact npm version.

Expected / question

Ideally, the package-less project root should produce a bounded generic TypeScript source feature (or source-group feature) for the nested implementation, even when there is no nested package.json, project.json, or conventional src directory. Alternatively, document that this structure is intentionally unsupported and the recommended native configuration for adding coverage.

The Feature Mapping documentation describes package-less Node/TypeScript project roots and bounded source-group discovery, so this is a meaningful gap to clarify.

Constraints

Keep deterministic mapping fast and bounded; no model invocation to make basic source inventory complete.
Respect excludes, generated paths, symlinks, and existing package/project owners.
Add a synthetic mapper test proving the new coverage, with false-positive guards.
Prefer upstream correction rather than a ClawPatch-specific fork or downstream feature mapper.

No private source, credentials or customer data included.

Codex review: this still needs some work.

Summary
This issue still needs a maintainer decision: current main skips the reported layout, and the working metadata workaround has not been documented as the supported alternative.

Reproducibility: Current source establishes why packages/core/governance/types.ts is omitted; the reporter supplies a v0.8.2 reproduction and successful metadata workaround, but this review did not execute the fixture or independently verify the linked CI run.

Maintainer decision needed

Question: Should packages/core/governance be discovered automatically without metadata, or should unconventional package-less layouts require an explicit project.json sourceRoot?
Recommendation: Document explicit source metadata: Keep convention-based discovery and document packages/core/project.json with sourceRoot set to packages/core/governance, backed by a focused ownership regression.
Why: Current source and introduction history deliberately use conventional roots, while the reporter has demonstrated that existing metadata solves this layout; neither the documentation nor a maintainer decision settles whether automatic discovery should expand.

Next step
Choose whether unconventional folders require project.json metadata, then document the validated sourceRoot example or define bounded discovery and ownership changes.

Review details

Best possible solution:

Document the existing project.json sourceRoot route with the reported fixture and an ownership regression, subject to maintainer agreement on the discovery boundary.

Do we have a high-confidence way to reproduce the issue?

Current source establishes why packages/core/governance/types.ts is omitted; the reporter supplies a v0.8.2 reproduction and successful metadata workaround, but this review did not execute the fixture or independently verify the linked CI run.

Is this the best way to solve the issue?

The existing sourceRoot route solves ownership without expanding heuristic discovery; documenting it is the smallest supported path, while automatic coverage requires a deliberate change to both discovery and source-root selection.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

The supported boundary for automatic discovery of unconventional package-less source folders remains undecided.
Broader discovery must preserve exclusions, symlink handling, bounded traversal, and existing project ownership.

Codex review notes: model internal, reasoning medium; reviewed against 12edc2ac692a.

Label changes

Label changes:

No label changes.

Label justifications:

P2: A concrete repository layout loses deterministic feature coverage, but mapping completes and explicit project metadata provides a workaround.
impact:other: Unowned TypeScript files reduce the coverage available to feature-based review.

Evidence reviewed

Acceptance criteria:

pnpm test src/mapper.test.ts src/mappers/next.test.ts
pnpm typecheck
pnpm lint
pnpm test
pnpm build

What I checked:

Current default branch verified: GitHub identifies main as the default branch, and its current SHA matches the review checkout; the working tree remains clean. (12edc2ac692a)
Discovery excludes the reported source layout: Generic project discovery requires framework evidence or reviewable source beneath src, app, pages, lib, server, or api; packages/core/governance/types.ts supplies neither. (src/mappers/projects.ts:733, 12edc2ac692a)
Ownership independently depends on selected source roots: Source grouping walks explicit sourceRoot metadata and named source directories; discovering packages/core alone would still leave governance/types.ts outside the selected roots. (src/mappers/node.ts:378, 12edc2ac692a)
Existing metadata route matches the workaround: Nested project.json files are discovered without requiring an Nx installation, their sourceRoot is retained, and source groups assign matching files to ownedFiles. (src/mappers/projects.ts:81, 12edc2ac692a)
Documentation describes conventions but lacks the concrete workaround: The guide lists package-less projects, supported source directories, and project.json source roots, but does not show the unconventional-folder example or explicitly explain that arbitrary folders require metadata. (docs/feature-mapping.md:34, 12edc2ac692a)
Introduction and subsequent feature history: The REST commit patch for 16e91bc introduced package-less discovery with the same conventional source-root list; merged feat(mapper): map package-less monorepo roots #75 describes convention-based discovery rather than arbitrary-folder coverage. Subsequent history includes false-positive safeguards and package-less Nx preservation. (src/mappers/projects.ts:764, 16e91bc8a689)

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge; those execution lanes are retired.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Reviewed October 20, 2026, 4:47 PM ET / 20:47 UTC.

Verified configuration-first workaround (synthetic GitHub Actions repro)

Thanks for the review. I exercised the recommended native project.json route against unmodified clawpatch@0.8.2, using the same public-safe synthetic workspace as the issue (Node 24, Linux, no Nx package installed, no model calls).

Before: packages/core/governance/types.ts is unowned; default heuristic mapper emits 2 features, neither with that file in ownedFiles.

Change: create packages/core/project.json with:

{"name":"governance-synthetic","sourceRoot":"packages/core/governance","projectType":"library"}

After: clawpatch map --source heuristic emits a native feature with ownedFiles[].path === "packages/core/governance/types.ts". The CI check asserts this and passed, observing 1 owning feature slice.

Evidence: agencyftw/agents PR #574; GitHub Actions run 39365416017.

This validates the maintainer/reviewer suggestion that explicit native metadata can solve the documented package-less mapping case without broadening heuristics or maintaining a fork. Suggest documenting this as the recommended workaround in feature-mapping guidance, with a regression example. I am treating the automated discovery-boundary question as separate; the user still needs to decide whether new project metadata should be required for arbitrary layouts.

No customer code or private findings included.

Navigation Menu

Repository navigation

Feature mapping: package-less nested TypeScript sources under packages/* can be unowned #243

Summary

Minimal synthetic reproduction (no private source)

Expected / question

Constraints

Verified configuration-first workaround (synthetic GitHub Actions repro)

4 remaining items

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Feature mapping: package-less nested TypeScript sources under packages/* can be unowned #243

Description

Summary

Minimal synthetic reproduction (no private source)

Expected / question

Constraints

Activity

clawsweeper commented on Oct 20, 2026

ptahdunbar commented on Oct 20, 2026

Verified configuration-first workaround (synthetic GitHub Actions repro)

4 remaining items

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions