businesslens 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,253 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.7.0] - 2026-08-04
+
+### Added
+
+- `businesslens view` renders the current Product Model privately on localhost,
+  recompiles automatically after debounced source edits, streams revisions to
+  open browsers, retains the last valid report during lint errors, writes no
+  generated report, and opens no network listener beyond `127.0.0.1`.
+- Root `businesslens` exports for the pure Product Report view-model projection,
+  the shared Nuxt report renderer, and a sibling BusinessLens-wide theme Layer,
+  so hosts share UI without a second public npm package.
+- An opt-in shared Nuxt theme-lab Layer for auditioning the same backgrounds,
+  marks, lockups, and favicon families across the landing site and local report
+  viewer without promoting undecided presentation into the stable theme.
+- An optional `.businesslens/logo.svg` Product logo used by the local viewer and
+  Blueprint presentation.
+- First-class Interface entities for supported Product interaction contracts,
+  with exact Interface–Experience availability across Capabilities, Journeys,
+  Screens, Scenarios, and Business Rules.
+- Required Actor classification as `person|system` and `external|internal`.
+- Platform-neutral Screen entities for meaningful web and mobile product views,
+  including product-visible information, actions, states, capability boundaries,
+  relationships, and optional public routes or deep links.
+- Universal References on every semantic entity, with independent artifact
+  kinds (`code|spec|proposal|doc|adr|visual|research`) and attachment roles
+  (`intent|implementation|context`). Referenced content stays outside the
+  Product Model and never replaces its prose or proves alignment.
+- `businesslens-map` for initial adoption, scoped remapping, and deliberate
+  Product Model coverage expansion without executing target code.
+- `businesslens-verify` as the single post-build invocation. It classifies
+  model/code gaps, negotiates only authority decisions, automatically runs
+  internal intent-resolution or scoped-mapping phases, hands code corrections
+  to a harness-injected builder, and re-verifies until aligned or blocked.
+- `report only` verification mode, an explicit missing-builder handoff, and an
+  unchanged-gap stopping rule. Verification findings are re-derived rather than
+  persisted in a receipt or ledger.
+- Accepted decisions covering [repository-owned files](./adr/0004-write-nothing-outside-businesslens.md),
+  [unified References](./adr/0008-unified-references-and-portable-reports.md),
+  [non-persisted verification](./adr/0006-verification-is-not-persisted.md),
+  and the [three-skill boundary](./adr/0007-three-skills-and-one-verification-loop.md).
+
+### Changed
+
+- The CLI now uses a real hierarchical command parser with concise root help,
+  command-specific options, nested Blueprint help, standard `-h`/`-V` flags,
+  strict option ownership, and usage validation before command execution.
+- `-c, --cwd` now always means "run from this directory". A model directly in the
+  current directory wins over the Git-root model whether or not `--cwd .` was
+  typed explicitly.
+- **Breaking.** A catalog Blueprint has no separate `blueprint.yaml`. Product
+  ID, title, summary, description, category, tags, authors, license, and report
+  content come from `product.md`; visual identity comes only from
+  `.businesslens/logo.svg`, and catalog operational state remains outside the
+  Product Model.
+- **Breaking.** Product Report v7 is the only accepted report contract. It
+  carries portable Product identity and attribution, uses `summary` for the
+  short Product description, and renames computed entity totals to `counts`.
+- **Breaking.** `blueprint contribute` no longer accepts `--slug`; the Product
+  ID is the canonical contribution directory, branch suffix, catalog slug, and
+  pull name.
+
+- **Breaking.** Folder schema 3 and Product Report v7 are now the only accepted
+  formats. Schema 1/2, Product Report v4/v5/v6, and their compatibility paths are
+  removed rather than migrated.
+- **Breaking.** Feature is renamed Capability throughout the folder format,
+  parser, SDK, CLI, skills, docs, fixtures, and Blueprint. `features/` is
+  rejected; Capabilities live in `capabilities/`.
+- **Breaking.** Experiences now declare their Interfaces and no longer carry
+  `exit`. Journeys use Capabilities and exact availability, may cross Domains,
+  and no longer declare one Domain. Business Rules exclusively own Rule scope.
+- Domains are optional Capability groupings. Screens remain optional and now
+  use exact availability without embedding visual evidence.
+- The bundled Content & Feed Reader Blueprint now demonstrates the complete
+  model, including cross-platform Screens, product states, mobile deep links,
+  and external visual and research references.
+- **Breaking.** The public skill set is exactly `businesslens-map`,
+  `businesslens-ideate`, and `businesslens-verify`. Ideate also handles a narrow
+  already-decided verification handoff without reopening broad brainstorming.
+- **Breaking.** `businesslens validate` is now `businesslens lint`. The old
+  spelling is refused with exit code 2 and a replacement message; it is not an
+  alias. Lint output contains only `ok`, `errors`, `warnings`, and `counts`—no
+  branch situation or authority inference.
+- **Breaking.** `references` replaces both `codeRefs` and `links`. Reference
+  records are strict, duplicate targets fail lint, code targets require tracked
+  files, and missing local non-code targets warn.
+- `coverage.status` now describes model breadth only: `draft` while the model
+  itself is under review, `partial` with known unmapped areas, and `complete`
+  when intended product scope is modeled. A complete model may have zero
+  References.
+- **Breaking.** Product Report v7 declares a `workspace` or `portable` Reference
+  profile. Portable projection replaces evidence-redaction terminology and
+  keeps only HTTP(S) intent/context References.
+- **Breaking.** Coverage no longer contains counts, mapped entities, or a
+  redaction flag. Entity totals live only in Counts; Coverage is independent
+  from References. Blueprint open and pull preserve model breadth while
+  removing repository-local Coverage source areas.
+- Every model creation path carries canonical orientation in
+  `.businesslens/README.md`. BusinessLens still never writes target-root
+  `AGENTS.md`, `CLAUDE.md`, or README files.
+- Canonical report expansion now owns that orientation file for `open`, `pull`,
+  and `contribute`; Blueprint contributions accept every valid model-breadth
+  Coverage status and publish no source-repository provenance.
+- Lint now requires the complete committed model shell (`README.md` plus a
+  `.gitignore` covering `build/` and `cache/`), and CLI argument, provider,
+  scope, slug, and catalog-origin errors consistently exit with usage code 2.
+- Documentation now teaches three starting doors and one ongoing loop:
+  `ideate → injected build → verify (including final lint) → merge`. Map is explicitly not a
+  daily maintenance command, and lint is explicitly not semantic verification.
+
+### Fixed
+
+- Product logos are parsed as namespace-aware XML and restricted to a static SVG
+  allowlist, closing namespace-prefix and escaped-reference paths around the
+  active-content checks. Logo responses from the local viewer also carry a
+  script-free sandbox CSP.
+- `blueprint pull` retrieves the optional logo from the selected catalog's
+  same-origin endpoint, so custom catalogs and commit-pinned reports cannot be
+  paired with the current logo from the official PDD `main` branch.
+- Releases tag an already prepared package and changelog exactly once; the tag
+  push is now the single automatic publication trigger.
+
+### Removed
+
+- `businesslens-init`, `businesslens-sync`, `businesslens-doctor`, and
+  `businesslens-deep-dive`. Their useful scopes now belong to map or verify.
+- The `businesslens-contribute` skill. Catalog contribution remains the
+  deterministic `businesslens blueprint contribute` CLI command.
+- Git branch-state routing from lint and the internal `branch-state` module.
+
+## [0.6.0] - 2026-07-31
+
+BusinessLens consolidates onto one site. The Platform is retired; the Blueprint
+catalog moves to `businesslens.io` and becomes anonymous to browse and to pull.
+
+The previous published npm version is `0.5.0`. An intermediate draft of this
+release included authenticated Platform workflows, but it was never published;
+the final `0.6.0` replaces those workflows with the anonymous catalog and the
+pull-request contribution flow described below.
+
+### Added
+
+- `businesslens open <report>` expands a local Product Report back into a
+  canonical `.businesslens/` Product Model, making `export` and `open`
+  semantic inverses.
+- `businesslens pull <blueprint-name>` anonymously retrieves a Blueprint and
+  expands it without a user-facing `report.json` download. It writes a
+  greenfield block into `AGENTS.md` and sends
+  `user-agent: businesslens/<version>` to the catalog.
+- **Features** and **business rules** are first-class product-model entities
+  with their own directories, IDs, relationships, and validation rules.
+- A `businesslens/report` library entry point exporting the Product Report
+  schema, its cross-entity validator, and the canonical digest. It depends only
+  on `zod` and never loads the CLI.
+- `redactSourceEvidence` in the `businesslens/report` contract strips every
+  repository reference from a report before it leaves its owning workspace —
+  `codeRefs`, repository `entryPoints`, repository-relative `links`, and
+  `coverage.sourceAreas`. Product-facing routes and HTTP(S) URLs are kept.
+  `coverage.mapped` remains a model-quality signal, and
+  `coverage.evidenceRedacted` records both that those counts describe the
+  origin repository and that validation must reject any repository path still
+  present.
+- `businesslens-plan` and `businesslens-verify` skills for planning in the
+  Product Model and verifying implementation evidence before merge.
+- `businesslens-implement` builds the software a Product Model describes, with
+  its scenarios as the acceptance contract.
+- `businesslens-ideate` proposes candidate product directions as a shortlist.
+  It is the only skill that never writes to the model.
+- Draft greenfield product models, with missing-evidence warnings during
+  planning and support for exporting planned Product Model Versions before
+  implementation is complete.
+- `blueprints/` — the Blueprint source layout, with a `blueprint.yaml` manifest
+  and MIT-licensed content.
+- `blueprints:check`, wired into `verify`, parses every manifest, builds every
+  Blueprint, and rejects any that carries source evidence. It does not trust
+  `contribute`, because anyone can open a pull request by hand.
+- `blueprints:publish` pushes built Blueprints to the catalog.
+- `resolveModelRoot` allows the model to live outside the Git root or without a
+  repository, adding general monorepo support.
+- A structured open-source documentation section with tutorials, individual
+  skill pages, and deterministic navigation frontmatter.
+- `docs/terminology.md` defines every product-model entity and separates the
+  terms that are easy to confuse.
+
+### Changed
+
+- **Breaking.** `businesslens publish` is now `businesslens contribute`, and
+  opens a pull request against `businesslens/pdd` through the `gh` CLI rather
+  than submitting to a Platform. No API key is involved. The model in the pull
+  request is regenerated from a redacted report, so it carries no source paths
+  and is byte-identical to what `pull` produces.
+- **Breaking.** `businesslens build` is now `businesslens export`. `build` still
+  works and warns; it will be removed after 0.6.x.
+- `export` emits a source-free **Product Report v4** at
+  `.businesslens/build/report.json`, replacing the portable v3 `project.json`.
+  The report carries no repository URL, commit, branch, or workspace metadata.
+- **Breaking.** `.businesslens/` is now called the **Product Model** throughout
+  the CLI, docs, and skills. "Product map" is reserved for a visual or
+  navigable view of that model. Draft coverage is an evidence state and no
+  longer implies a reusable Blueprint.
+- Product Report validation rejects content that cannot round-trip into
+  canonical Markdown and inconsistent mapped-coverage counts. Product Model
+  validation continues to reject non-draft behavioral claims without evidence.
+- `--catalog` defaults to `https://businesslens.io` and accepts any origin.
+  Precedence is `--catalog`, `BUSINESSLENS_CATALOG_URL`, then the default.
+- `businesslens-publish` is now `businesslens-contribute`.
+- Skill runners pin the CLI to the version the skills were installed from rather
+  than resolving the latest published version, which could validate a model
+  against an older published format.
+
+### Fixed
+
+- Report expansion is idempotent. `open` appended its coverage limitation
+  unconditionally, so every open/pull cycle gained another copy and broke the
+  guarantee that a pulled Blueprint matches what the catalog holds.
+- Docs dispatch sends an immutable commit-pinned revision to the landing
+  pipeline ([#2](https://github.com/businesslens/pdd/pull/2)).
+
+## [0.5.0] - 2026-07-26
+
+### Added
+
+- `build` and `publish` CLI commands, the `businesslens-publish` skill with its
+  isolated runner, and the CI publishing recipe
+  ([#1](https://github.com/businesslens/pdd/pull/1)).
+
+## [0.4.0] - 2026-07-26
+
+Initial public launch of the repository.
+
+### Added
+
+- CLI: `install`, `update`, and `validate` commands.
+- Agent skills: `businesslens-init`, `businesslens-sync`,
+  `businesslens-deep-dive`, `businesslens-validate`, and
+  `businesslens-doctor`.
+- The `.businesslens/` product-map format and its contract in
+  `docs/format.md`.
+- Claude plugin manifest and marketplace entry.
+
+[Unreleased]: https://github.com/businesslens/pdd/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/businesslens/pdd/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/businesslens/pdd/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/businesslens/pdd/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/businesslens/pdd/releases/tag/v0.4.0

package/README.md

@@ -1,18 +1,29 @@
 # BusinessLens
 
-**Product-Driven Design for coding agents.** BusinessLens builds a
-Git-tracked product map in `.businesslens/`: who the product serves, what they
-accomplish, and where the code proves it.
+[![npm](https://img.shields.io/npm/v/businesslens)](https://www.npmjs.com/package/businesslens)
+[![Check](https://github.com/businesslens/pdd/actions/workflows/check.yml/badge.svg)](https://github.com/businesslens/pdd/actions/workflows/check.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-The map is Markdown, reviewable in pull requests, and useful without a hosted
-service.
+**Product-Driven Development for coding agents.** BusinessLens keeps intended
+product behavior in a Git-tracked `.businesslens/` Product Model: who the
+product serves, what they accomplish, and which rules must remain true.
+
+The model is Markdown, reviewable in pull requests, and useful without a hosted
+service. `businesslens lint` checks its structure. The `businesslens-verify`
+skill performs the separate semantic comparison with code and owns the
+resolution loop.
 
 ```text
 .businesslens/
+├── README.md
 ├── product.md
 ├── actors/
+├── interfaces/
 ├── experiences/
-├── domains/
+├── screens/                  # optional product views
+├── domains/                  # optional organization
+├── capabilities/
+├── business-rules/
 ├── journeys/<id>/journey.md
 │   └── scenarios/<id>.md
 └── coverage.md
@@ -20,129 +31,123 @@ service.
 
 ## Getting started
 
-### 1. Install the skills
-
-Run this in the repository you want to map:
+Install the skills:
 
 ```bash
-npx businesslens@latest install
+npx businesslens install
 ```
 
-The installer detects supported AI harnesses, lets you customize the
-selection, asks for project or global scope, and installs only the
-BusinessLens skills.
-
-For automated setup:
+Then choose one starting door:
 
-```bash
-npx businesslens@latest install \
-  --providers claude,codex,cursor \
-  --scope project \
-  --yes
-```
+- **Existing product** — `/businesslens-map` creates the model from established
+  repository behavior.
+- **Blank repository** — `/businesslens-ideate` decides and authors the product
+  before implementation.
+- **Blueprint** — `npx businesslens blueprint pull <name>` opens a
+  reviewed starting model.
 
-### 2. Build the map in your AI harness
+Codex users invoke skills with `$`, for example `$businesslens-map`.
 
-Invoke the initialization skill:
+## The ongoing loop
 
 ```text
-/businesslens-init
+/businesslens-ideate guest checkout
+        ↓ approved Product Model delta
+your injected plan / build flow
+        ↓ implementation
+/businesslens-verify this branch
+        ↓ automatically resolve gaps, re-check, and run final lint
+merge
 ```
 
-Codex users can invoke the same skill as `$businesslens-init`. The skill
-inspects the repository without executing its application, authors the full
-map, installs the managed `AGENTS.md` guidance, and validates the result.
-
-### 3. Review and commit
+You invoke verify once. When it finds a gap, it groups the authority decision
+and routes automatically: update approved model meaning through its internal
+ideation protocol, map an absent established area, or hand an acceptance packet
+to the builder supplied by your harness. It re-verifies after every change and
+stops explicitly when blocked. Its completion report includes final structural
+lint, so no second skill or command is required to finish the loop. Use `report
+only` to disable all writes and delegation.
 
-Review `.businesslens/`, then commit its authored files. Generated cache files
-stay ignored.
+`map` is not daily maintenance. Use it for adoption, a deliberately untrusted
+area, or coverage expansion. Use `verify` after changes, refactors, suspected
+drift, before release, or for a named/full current-state audit.
 
-## Terminal or agent?
-
-BusinessLens has two deliberate surfaces:
+## Terminal and agent surfaces
 
 | Where | Command | Purpose |
 | --- | --- | --- |
-| Terminal | `npx businesslens install` | Install the agent skills |
+| Terminal | `npx businesslens install` | Install the three skills |
 | Terminal | `npx businesslens update` | Refresh managed skill installations |
-| Terminal | `npx businesslens validate` | Deterministically validate the map |
-| Terminal | `npx businesslens build` | Compile the map into the portable project document |
-| Terminal | `npx businesslens publish` | Submit the map to the platform as a commit-pinned snapshot |
-| AI harness | `businesslens-init` | Build the initial map |
-| AI harness | `businesslens-sync` | Update the map after behavior changes |
-| AI harness | `businesslens-deep-dive` | Expand one journey or experience |
-| AI harness | `businesslens-validate` | Validate the map and explain every result |
-| AI harness | `businesslens-doctor` | Diagnose validation, drift, and coverage |
-| AI harness | `businesslens-publish` | Publish the map to the platform on explicit request |
-
-The installer never creates `.businesslens/` or modifies `AGENTS.md`. Those
-require repository analysis and belong to the initialization skill.
-
-## Skills
-
-| Skill | Use it when |
-| --- | --- |
-| `businesslens-init` | Adopting BusinessLens or rebuilding an incomplete map |
-| `businesslens-sync` | Code changes affected product behavior |
-| `businesslens-deep-dive` | One journey or experience needs exhaustive coverage |
-| `businesslens-validate` | The map needs a read-only deterministic check |
-| `businesslens-doctor` | The map fails validation, looks stale, or needs a health report |
-| `businesslens-publish` | The user explicitly wants the map on the platform |
-
-Every skill is self-contained and follows the open Agent Skills folder format.
-The CLI currently supports Claude Code, Codex, Cursor, Gemini CLI, and GitHub
-Copilot installation paths.
-
-`businesslens-validate` is the read-only agent interface to the deterministic
-CLI validator. `businesslens-doctor` goes further: it investigates drift,
-coverage, and hygiene, and can repair problems when explicitly requested.
-
-Claude Code plugin users may alternatively install from this repository's
-marketplace manifest. The standalone CLI remains the primary installation
-experience.
-
-## Keep the map current
-
-1. Before changing behavior, read the relevant experiences, journeys, and
-   scenarios.
-2. Build against the repository's SDD change when one exists.
-3. Invoke `businesslens-sync` after behavior changes.
-4. Run `npx businesslens validate`.
-
-PDD records what **is**. OpenSpec, spec-kit, and other SDD systems prescribe
-what **will change**. BusinessLens links that intent without copying it. See
-[PDD and SDD](./docs/pdd-and-sdd.md).
-
-## Updating the skills
-
-```bash
-npx businesslens@latest update
-```
-
-Update discovers BusinessLens-managed installations through ownership markers
-and refreshes only those skill directories. It does not touch `.businesslens/`
-or `AGENTS.md`.
+| Terminal | `npx businesslens lint` | Check Product Model structure; no semantic claim |
+| Terminal | `npx businesslens view` | View the current Product Model privately on localhost |
+| Terminal | `npx businesslens blueprint export` | Compile the model into a source-free Blueprint |
+| Terminal | `npx businesslens blueprint pull <name>` | Pull a catalog Blueprint |
+| Terminal | `npx businesslens blueprint open <report>` | Expand a local Blueprint |
+| Terminal | `npx businesslens blueprint contribute` | Propose a Blueprint by pull request |
+| AI harness | `businesslens-map` | Map established repository behavior |
+| AI harness | `businesslens-ideate` | Decide intended behavior and write approved meaning |
+| AI harness | `businesslens-verify` | Verify and automatically resolve model/code gaps |
+
+Catalog contribution stays in the CLI; there is no contribution skill.
+
+## Product Model semantics
+
+- `references` optionally attach intent, implementation, or context artifacts
+  to any semantic entity. They are navigation and supporting material, not
+  proof or verification receipts.
+- `coverage.status` describes model breadth: `draft` while the model itself is
+  under review, `partial` with known unmapped areas, and `complete` when the
+  intended product scope is modeled.
+- A complete model may contain zero References.
+- A Product may expose several Interfaces—such as web, mobile, CLI, and a
+  supported API—without being classified as one of those delivery forms.
+- Experiences are coherent usage contexts across Interfaces; exact
+  Interface–Experience availability says where behavior is promised.
+- Domains are optional Capability groupings, and Journeys may cross them.
+- Screens are optional platform-neutral product views. Screenshots and other
+  visuals remain external References, not model assets or proof.
+- `lint` checks format, required content, relationships, Reference grammar, and
+  tracked code-reference paths. `verify` checks meaning against current code.
+
+Every model creation path writes `.businesslens/README.md`. BusinessLens never
+writes target `AGENTS.md`, `CLAUDE.md`, or root README files.
 
 ## Documentation
 
-- [Introduction](./docs/index.md)
-- [Quickstart](./docs/quickstart.md)
-- [`.businesslens/` format](./docs/format.md)
-- [CLI reference](./docs/cli.md)
-- [Skills reference](./docs/skills.md)
-- [CI validation and publishing](./docs/ci.md)
-- [PDD and SDD](./docs/pdd-and-sdd.md)
+- [Introduction](./docs/index.md) · [Installation](./docs/installation.md) ·
+  [Development loop](./docs/the-loop.md)
+- Start [from your repo](./docs/from-your-repo.md),
+  [from a Blueprint](./docs/from-a-blueprint.md), or
+  [from an idea](./docs/from-an-idea.md)
+- [Product Model](./docs/product-model.md) ·
+  [References](./docs/references.md)
+- [Skills](./docs/skills.md) · [CLI](./docs/cli.md) ·
+  [CI/CD](./docs/ci.md)
+- [Format contract](./spec/format.md)
+
+## Nuxt layers
+
+The package also exposes separately composable Nuxt layers:
+
+- `businesslens/nuxt/report-viewer` renders a Product Report without owning its
+  host navigation or page shell.
+- `businesslens/nuxt/theme` provides the stable BusinessLens palette, type, and
+  semantic UI foundation.
+- `businesslens/nuxt/theme-lab` extends that stable theme with the shared,
+  opt-in background and brand experiments used by the landing site and local
+  report viewer. Its ownership and promotion rules are recorded in
+  [`plans/shared-theme-lab.md`](./plans/shared-theme-lab.md).
 
 ## Safety
 
-- Skills inspect target repositories statically; they do not run target code.
-- Installation refuses to overwrite unowned `businesslens-*` directories
-  unless `--force` is explicit.
-- Updates replace only artifacts marked as BusinessLens-managed.
-- No platform connection or publishing occurs during installation or mapping;
-  publishing happens only through the explicit `publish` command or the
-  `businesslens-publish` skill.
+- BusinessLens analysis phases inspect untrusted repositories without executing
+  target code. A separately injected builder may run normal project checks under
+  its own permissions.
+- Installation refuses to overwrite unowned skill directories unless `--force`
+  is explicit; update touches only marked installations.
+- Nothing submits model data except the explicit
+  `businesslens blueprint contribute` command.
+- No command publishes, tags, or pushes implicitly.
 
 ## License
 

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { };