Warn aipm init about ancestor pnpm workspaces; sync GUIDE.md with --help

[mike-north]

Summary

Two onboarding hazards from the DX study (issue #96):

1. Ancestor pnpm-workspace contamination. A directory with no local package.json under an
   ancestor pnpm-workspace.yaml has pnpm add/pnpm install silently target the ancestor's
   manifest and lockfile — a first-time user following the old docs verbatim could corrupt an
   unrelated parent repo.
2. GUIDE.md (packages/cli/README.md) drift vs aipm --help: missing lint, missing flags,
   missing the quick start's install step, and a dead relative link to the architecture spec (only
   resolvable inside the monorepo checkout, 404s in the published npm package).

Changes

• packages/core/src/pipeline/init.ts: runInit now walks up from the target directory looking
  for an ancestor pnpm-workspace.yaml and returns it via a new InitOutcome.ancestorWorkspace.
  The local package.json boundary is still always written regardless.
• packages/core/src/pipeline/{operations,types,index}.ts: init()'s public return type changes
  from Promise<void> to Promise<InitOutcome> (additive; new exported type
  { ancestorWorkspace?: string }).
• packages/cli/src/run.ts: aipm init prints a warning to stderr when ancestorWorkspace is
  set, before the "Next: run pnpm install" line, exit code stays 0 (informational, non-blocking).
• packages/cli/README.md (the "GUIDE.md" referenced in the issue — DX-study participants
  literally copied this file and named it GUIDE.md): quick start now runs npm init -y before
  the install command with an explicit workspace-hazard callout; documents lint and every
  subcommand's flags (--name, --refresh, --force, --force-downgrade, --as, --format,
  --rule, --verbose) to match aipm --help; includes the quick start's install step; replaces
  the dead ../../docs/specs/architecture.md relative link with an absolute GitHub URL.
• docs/specs/architecture.md §8.1: updated the pinned init signature and InitOptions/
  InitOutcome block to match, plus a short note on the new guard.
• .changeset/onboarding-workspace-hazard-and-guide-sync.md: minor bump for both packages (public
  return-type change to init()).

Acceptance criteria mapping

1. Quick start requires npm init -y before install, with an explicit workspace-hazard note —
   packages/cli/README.md Install section (verified by reading the rendered file; no automated
   doc-content test per repo convention for prose sections).
2. aipm init scaffolds a workspace boundary OR detects an ancestor workspace and warns —
   runInit always writes a local package.json (pre-existing boundary) and now detects+warns
   on an ancestor pnpm-workspace.yaml. Covered by:
   • packages/core/src/pipeline/init.test.ts → describe('ancestor pnpm-workspace detection (issue #96)') (InitOutcome.ancestorWorkspace set/unset, nested ancestor lookup)
   • packages/cli/src/run.test.ts → 'warns to stderr when an ancestor pnpm-workspace.yaml exists' and 'does not warn when there is no ancestor pnpm-workspace.yaml' (UAT against the real CLI dispatcher/stderr contract)
3. GUIDE.md synced with aipm --help: lint command, all flags, install step present; dead
   relative link fixed — verified manually by diffing packages/cli/README.md against
   node packages/cli/dist/bin.js --help output (every command/flag row present) and confirming
   the architecture-spec link is an absolute, always-resolvable GitHub URL.

Test plan

• pnpm run check (typecheck, lint, api-report, tests, knip, syncpack, prettier) — green
• pnpm run fix:format run before push
• New unit tests in packages/core/src/pipeline/init.test.ts (ancestor detection: found nested, found deep, not found)
• New UAT tests in packages/cli/src/run.test.ts (stderr warning content + exit code + no-warning case)
• Manual: packages/cli/README.md command/flag tables cross-checked against aipm --help output

Refs #96

[Copilot]

Pull request overview

Addresses two onboarding hazards (issue #96) by (1) detecting and warning about ancestor pnpm-workspace.yaml workspaces during aipm init and (2) syncing the published CLI guide (packages/cli/README.md) with the actual aipm --help surface.

Changes:

• Add ancestor pnpm-workspace detection to core init and return it as InitOutcome.ancestorWorkspace (public API now returns Promise<InitOutcome>).
• Emit a non-blocking stderr warning in the CLI when an ancestor workspace is detected, and add tests for both the detection and the warning behavior.
• Update CLI README and architecture spec to document the workspace hazard, add missing commands/flags, and fix the dead spec link.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/core/src/pipeline/types.ts	Introduces InitOutcome (public return type for init).
packages/core/src/pipeline/operations.ts	Updates init() signature to return Promise<InitOutcome>.
packages/core/src/pipeline/init.ts	Implements ancestor pnpm-workspace.yaml lookup and returns it via InitOutcome.
packages/core/src/pipeline/init.test.ts	Adds unit tests covering ancestor workspace detection behavior.
packages/core/src/index.ts	Exports InitOutcome from the public core entrypoint.
packages/core/api-report/core.api.md	Updates API report for the new init() signature and InitOutcome type.
packages/cli/src/run.ts	Prints a stderr warning when InitOutcome.ancestorWorkspace is set.
packages/cli/src/run.test.ts	Adds UAT coverage for warning/no-warning behavior and exit code.
packages/cli/README.md	Updates install/quick start + adds missing commands/flags + fixes spec link.
docs/specs/architecture.md	Syncs architecture spec API blocks and documents the new guard/warn.
.changeset/onboarding-workspace-hazard-and-guide-sync.md	Records a minor bump for the public API surface + doc sync.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.