diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dc7b7eb..f75541d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -45,12 +45,3 @@ jobs: - name: Verify the workspace run: pnpm check - - - name: Upload the checked Histoire artifact - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: ui-web-histoire - path: packages/web/.histoire/dist - if-no-files-found: error - include-hidden-files: true - retention-days: 7 diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml index 2131f12..d987bf4 100644 --- a/.github/workflows/pages-deploy.yml +++ b/.github/workflows/pages-deploy.yml @@ -123,21 +123,6 @@ jobs: name: ui-web-histoire path: .pages-delivery/dist - - name: Reverify main before delivery - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 - env: - RELEASE_HEAD_SHA: ${{ needs.build.outputs.head_sha }} - with: - script: | - const currentMain = await github.rest.git.getRef({ - owner: context.repo.owner, - repo: context.repo.repo, - ref: 'heads/main', - }) - if (currentMain.data.object.sha !== process.env.RELEASE_HEAD_SHA) { - core.setFailed('Main changed after the Histoire build; refusing delivery.') - } - - name: Deploy the exact Histoire release artifact env: CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} diff --git a/.github/workflows/pages-preview.yml b/.github/workflows/pages-preview.yml index 405bdb5..d6b4172 100644 --- a/.github/workflows/pages-preview.yml +++ b/.github/workflows/pages-preview.yml @@ -24,7 +24,6 @@ jobs: branch: ${{ steps.identity.outputs.branch }} head_sha: ${{ steps.identity.outputs.head_sha }} pull_number: ${{ steps.identity.outputs.pull_number }} - run_id: ${{ steps.identity.outputs.run_id }} steps: - name: Resolve the exact internal pull request id: identity @@ -38,7 +37,7 @@ jobs: run_id: runId, }) if (run.name !== 'UI checks' || run.path !== '.github/workflows/ci.yml') { - core.setFailed('Preview artifact must come from the trusted UI checks workflow.') + core.setFailed('Preview must be orchestrated by the trusted UI checks workflow.') return } if (run.conclusion !== 'success' || run.event !== 'pull_request') { @@ -69,7 +68,6 @@ jobs: core.setOutput('branch', `pr-${pull.number}`) core.setOutput('head_sha', run.head_sha) core.setOutput('pull_number', String(pull.number)) - core.setOutput('run_id', String(runId)) deploy: name: ui-web preview @@ -78,10 +76,8 @@ jobs: group: ui-web-preview-${{ needs.identity.outputs.pull_number }} cancel-in-progress: true permissions: - actions: read contents: read deployments: write - pull-requests: read runs-on: ubuntu-latest timeout-minutes: 20 environment: @@ -95,6 +91,13 @@ jobs: path: controller persist-credentials: false + - name: Checkout the exact pull-request head + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.identity.outputs.head_sha }} + path: candidate + persist-credentials: false + - name: Install the pinned pnpm release uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9 with: @@ -105,41 +108,19 @@ jobs: with: node-version: 22.22.3 cache: pnpm - cache-dependency-path: controller/pnpm-lock.yaml + cache-dependency-path: | + candidate/pnpm-lock.yaml + controller/pnpm-lock.yaml - - name: Install the trusted delivery toolchain - run: pnpm --dir controller install --frozen-lockfile + - name: Install the candidate and trusted delivery toolchains + run: | + pnpm --dir candidate install --frozen-lockfile + pnpm --dir controller install --frozen-lockfile - - name: Download the exact checked artifact - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 - with: - name: ui-web-histoire - path: .pages-preview/dist - run-id: ${{ needs.identity.outputs.run_id }} - github-token: ${{ secrets.GITHUB_TOKEN }} - - - name: Reverify pull-request identity before delivery - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 - env: - PREVIEW_HEAD_SHA: ${{ needs.identity.outputs.head_sha }} - PULL_NUMBER: ${{ needs.identity.outputs.pull_number }} - with: - script: | - const { data: pull } = await github.rest.pulls.get({ - owner: context.repo.owner, - repo: context.repo.repo, - pull_number: Number(process.env.PULL_NUMBER), - }) - if ( - pull.state !== 'open' || - pull.base.ref !== 'main' || - pull.head.sha !== process.env.PREVIEW_HEAD_SHA || - pull.head.repo?.full_name !== `${context.repo.owner}/${context.repo.repo}` - ) { - core.setFailed('Pull-request identity changed after artifact selection.') - } + - name: Build the exact-head Histoire preview + run: pnpm --dir candidate story - - name: Deploy the checked Histoire artifact + - name: Deploy the exact-head Histoire preview env: CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} @@ -147,7 +128,7 @@ jobs: PREVIEW_HEAD_SHA: ${{ needs.identity.outputs.head_sha }} run: >- pnpm --dir controller exec wrangler pages deploy - "$GITHUB_WORKSPACE/.pages-preview/dist" + "$GITHUB_WORKSPACE/candidate/packages/web/.histoire/dist" --project-name="${{ vars.CLOUDFLARE_PAGES_PROJECT }}" --branch="$PREVIEW_BRANCH" --commit-hash="$PREVIEW_HEAD_SHA" diff --git a/.gitignore b/.gitignore index eee3857..292395f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,33 +1,38 @@ -# package files -dist/ -node_modules/ -package-lock.json -yarn.lock - -# IDE files -.vscode/* +# package files +dist/ +node_modules/ +package-lock.json +yarn.lock + +# IDE files +.vscode/* !.vscode/*.example.jsonc !.vscode/*.code-snippets !.vscode/extensions.json !.vscode/settings.json - -# temp files -tmp - -# build files -*.tgz -stats.html - -# logs -debug.log - -# test coverage -coverage/ -.nyc_output/ - -# histoire -.histoire/ - -# images -*.png + +# temp files +tmp + +# build files +*.tgz +stats.html + +# logs +debug.log + +# test coverage +coverage/ +.nyc_output/ + +# histoire +.histoire/ + +# images +*.png *.jpg + +# svc:begin local-config sha256=0cb2591848c4e5675766aa516f16dfb9981fc52e1dcbadd8cec89b6982db927d +svc.local.json +AGENTS.local.md +# svc:end local-config diff --git a/AGENTS.md b/AGENTS.md index 2023cd6..bc1e997 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,27 +1,64 @@ -# `@inkcre/ui` coding guide +# InKCre UI This repository owns the InKCre design system and UI libraries. -## Project Structure +Reason in English. Communicate with humans in Chinese. -- `packages/`: this is a monorepo - - `web`: `@inkcre/ui-web`, the InKCre UI library for web projects -- `tokens/` - - `inkcre.tokens.json`: Design tokens follows W3C DTCG format -- `scripts/` - - `build-tokens.ts`: Transform design tokens to code +## Repository Map + +- `packages/web/`: `@inkcre/ui-web`, its public components, styles, stories, + generated consumer skill, and package-local instructions. +- `tokens/inkcre.tokens.json`: W3C DTCG design-token source. +- `scripts/`: deterministic token, package-metadata, Agent Skill, contract, and + release preparation commands. +- `docs/index.md`: durable documentation navigation. +- `tasks/`: volatile task packets retained only while their parent task is active. + +## Knowledge Owners + +- Repository and package entry points: `README.md` and `packages/web/README.md`. +- Public package API: package exports, component manifest, TypeScript source, + generated declarations, and styles. +- Component usage evidence: `packages/web/stories/`. +- UI consumer Agent guidance: `packages/web/skill.seed.json` and the generated + `packages/web/skills/ui-web/` artifact. +- Package migration contract: `packages/web/MIGRATION.md`. +- Build, release, preview, and production behavior: package scripts, repository + scripts, and `.github/workflows/`. +- Repeated subtree hazards: the nearest local `AGENTS.md`. ## Coding Guidelines - [Coding for Human](/.github/instructions/coding-for-human.instructions.md) -## Development Workflows +## Development Workflow - Follow the organization-wide [Git and GitHub Governance](https://github.com/InKCre/.github/blob/main/GOVERNANCE.md) and [contribution workflow](https://github.com/InKCre/.github/blob/main/CONTRIBUTING.md) for branches, pull requests, release authority, and delivery boundaries; repository-local documents own exact commands. -- Package manager is PNPM -- Use changeset to summarize your changes (run `pnpm changeset` after you made changes.) +- Runtime: Node.js 22.22.3; package manager: pnpm 11.17.0. +- Install with `pnpm install --frozen-lockfile`; run the full contract with + `pnpm check`. +- Use `pnpm changeset` for an observable published-package change. +- Generated tokens, package metadata, and `skills/ui-web` are checked-in + projections. Change their source owner and run `pnpm generate`; do not edit + generated output directly. - Follow the organization-wide [Verification and Test Policy](https://github.com/InKCre/.github/blob/main/TESTING.md). This repository prefers type-check, lint, generated-contract checks, story builds, and real consuming-page review; it currently admits no automated unit/component suite. +- Require explicit Human authorization before commit, push, publication, or + external repository/settings mutation. + + +## SVC + +Use `svc --help` or `svc --help`. + +- `svc status`: inspect project state +- `svc lookup`: read SVC guidance +- `svc task init`: create a task packet +- `svc task grow`: inspect packet shape without changing files +- `svc dev`: manage declared development targets + +If `AGENTS.local.md` exists, read it after this file. It is ignored local guidance; shared rules belong here. + diff --git a/README.md b/README.md index 204f717..9b66a6c 100644 --- a/README.md +++ b/README.md @@ -60,11 +60,12 @@ coverage, and generated Agent Skills. ## Histoire delivery -`UI checks` builds Histoire as part of the repository contract. Successful -same-repository pull requests publish that checked output to the stable -`pr-N.design-dd4.pages.dev` preview alias. Closing the pull request replaces -the alias with a noindex marker; Cloudflare retains older immutable deployment -URLs as platform history. +`UI checks` validates Histoire as part of the repository contract. After a +successful same-repository run, the trusted Preview workflow checks out that +exact pull-request head, builds Histoire itself, and publishes it to the stable +`pr-N.design-dd4.pages.dev` preview alias. Closing the pull request replaces the +alias with a noindex marker; Cloudflare retains older immutable deployment URLs +as platform history. A protected `main` push builds Histoire again as a focused release, transfers the exact same-run artifact to the deployment job, and publishes it to diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c086754 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,19 @@ +# Documentation + +## Navigation + +- [Repository overview](../README.md) +- [Web package usage and development](../packages/web/README.md) +- [Package migration contract](../packages/web/MIGRATION.md) +- [UI Web Agent Skill generation](../scripts/build-agent-skills.md) + +Public component and styling facts are owned by source, package exports, +generated declarations, stories, and the package consumer skill. Delivery +behavior is owned by package scripts, repository scripts, and GitHub workflows; +this directory does not copy those executable contracts. + + +## SVC Corpus + +Use `svc lookup` when packaged Sustainable Vibe Coding Corpus guidance is relevant, and discover its browse/search/read grammar through `svc lookup --help`. Project documentation outside this marked block remains Consumer-owned. + diff --git a/scripts/build-agent-skills.md b/scripts/build-agent-skills.md index 45b396f..32a6a85 100644 --- a/scripts/build-agent-skills.md +++ b/scripts/build-agent-skills.md @@ -1,146 +1,30 @@ -# build-agent-skills.ts +# UI Web Agent Skill -Generates Agent Skills for the `@inkcre/ui-web` package following the [agentskills.io](https://agentskills.io) specification. +`build-agent-skills.ts` generates the single TanStack Intent skill shipped by +`@inkcre/ui-web` at `packages/web/skills/ui-web/`. -## Overview +## Owners -This script creates properly formatted Agent Skills for component documentation. Skills are organized folders containing `SKILL.md` files with YAML frontmatter and markdown content. +- `packages/web/skill.seed.json` owns reviewed component intent, selection, + composition, integration, styling, and mistake guidance. +- Component source, the public component manifest, and Histoire stories own + mechanically derived API and variant facts. +- `scripts/build-agent-skills.ts` combines those sources into the generated + skill and references. Generated files must not be edited directly. +- `scripts/check-package-contract.ts` proves the packed package exposes the + skill at the discoverable `skills/ui-web` path and excludes the retired + `agent-skills/` path and maintainer seed. -## What are Agent Skills? - -Agent Skills are a standardized format for packaging domain-specific expertise that AI agents can discover and load dynamically. Each skill contains: - -- **YAML frontmatter**: Metadata including `name` and `description` -- **Markdown content**: Instructions, examples, and reference material -- **Optional directories**: Scripts, references, and assets - -Learn more at [agentskills.io](https://agentskills.io/specification). - -## Generated Skills - -The script automatically generates the **components** skill in `agent-skills/components/`: - -### components - -Main skill for using the component library with individual component reference files: - -- Main `SKILL.md` with overview and setup -- `references/` directory with one markdown file per component -- Each component file includes props, events, types, and usage examples -- Components are loaded on-demand by referencing their individual files - -## Manual Skills - -The following skills are maintained manually in `agent-skills/`: - -### router - -Router integration patterns with Vue Router adapter setup. - -### i18n - -Internationalization setup with vue-i18n integration. - -### styling - -Design token system with SCSS utilities and theming examples. - -### best-practices - -Development guidelines including naming conventions and accessibility. - -## Usage - -From the repository root: +## Commands ```bash pnpm build-skills +pnpm check:skills ``` -From the web UI package: - -```bash -cd packages/web -pnpm build:skills -``` - -## Output Structure - -``` -packages/web/agent-skills/ -├── components/ -│ ├── SKILL.md # Main components skill -│ └── references/ # Individual component files -│ ├── inkButton.md -│ ├── inkInput.md -│ └── ... -├── router/ -│ └── SKILL.md # Manual -├── i18n/ -│ └── SKILL.md # Manual -├── styling/ -│ └── SKILL.md # Manual -└── best-practices/ - └── SKILL.md # Manual -``` - -Each `SKILL.md` follows the agentskills.io specification: - -```markdown ---- -name: skill-name -description: What this skill does and when to use it ---- - -# Skill Content - -Instructions and examples... -``` - -## Integration - -Skills are: - -- Generated during the build process (components only) -- Shipped with the npm package (via `agent-skills/` in `files` array) -- Automatically discovered by compatible AI agents -- Loaded on-demand when relevant to user's task - -## Agent Compatibility - -These skills work with: - -- Claude Code (Anthropic) -- GitHub Copilot (VS Code, CLI) -- OpenAI Codex -- Cursor -- Any agent supporting the agentskills.io standard - -## How Agents Use Skills - -1. **Discovery**: Agent scans `agent-skills/` directory -2. **Metadata Loading**: Reads YAML frontmatter (name, description) -3. **Tool Registration**: Exposes skills as callable functions -4. **Activation**: User's query triggers relevant skill -5. **Content Loading**: Main SKILL.md and referenced files loaded on-demand -6. **Execution**: Agent follows skill instructions - -## Progressive Disclosure - -The components skill uses progressive disclosure: - -- Main `SKILL.md` provides overview and component list -- Individual component files in `references/` are loaded only when needed -- This keeps context window small while providing access to all details - -## Maintenance - -The script automatically: - -- Extracts component info from TypeScript files -- Cleans Histoire-specific syntax from documentation -- Generates valid YAML frontmatter -- Creates compliant directory structure -- Validates skill names (lowercase, hyphens only) +Use `pnpm build-skills` after changing a source owner. `pnpm check:skills` +rejects stale generated output and validates the result with TanStack Intent. -Manual skills should be updated directly in `agent-skills/` directory. +This product skill belongs to the published UI package. Organization-wide +Agent workflow skills and repository instructions have different consumers +and do not belong in this package. diff --git a/svc.json b/svc.json new file mode 100644 index 0000000..885a9bf --- /dev/null +++ b/svc.json @@ -0,0 +1,4 @@ +{ + "schema_version": 3, + "corpus_version": "14.0.0" +} diff --git a/tasks/ui-engineering/execution-01.md b/tasks/ui-engineering/execution-01.md deleted file mode 100644 index 0a4eabe..0000000 --- a/tasks/ui-engineering/execution-01.md +++ /dev/null @@ -1,47 +0,0 @@ -# Execution 01 — Reproducible Engineering Baseline - -Execution 01 was explicitly authorized by Sir on 2026-07-27. This record describes the bounded implementation slice; it is not a publish, consumer mutation, or GitHub-governance change. - -## Delivered - -- Initially pinned Node `22.22.3` and pnpm `11.17.0` through `.node-version`, `engines`, and `packageManager`; Execution 02 later moved Node authority to pnpm's locked runtime. -- Added an explicit pnpm 11 build-script allowlist for `@parcel/watcher` and `esbuild`, the native tooling required by Sass, Vite, and TSX. -- Removed the package-local lockfile; the root `pnpm-lock.yaml` is the only dependency graph. -- Added root `dev`, `build`, `type-check`, `test`, `story`, `format`, `lint`, generator, and `check` commands. -- Introduced a bounded formatting baseline for shared engineering entrypoints and blocking-error linting without rewriting the legacy component tree. -- Added a generated-output freshness check that snapshots outputs, runs both generators, and fails only if generation changes them. It does not require a clean Git worktree. -- Made Vue source checking explicit and made vite-plugin-dts diagnostics fail package/locales builds. -- Resolved `InkPicker`'s pnpm-linked Vue declaration inference while bundling the internal shared type so rolled declarations expose only portable `vue` imports. -- Refreshed stale generated Agent Skills. -- Replaced weak `InkDialog` tests with public DOM/interaction assertions. -- Fixed and covered uncontrolled `InkImage` expansion, controlled-model behavior, close forwarding, Escape handling, and Scrim close-button propagation. -- Added a patch changeset for the public image/scrim fixes. -- Added a read-only, SHA-pinned pull-request workflow with frozen installation and the canonical root check. -- Updated the release workflow to use the same pinned runtime, frozen installation, and root check before its existing release path. -- Replaced stale root development documentation with the actual toolchain and root commands. - -## Verification - -| Gate | Result | -|---|---| -| `pnpm format:check` | pass for the bounded engineering baseline | -| `pnpm lint` | pass for blocking Oxlint diagnostics | -| `pnpm check:generated` | pass; tokens and Agent Skills unchanged by regeneration | -| `pnpm type-check` | pass for root scripts and Vue source | -| `pnpm test` | pass; 11 files / 103 tests | -| `pnpm build` | pass; declaration diagnostics are fatal | -| declaration portability scan | pass; no `.pnpm`, relative `node_modules`, or `@vue/shared` import | -| `pnpm story` | pass; 21 stories / 108 variants | -| `pnpm check` | pass in the working tree | -| disposable copy: pnpm `11.17.0` frozen install + `pnpm check` | pass | -| `pnpm changeset status` | patch bump for `@inkcre/web-design` | -| `git diff --check` | pass | - -## Known Warnings And Deferred Boundaries - -- The committed npm credential placeholder still produces pnpm's untrusted-project-config warning. This is intentionally owned by Execution 02. -- Vite/Histoire still warn about the invalid bare `uno` export; the packed package remains unusable until Execution 03 fixes all exports and missing targets. -- Style Dictionary reports token collisions even though output is stable. Classification belongs with the generator contract in Execution 03. -- API Extractor uses bundled TypeScript 5.8 while the workspace uses 5.9; output is currently portable, but the tooling warning should be removed during the package-contract pass. -- Histoire alpha emits setup-export warnings while still producing the complete catalog. Story runtime/tooling modernization belongs to Execution 04. -- The new workflow has not run on GitHub because no push was authorized. Local and disposable-copy execution prove the command graph, not remote governance. diff --git a/tasks/ui-engineering/execution-02.md b/tasks/ui-engineering/execution-02.md deleted file mode 100644 index ec353ca..0000000 --- a/tasks/ui-engineering/execution-02.md +++ /dev/null @@ -1,42 +0,0 @@ -# Execution 02 — Registry Authentication Boundary - -Execution 02 was explicitly authorized by Sir on 2026-07-27. This record describes the bounded local implementation; it is not a publish, consumer mutation, package-visibility change, or remote package-access grant. - -## Delivered - -- Reduced the committed `.npmrc` to the `@inkcre` registry route. It contains no credential or environment-expanded credential placeholder. -- Documented the native interactive GitHub Packages login flow, the trusted user-config alternative, and direct package-manager remediation without adding an auth doctor. -- Removed the ineffective root `publishConfig`. -- Added the GitHub repository link and GitHub Packages registry to the publishable `@inkcre/web-design` package. -- Configured `actions/setup-node` with the `@inkcre` scope and GitHub Packages registry in PR and release workflows. -- Removed the unused Copilot setup workflow after Sir confirmed that the project no longer uses Copilot. -- Replaced `.node-version` and the root Node engine pin with pnpm's `devEngines.runtime`; CI setup-node steps now configure cache and registry without owning the project runtime. -- Removed shell `npm config set` calls from the release workflow. -- Declared explicit release permissions for repository changes and package publication. -- Bound `NODE_AUTH_TOKEN` only to the SHA-pinned Changesets action that performs the release operation. Frozen install and package lifecycle scripts do not receive it. -- Added a patch changeset for the publishable package metadata change. - -The producer PR workflow intentionally retains only `contents: read`: its dependency graph contains no external private `@inkcre` package. `packages: read` belongs on a consumer job when that job actually installs a private package. - -## Verification - -| Gate | Result | -|---|---| -| missing auth with empty trusted config | native package-manager failure | -| temporary trusted user config referencing the process token | resolved `@inkcre/web-design@1.2.2` | -| disposable `../client-web` copy with trusted config and `--ignore-scripts` | frozen registry install passed; web, ext-dev-utils, and Twitter importers resolved `1.2.2` | -| committed `.npmrc` | exactly one scoped registry route | -| local `pnpm install --frozen-lockfile` | pass with no project-auth warning | -| pnpm-managed runtime | lock resolves `node@runtime:22.22.3`; `pnpm exec node` and `pnpm node` report `v22.22.3` | -| `pnpm check` | pass; 11 files / 103 tests and 21 stories / 108 variants | -| `pnpm changeset status` | patch bump for `@inkcre/web-design` | -| current GitHub Package metadata | private and linked to `InKCre/design` | - -The auth proofs used a disposable npm-compatible user config and removed it afterward. They did not print or persist the process token and left the real user configuration and `../client-web` worktree unchanged. The consumer install disabled lifecycle scripts while the token was present. - -## Remote Proof Still Pending - -- The updated PR workflow has not run because no push was authorized. -- The release path has not published with its repository `GITHUB_TOKEN`; that proof requires a real release after the packed contract is repaired. -- The future `@inkcre/ui-web` package does not exist yet, so its visibility, repository inheritance, `client-web` Actions access, and Dependabot path cannot be configured or proven in this slice. -- The current package remains private. The new package's visibility is still an explicit decision before Execution 05. diff --git a/tasks/ui-engineering/execution-03.md b/tasks/ui-engineering/execution-03.md deleted file mode 100644 index 30d3490..0000000 --- a/tasks/ui-engineering/execution-03.md +++ /dev/null @@ -1,33 +0,0 @@ -# Execution 03 — Package And Generator Contract - -Execution 03 was completed locally on 2026-07-27 as part of Sir's authorization to carry the engineering roadmap through Execution 05. This slice repairs the published artifact before introducing the new package identity; it does not mutate `../client-web`. - -## Delivered - -- Replaced the invalid mixed `exports` map with explicit JavaScript, declaration, CSS, Sass, token, locale, utility, and UnoCSS subpaths. -- Built every claimed JavaScript subpath and its declarations. Raw component-directory imports remain private and are rejected by the package boundary. -- Externalized package peers consistently, including the JSON editor's direct `vscode-languageserver-textdocument` dependency. -- Established one public-component manifest for generated component metadata, Vue global component types, package version data, Agent Skills, and story coverage. -- Anchored token and Agent Skill generation to the repository root instead of the caller's working directory. -- Added stale-generation gates for package metadata, tokens, and Agent Skills. -- Added a packed consumer contract that creates a tarball, installs it in an isolated fixture, and probes Node, Vue/TypeScript, CSS, Sass, tokens, locales, utilities, UnoCSS, side effects, and forbidden raw subpaths. -- Added a changeset policy gate for package behavior, contents, public documentation, and generated token changes. -- Reworked token-update preparation into a deterministic payload-to-source-to-generated-output-to-changeset pipeline. The GitHub workflow validates input, uses collision-resistant branch and changeset names, and is covered by a local fixture. - -## Verification - -| Gate | Result | -|---|---| -| packed `@inkcre/web-design@1.2.2` contract | pass | -| Node and Vue/TypeScript consumer probes | pass | -| CSS, Sass, token, locale, utility, and UnoCSS probes | pass | -| raw component subpath rejection | pass | -| declaration leak scan | no `.pnpm`, relative `node_modules`, or private source leaks | -| generated-output second pass | clean | -| deterministic token workflow fixture | pass | - -The main JavaScript artifact shrank from approximately 4.6 MB to 258 KB after peer externalization. API Extractor still reports that its bundled TypeScript 5.8 compiler is older than the workspace TypeScript 5.9 compiler; this is an upstream compatibility warning, not a suppressed package diagnostic. - -## Boundary - -The repaired artifact can be reproducibly repacked and exercised under the old package identity. This preserves the pre-rename identity proof; it does not claim that the immutable historical registry tarball was rewritten or repaired. Consumer alias removal and frozen installation of the new package belong to Execution 06, after the new exact registry version exists. diff --git a/tasks/ui-engineering/execution-04.md b/tasks/ui-engineering/execution-04.md deleted file mode 100644 index 8dca9bd..0000000 --- a/tasks/ui-engineering/execution-04.md +++ /dev/null @@ -1,30 +0,0 @@ -# Execution 04 — Story And Component Verification Baseline - -Execution 04 was completed locally on 2026-07-27 as part of Sir's authorization to carry the engineering roadmap through Execution 05. - -## Delivered - -- Kept Histoire as the interactive component catalog and moved stories out of runtime component directories. -- Organized the 21 public-component stories and companion documentation under user-facing `controls`, `feedback`, `forms`, `media`, `overlays`, and `specialized` categories. -- Added a manifest-backed coverage gate requiring exactly one story and one story document for every public component, with no orphaned catalog files. -- Added shared responsive and background presets. -- Added a light/dark theme bridge that maps Histoire's `html.dark` state to the package's `data-theme` contract, plus a focused runtime test. -- Replaced missing image assets in catalog examples with the repository's existing SVG fixture. -- Included stories in format, lint, and type-check scope and kept Histoire build smoke in the canonical root check. - -## Verification - -| Gate | Result | -|---|---| -| public component story coverage | 21 / 21 | -| Histoire variants | 108 | -| orphan story or story-document files | none | -| theme bridge unit test | pass | -| behavior suite | 12 files / 104 tests | -| Histoire production build | pass | - -Histoire `1.0.0-alpha.5` emits known setup-module export warnings during the successful production build. They are retained as visible upstream warnings instead of being hidden by fake compatibility exports. - -## Responsibility Boundary - -Story coverage proves that public components are discoverable and that catalog states build. Vitest owns behavior contracts. Ten public components still lack a focused behavior test; that is an explicit quality backlog rather than a reason to conflate catalog coverage with behavioral proof. Playwright and screenshot regression remain deferred until deterministic fonts, animation policy, viewports, and browser ownership are defined. diff --git a/tasks/ui-engineering/execution-05.md b/tasks/ui-engineering/execution-05.md deleted file mode 100644 index 33bbbfa..0000000 --- a/tasks/ui-engineering/execution-05.md +++ /dev/null @@ -1,51 +0,0 @@ -# Execution 05 — Local Identity Migration And New Package Publication - -Execution 05 was explicitly authorized by Sir on 2026-07-27. This record owns the local identity transition and the first exact-version publication of the new package; consumer mutation and remote repository rename remain outside this slice. - -## Delivered Locally - -- Renamed the private workspace from `inkcre-design` to `@inkcre/ui`. -- Moved the web package from `packages/web-design` to `packages/web`. -- Renamed the published package from `@inkcre/web-design` to `@inkcre/ui-web` while retaining version lineage at `1.2.2`. -- Renamed the Vite library identifier to `InKCreUIWeb`. -- Updated generators, Histoire, documentation, changesets, package metadata, generated Agent Skills, lockfile importers, and developer examples to the new identity. -- Preserved all `Ink*` component APIs, `.ink-*` CSS classes, token APIs, and accurate Design System/design-token vocabulary. -- Set the leaf package and Changesets access policy to restricted/private GitHub Packages publication. -- Added a package-local migration guide that freezes `@inkcre/web-design@1.2.2` as the immutable rollback artifact, rejects a forwarding wrapper without evidence of unknown consumers, and defers deprecation until known consumers have migrated. -- Recorded `../client-web` revision `71a64fd` as the bounded pre-migration consumer state. - -## Publication And Registry Proof - -- Published `@inkcre/ui-web@1.2.2` to the InKCre GitHub Packages npm registry after confirming that the exact version did not already exist. -- GitHub reports one version, private visibility, and registry integrity `sha512-26u+VHciYNpPN9BHwwMoqqPWPN56JsNoa1n5ZkfY7aE5Rq/UwUuVgrWpY1tfzRBo9ec+Fvu1IT4lBj8xLhs9ug==`. -- A disposable empty project installed the exact registry version with lifecycle scripts disabled and successfully imported the package root, version export, and Vue plugin. -- Linked the package to the current `InKCre/design` source repository. Execution 07 will rename that repository to `InKCre/ui`; no premature remote rename was performed here. -- Granted `InKCre/client-web` GitHub Actions access with the `Read` role. No Codespaces access or broader package visibility was added. -- Kept `@inkcre/web-design@1.2.2` installable and undeclared as deprecated. Consumer manifests remain unchanged until Execution 06. - -## Verification - -| Gate | Result | -|---|---| -| reproducible packed old-name `@inkcre/web-design@1.2.2` identity contract | pass | -| reproducible packed new-name `@inkcre/ui-web@1.2.2` contract | pass | -| exact GitHub Packages version and integrity | `1.2.2`; verified | -| disposable exact-version registry install and ESM import | pass | -| package visibility and source association | private; `InKCre/design` | -| `client-web` Actions package access | `Read` | -| package changeset status | patch release for `@inkcre/ui-web` | -| `../client-web` worktree | unchanged | - -The old-name contract gate re-identifies and repacks the current repaired artifact -as `@inkcre/web-design`; it is a reproducible identity-compatibility probe, not a -byte-for-byte assertion about the immutable historical registry tarball. The -registry artifact is separately proven to remain available for the existing -consumer rollback path. - -## Deferred By Design - -- `@inkcre/web-design` is not deprecated until Execution 06 completes. -- `../client-web` manifest, lockfile, aliases, and runtime imports are unchanged until Execution 06. -- Remote repository rename and local checkout rename remain Execution 07 and require their own authorization. -- Web DX and Intent-based Agent Skill delivery remain the separate post-migration Executions 08A and 08B. -- The optional local source overlay remains Execution 09. diff --git a/tasks/ui-engineering/execution-06.md b/tasks/ui-engineering/execution-06.md deleted file mode 100644 index 4d809f2..0000000 --- a/tasks/ui-engineering/execution-06.md +++ /dev/null @@ -1,100 +0,0 @@ -# Execution 06 — Registry-Backed Consumer Migration - -Sir explicitly started Execution 06 on 2026-07-27. It was committed, pushed, -and remotely verified on 2026-07-28. This slice migrates every known -`../client-web` consumer from the frozen old package to the already published -exact `@inkcre/ui-web@1.2.2` artifact. It did not introduce a source overlay or -change the producer toolchain or skill delivery. - -## Baseline And Scope - -- The bounded consumer baseline is `../client-web` revision - `71a64fd2fe1994aab659e9ccafbbe1b79bab48c5`. -- The three package importers are `apps/client-web`, - `packages/ext-dev-utils`, and `extensions/twitter`. -- `apps/client-webext` does not consume the UI package. -- Historical old-name evidence under `../client-web/tasks/**` remains - unchanged; active code, configuration, instructions, templates, and - documentation own the migration. - -## Delivered - -- Pinned all three importer manifests to exact `@inkcre/ui-web@1.2.2`. -- Regenerated the lockfile from GitHub Packages. Its package URL and - `sha512-26u+VHciYNpPN9BHwwMoqqPWPN56JsNoa1n5ZkfY7aE5Rq/UwUuVgrWpY1tfzRBo9ec+Fvu1IT4lBj8xLhs9ug==` - integrity match the Execution 05 publication evidence. -- Added the package's required - `vscode-languageserver-textdocument@^1.0.12` peer explicitly to the web app; - the lock also resolves the optional UnoCSS peer. -- Migrated Vue/TypeScript imports, global types, CSS and Sass subpaths, the - Vitest mock, web and Twitter Sass injection, developer instructions, and the - extension Vite template. -- Deleted the four Vitest aliases that bypassed the old package's invalid - exports through direct `node_modules`, `dist`, and Sass paths. The migrated - app now proves the public package exports instead of retaining renamed - workarounds. -- Added a release-age exception for only `@inkcre/ui-web@1.2.2`. The repository - records pnpm 11's built-in 24-hour gate, and this exact internally published - migration artifact was intentionally consumed on its publication day; the - broader supply-chain policy remains active. -- Active non-historical `@inkcre/web-design` references are zero. - -## Registry And Authentication Proof - -- A direct unauthenticated lookup returned HTTP 401, confirming that - repository configuration does not own a credential. -- The first install attempt inherited a stale `NODE_AUTH_TOKEN` and was - rejected without exposing the credential. -- A second attempt used the active GitHub CLI credential through a temporary - trusted user npmrc outside both repositories. It downloaded the new tarball - and regenerated the lock; the temporary file was then deleted. -- With Node `22.22.3`, pnpm `11.11.0`, the trusted temporary auth boundary, and - the regenerated lock candidate, `pnpm install --frozen-lockfile` passed - including the existing WXT postinstall. -- The installed graph contains one UI version, `1.2.2`, for all three - importers. A direct ESM smoke observed 21 `Ink*` exports, version `1.2.2`, - and the Vue plugin install function. - -No token, token placeholder, or machine-specific path was written to either -repository. - -## Verification - -| Gate | Result | -| --------------------------------------------- | ------------------------ | -| exact registry resolution and integrity | pass | -| `pnpm install --frozen-lockfile` | pass | -| active old-name and direct-alias search | zero | -| package-local and workspace TypeScript checks | pass | -| client-web Vitest | 10 files / 35 tests pass | -| client-web production build | pass | -| ext-dev-utils type check | pass | -| Twitter remote type check and build | pass | -| Chromium web extension type check and build | pass | -| root `pnpm check` | pass | -| type-aware Oxlint shadow lane | pass | -| native TypeScript 7 shadow lane | pass | -| `git diff --check` | pass | -| pre-rename complete Client checks | pass | -| post-rename complete Client checks rerun | pass | - -The root build proves the new JavaScript, declaration, CSS, Sass, token, and -global-component surfaces through the normal Vite/Vitest resolvers with no UI -filesystem alias. - -A supplemental `pnpm peers check` still reports three unrelated ecosystem -mismatches involving Rspack Module Federation, `zod-class`, and the Vite 8 -plugin graph. It reports no missing `@inkcre/ui-web` peer, and the canonical -type, test, and build gates are green; those diagnostics remain outside this -identity-only slice. - -## Rollback And Deferred Work - -- The consumer migration is committed as - `b08cade2e1b527dc5720e8e84de7b3c703cca8d6`. Reverting that bounded commit - restores the three old manifest entries, lock, imports, and aliases. -- `@inkcre/web-design@1.2.2` remains installable and is not yet deprecated. -- The remote repository rename is recorded in Execution 07; only the local - checkout directory rename remains deferred. -- Web DX/native TypeScript and Intent delivery remain Executions 08A and 08B. -- The optional source overlay remains Execution 09. diff --git a/tasks/ui-engineering/execution-07.md b/tasks/ui-engineering/execution-07.md deleted file mode 100644 index 77393a3..0000000 --- a/tasks/ui-engineering/execution-07.md +++ /dev/null @@ -1,170 +0,0 @@ -# Execution 07 — Remote Rename And Identity Closure - -## Status - -Execution 07 is in progress. The GitHub repository was renamed from -`InKCre/design` to `InKCre/ui` on 2026-07-28 after the registry-backed -Execution 06 consumer run passed. The repository, package association, local -remote, fresh-clone path, release workflow, post-rename consumer package -access, and Cloudflare Pages build are proven. The release-PR version -generator, required status-check governance, a live Figma dispatch, and the -local checkout directory remain explicit closure items. - -## Applied Identity Mutation - -| Surface | Result | -| --- | --- | -| GitHub repository | `InKCre/ui` | -| Stable repository ID | `R_kgDOQbKaGg` before and after rename | -| Default branch / visibility | `main` / public | -| Old web URL | HTTP 301 to `https://github.com/InKCre/ui` | -| Old Git URL | still resolves `main` through GitHub's rename redirect | -| Local `origin` | `ssh://git@github.com/InKCre/ui` | -| Repository description | `InKCre design system and UI libraries` | -| Homepage | cleared because the old Storybook hostname does not resolve | -| GitHub Package source | private `@inkcre/ui-web`, package ID `14055172`, associated with `InKCre/ui` | -| Default Actions authority | `read`; workflow-token PR approval disabled | - -The local checkout directory remains -`/Volumes/WorkSSD/Development/InKCre/design`. Renaming that directory while the -current tool owns it would invalidate the active workspace, so it is deferred -to a user/session boundary. - -## Remote Proof - -1. `../client-web` commit `b08cade` was pushed to `main`. -2. Client checks run - [`30320257162`](https://github.com/InKCre/client-web/actions/runs/30320257162) - passed before the producer rename. -3. The same run was rerun after the producer rename. All four executable jobs - passed again, including frozen private-package installation, workspace - contracts, native TypeScript 7 shadow checking, Chromium/Firefox extension - contracts, and the isolated browser/database chain. This proves that the - `InKCre/client-web` Actions Read grant survived the package's source - association change to `InKCre/ui`. -4. Producer commits through `1d4ab92` were pushed to the renamed repository. - Release run - [`30320502078`](https://github.com/InKCre/ui/actions/runs/30320502078) - passed checkout, frozen installation, the full root check, and Changesets - execution under the new repository identity. -5. A new shallow clone from `ssh://git@github.com/InKCre/ui` passed frozen - installation and the full root check on pnpm `11.17.0` and Node `22.22.3`: - 12 test files / 104 tests, package build and packed contracts, and 21 stories - / 108 variants. - -## Release-PR Defect And Bounded Fix - -Changesets created release PR -[`#31`](https://github.com/InKCre/ui/pull/31) for `@inkcre/ui-web@1.2.3`. -Its first `UI checks` execution required a manual rerun because the PR was -created by `github-actions[bot]`. The rerun then exposed a valid generated-file -failure: - -```text -packages/web/package.json 1.2.2 -> 1.2.3 -packages/web/src/version.ts remained 1.2.2 -``` - -The bounded local fix: - -1. makes `changeset:version` run `changeset version` and then regenerate package - metadata; -2. configures `changesets/action@1.9.0` to use that version command when - creating or updating the release PR; -3. makes the manual publish entrypoint reuse the same version command. - -The pinned action's own `action.yml` confirms that its `version` input must run -the version/update command and that the default is `changeset version`. A -disposable clone rehearsed `1.2.2 -> 1.2.3`, generated the new version constant, -and passed `check:generated`. - -This fix was committed as `a423ea0` and pushed after Sir's explicit -authorization. Release run -[`30322305378`](https://github.com/InKCre/ui/actions/runs/30322305378) passed -and refreshed PR #31. The refreshed diff contains matching -`@inkcre/ui-web@1.2.3` manifest and generated version values. - -The refreshed PR's workspace check then passed the complete root verification -but exposed a second changeset-gate boundary: `check-changeset.ts` tried to -read the three changeset files that a release PR intentionally deletes and -raised `ENOENT`. It also did not yet classify the generated `src/version.ts` as -part of a version-only release diff. The bounded local follow-up: - -1. permits generated `src/version.ts` in the release-version-only file set; -2. excludes deleted changeset paths before reading current changeset contents. - -A disposable checkout of the actual release branch now reports -`Changesets release-version change detected.` A negative fixture that combines -the deleted changesets with an additional source change fails cleanly with the -required-changeset diagnostic instead of throwing `ENOENT`. This follow-up is -implemented and verified; Sir explicitly authorized its commit on 2026-07-28. -PR #31 must not be merged or used to publish until the updated release PR is -green. - -## Cloudflare Pages Correction - -The failed `Cloudflare Pages` check on PR #31 is independent of the package -generator defect. The authenticated deployment log proves that the Pages -project still stores the removed identity: - -```text -Git repository: InKCre/design -Build command: pnpm run --filter web-design story:build -Build output: packages/web-design/.histoire/dist -``` - -The old Git URL redirect allowed cloning, but the old package filter matched no -workspace and the old output directory did not exist. The proposed bounded -correction is: - -```text -Git repository: InKCre/ui -Build command: pnpm story -Build output: packages/web/.histoire/dist -Root directory: unchanged (repository root) -``` - -Sir confirmed the external mutation. Cloudflare now stores `pnpm story`, -`packages/web/.histoire/dist`, and the unchanged repository root. Retried -deployment `2aae170b-edb4-4a14-a86c-86a6bfb51f96` built 21 stories / 108 -variants, uploaded 96 files, deployed successfully, and changed the PR's -`Cloudflare Pages` check to pass. - -The Dashboard still displays the cached `InKCre/design` source label, but the -Git integration received the renamed repository's release PR and cloned the -correct commit through GitHub's repository relationship. Updating that label -would require disconnecting and reconnecting the Git integration. Do not take -that more disruptive action while the functional event, clone, preview, and -deployment contracts are green. - -## Remaining Closure Gates - -1. Commit and push the authorized changeset deletion/version-only gate fix, - then prove the refreshed `Reproducible workspace check`. -2. Add that proven exact - context to the existing `main`/`develop` ruleset. Do not install a failing or - unproven required check. -3. Merge/publish PR #31 only under an explicit release decision. Verify the new - GitHub Package version, GitHub Release, exact-version consumer installation, - and source association afterward. -4. Have the external Figma owner trigger one live `update-tokens` dispatch. - Confirm that the renamed repository receives it and that the resulting PR - contains validated token source, generated artifacts, and a package - changeset. The deterministic fixture remains the required gate; the live - dispatch is supplementary integration evidence. -5. Rename the local checkout directory to `ui` only at a session boundary. - -## Rollback - -The repository rename is reversible without deleting history or packages: - -```text -gh repo rename design --repo InKCre/ui --yes -git remote set-url origin ssh://git@github.com/InKCre/design -``` - -After a rollback, recheck the stable repository ID, package source association, -Cloudflare Git/build settings, and the client Actions package-read run. The -published `@inkcre/ui-web@1.2.2` and immutable -`@inkcre/web-design@1.2.2` artifacts remain available; no unpublish or package -rewrite is part of rollback. diff --git a/tasks/ui-engineering/execution-08a.md b/tasks/ui-engineering/execution-08a.md deleted file mode 100644 index 576ffb4..0000000 --- a/tasks/ui-engineering/execution-08a.md +++ /dev/null @@ -1,176 +0,0 @@ -# Execution 08A — Web DX And Native TypeScript - -Execution 08A is complete and published in `@inkcre/ui-web@1.3.0`. Sir -authorized it on 2026-07-28 after the registry-backed consumer migration and -remote identity closure. The bounded change was committed as `f9a65a3`, and -Ubuntu glibc CI passed before release. - -## Why This Slice Exists - -- Oxlint `1.75.0` and Oxfmt `0.60.0` are installed at the workspace root, but - `packages/web` has no package-local lint, format, or fix commands and no - package-specific configuration. -- The root formatting command does not cover `packages/web/src`, so the - component source and Vue SFCs do not currently share the checked formatting - contract applied to stories and configuration. -- TypeScript `7.0.2` is native, but its programmatic API is not a drop-in - replacement for the classic API consumed by `vue-tsc`, Volar, `tsx`, and - declaration tooling. -- `typescript-native-bridge` keeps the classic TypeScript host/API while using - the TypeScript 7 checker. It is a third-party compatibility boundary and must - be pinned exactly, verified on every supported CI platform, and removable in - one dependency/lockfile revert. -- A fresh disposable checkout exposed an existing self-hosting defect: - CodeMirror and VS Code language-service peers imported by source were - available in the long-lived workspace but not declared as web-package - development dependencies. TypeScript 7 also correctly exposed missing - ambient declarations for Sass and `virtual:uno.css`. - -## Ownership Model - -- `packages/web` owns the commands and configuration that developers invoke - while editing Vue, TypeScript, stories, tests, and styles. -- The workspace root owns TypeScript resolution because all tools importing - the `typescript` package must see one compatible host. A leaf-only override - would create a mixed compiler graph. -- Root commands remain the canonical CI orchestration surface and delegate the - web-specific work to the leaf package. -- Oxlint remains a syntax/correctness linter. `vue-tsc` remains the - authoritative Vue semantic and declaration checker. - -## Planned Work - -1. Add package-local `format`, `format:check`, `lint`, and `lint:fix` commands - and focused Oxfmt/Oxlint configuration for source, Vue SFCs, stories, - tests, styles, and package configuration. -2. Enable the built-in Vue and Vitest Oxlint plugins, remove `--quiet`, and - clean the existing warning baseline so CI can reject new warnings. - `lint:fix` uses safe fixes only; dangerous suggestions remain explicit. -3. Keep type-aware Oxlint out of the required gate. The current implementation - cannot replace Volar's `.vue` virtual-file graph and duplicated type - diagnostics would add cost without authoritative coverage. -4. Declare every peer imported while developing/building the package as a - matching dev dependency, while retaining the peer dependency as the - consumer contract. -5. Add the ambient Vite/style/Uno declarations needed by the native checker - and remove TypeScript options that no longer exist in TypeScript 7 when - they have no remaining semantic purpose. -6. Upgrade `vue-tsc` to the proven current compatible release. -7. Pin one exact `typescript-native-bridge` build and apply the pnpm 11 - TypeScript override at the workspace root. Record both its classic host - version and embedded `tsgo` version; never use `latest` or a range. -8. Capture the stock compiler diagnostics and declaration/package outputs - immediately before cutover, then make the bridge-backed checker canonical - only after parity. Do not retain a permanent dual compiler lane. -9. Replace the Prettier editor recommendation with the official Oxc extension - and provide project-scoped Oxc plus workspace-TypeScript settings without - storing a machine path. -10. Keep the existing root `pnpm check` and frozen CI entrypoint; add no - separate doctor or wrapper whose only job is to restate native failures. - -## Preflight Evidence - -The 2026-07-27 disposable macOS arm64 probe used -`typescript-native-bridge@6.0.3-bridge.7.tsgo.7.0.2` and `vue-tsc@3.3.8`. -The first run failed on undeclared source-development peers and missing -non-TypeScript module declarations. After adding those explicit prerequisites: - -- root `tsc` and package `vue-tsc` both loaded the bridge; -- the complete root/package type check passed; -- the web build, declaration rollup, subpath declarations, finalization, and - generated-skill build passed. - -This proves feasibility on one platform, not permission to adopt the exact -versions or proof of Linux CI parity. - -## Implemented Result - -- `packages/web` owns focused Oxfmt and Oxlint configuration plus - `format`, `format:check`, `lint`, and safe `lint:fix` commands. The checked - surface includes Vue/TypeScript source, tests, stories, styles, and package - configuration. -- The warning baseline is clean with Vue and Vitest plugins enabled. Existing - false positives around the generic picker's runtime prop/event declarations - are narrowly disabled for that file; type-aware Oxlint remains outside the - required gate. -- The workspace override pins - `typescript-native-bridge@6.0.3-bridge.7.tsgo.7.0.2`. The manifest keeps - stock `typescript@5.9.3`, so removing the one override and restoring the - lockfile slice is the rollback. -- `vue-tsc@3.3.8`, every directly imported development peer, Vite/style/Uno - ambient modules, and a dedicated declaration tsconfig close the - clean-install gaps. -- The official Oxc extension replaces Prettier in workspace recommendations. - Project settings select Oxc formatting/fixes and the workspace TypeScript - SDK without a machine-specific path. -- Histoire ignores the library-only `vite:dts` plugin through its supported - `viteIgnorePlugins` option, so story builds no longer regenerate package - declarations or print declaration-output noise. - -## Declaration Compatibility Decision - -The bridge-backed emitter gives Vue arbitrary-extension declarations an -intermediate `*.vue.d.vue.ts` name. `vite-plugin-dts` also forced its internal -output root to the package directory. Its API Extractor rollup appeared to -succeed but retained imports to removed `.vue` declaration files, producing an -invalid packed type graph. - -The implemented boundary is deliberately smaller and observable: - -1. emit the complete declaration tree instead of the invalid rollup; -2. keep all declaration output inside `dist`; -3. normalize only `*.vue.d.vue.ts` to the conventional `*.vue.d.ts`; -4. fail package validation when a relative declaration import does not resolve - inside the tarball or an external declaration package is undeclared. - -`@vue/shared` is now a direct package dependency because generated public -types import its `IfAny` helper. The packed consumer retains its established -`skipLibCheck` posture: both stock TypeScript and the bridge expose unrelated -Vue `GlobalComponents` and third-party `unconfig` library errors when all -dependency declarations are rechecked. The explicit declaration topology and -dependency checks cover the publication regression without expanding this -slice into third-party declaration repair. - -## Local Proof - -- A same-source disposable stock-TypeScript `5.9.3` checkout and the - bridge-backed checkout both pass root/package type checking and the complete - web build. They emit the same declaration file set; reviewed differences are - representational ordering, quote style, and equivalent generic function - spelling. -- Root `tsc`, package `vue-tsc`, Vite declaration generation, and subpath - declaration generation all print the bridge activation banner. The host - reports `6.0.3`; the pinned bridge embeds `tsgo 7.0.2`. -- The working checkout passes the complete root check: 12 test files / 104 - tests, both packed package identities, and 21 Histoire stories / 108 - variants. -- A disposable copy with no dependency or build artifacts passes - `pnpm install --frozen-lockfile` and the same complete root check on macOS - arm64 with Node `22.22.3` and pnpm `11.17.0`. -- Ubuntu glibc proof follows the bounded commit in CI. Alpine/musl is - intentionally unsupported by the bridge. - -## Exit Proof - -- A disposable clean checkout passes `pnpm install --frozen-lockfile`, - package-local format/lint/type-check commands, and the canonical root check. -- The checked formatter covers `packages/web/src`, including Vue and SCSS. -- Oxlint surfaces Vue/Vitest diagnostics and rejects new warnings without - enabling its incomplete Vue type-check path. -- The bridge activation is observable in root `tsc`, `vue-tsc`, Vite - declaration generation, and subpath declaration generation. -- Native-checker diagnostics and the packed declaration contract are reviewed - against the pre-cutover stock baseline. -- macOS arm64 local verification and Ubuntu glibc CI are green. Alpine/musl is - not claimed as a supported bridge platform. -- Removing the workspace TypeScript override and restoring the prior - dependency/lockfile slice is sufficient rollback; no source fork or - compatibility wrapper is required. - -## Primary References - -- [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) -- [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) -- [TypeScript 7 native implementation](https://github.com/microsoft/typescript-go) -- [typescript-native-bridge](https://github.com/johnsoncodehk/typescript-native-bridge) -- [Vue language tools](https://github.com/vuejs/language-tools) diff --git a/tasks/ui-engineering/execution-08b.md b/tasks/ui-engineering/execution-08b.md deleted file mode 100644 index da5b618..0000000 --- a/tasks/ui-engineering/execution-08b.md +++ /dev/null @@ -1,166 +0,0 @@ -# Execution 08B — Intent-Based Agent Skill Delivery - -Execution 08B is complete and published in `@inkcre/ui-web@1.3.0`. Sir -authorized it on 2026-07-28 together with the web DX slice after consumer and -remote identity closure. Release PR #31 merged, and the exact registry -artifact passed installed-package discovery and loading. - -## Problem Statement - -The current package publishes five folders under `agent-skills/` and describes -them as automatically discoverable. TanStack Intent does not scan that path; -it discovers `skills/**/SKILL.md` at the installed package root. Running the -current pinned candidate against this repository reports no `skills/` -directory, so the present delivery claim is not mechanically true. - -The current content is also organized around documentation categories -(`components`, `router`, `i18n`, `styling`, and generic best practices) rather -than the developer's intent. It can enumerate APIs, but it does not reliably -teach an agent how to select and compose InKCre components for a product task. - -## Reference Interpretation - -`partner-up-dev/ui` provides the useful model, but TanStack Intent is only one -layer of that model: - -- Intent owns the standard package path, structural validation, installed - package discovery, trust allowlist, and `package#skill` loading. -- PartnerUp's own generator still owns component/source/story extraction, - curated intent, composition knowledge, caveats, references, and - deterministic output. - -InKCre should adopt that separation instead of expecting Intent to infer the -library's domain model or replacing one generated documentation dump with -another. - -## Target Shape - -```text -packages/web/ -├── skill.seed.json -└── skills/ - └── ui-web/ - ├── SKILL.md - └── references/ - ├── component-map.md - ├── composition-recipes.md - ├── integration.md - ├── styling-and-themes.md - ├── common-mistakes.md - └── components/ - └── Ink*.md -``` - -- `ui-web` is the one discoverable skill and intent router for the package. -- `SKILL.md` begins with task selection and composition workflow, then loads - only the relevant references. -- `skill.seed.json` is the curated semantic input for intents, preferred use, - avoid/caveat rules, composition partners, and durable source references. -- `component-manifest.json` remains the sole public-component authority. -- Component facts and maps are generated; product judgment and composition - guidance are explicit reviewed inputs. - -## Compatibility Decision - -Make a clean cut from `agent-skills/` to `skills/`: - -- `@inkcre/ui-web` has only just been published under the new identity and has - not yet been adopted by the known consumer. -- Repository and `../client-web` searches find no direct consumer of the old - file paths or skill IDs. -- The old path is not recognized by Intent, so maintaining a generated mirror - would preserve an unproven contract and double the stale-output surface. - -The change must still receive an explicit Changeset and migration note. If -direct-consumer evidence appears before implementation, compatibility is -reopened rather than silently adding a permanent mirror. - -## Planned Work - -1. Pin `@tanstack/intent` in `packages/web`; add the `tanstack-intent` keyword - and publish `skills/` while excluding non-runtime generation artifacts. -2. Replace the five old skill roots with one `skills/ui-web` intent router and - progressively disclosed references. -3. Evolve the existing generator instead of importing PartnerUp's generator. - Read the component manifest, reviewed seed, TypeScript/Vue source, and - stories; write only the owned generated tree; support a no-write - `--check` mode. -4. Encode useful selection/composition semantics such as form construction, - feedback/confirmation, overlays, JSON editing, media fallbacks, theming, - router/i18n integration, and known failure modes. -5. Add package-local `skill:generate`, `skill:generate:check`, and - `skill:validate` commands. Use the lockfile-pinned Intent binary. -6. Keep custom generation checks authoritative for source/story drift. - `intent stale` remains informational until its source/sync metadata is - deliberately populated and proven; an empty stale report is not a gate. -7. Extend the packed-package contract so a disposable consumer with an - explicit `intent.skills` allowlist can run pinned `intent list` and - `intent load @inkcre/ui-web#ui-web` against the extracted tarball. -8. Verify every referenced file is present in the tarball, no repository - source path leaks, and two generation/check passes are byte-stable. -9. Release and registry-probe the resulting exact package version from the - renamed `InKCre/ui` repository without reopening the completed consumer - identity migration. - -## Exit Proof - -- `intent validate` accepts the canonical `skills/ui-web/SKILL.md` and package - metadata with no packaging warning. -- The custom stale-generation check fails after a seeded component, - story/source fact, or reference is changed without regeneration. -- The packed artifact contains `skills/`, excludes `agent-skills/` and - maintainer-only artifacts, and exposes no new runtime export solely for - Intent. -- In a disposable consumer, explicit allowlisting discovers exactly the - installed `@inkcre/ui-web#ui-web` skill and loads a path inside that package. -- The root check, package build, packed consumer contract, and Histoire build - remain green. -- A reviewed Changeset records the delivery-model change and the exact - published version upgrades the already-migrated consumer through the normal - release path rather than serving as its identity-migration prerequisite. - -## Implemented Result - -- The retired five-folder `agent-skills/` tree is removed. The package now - publishes one canonical `skills/ui-web` skill and advertises - `tanstack-intent`. -- `skill.seed.json` contains reviewed selection, avoidance, composition, - integration, styling, and failure-mode judgment. It is a maintainer input - and is excluded from the tarball. -- The generator reads the public component manifest, reviewed seed, - TypeScript/Vue component facts, and story variants. It validates exact seed - coverage and composition references, then owns exactly 27 deterministic - files: one router, five shared references, and 21 component references. -- Package-local commands generate, check, and validate the skill. The root - generated-output and canonical check paths delegate to those commands. -- Package and migration documentation describe explicit Intent trust - allowlisting, discovery, loading, and the clean cut from `agent-skills/`. -- A minor Changeset records the combined web-DX and skill delivery contract. - -## Local Proof - -- Pinned `@tanstack/intent@0.3.6` validates exactly one skill with no packaging - warning. -- Two generation passes produce the same aggregate SHA-1 - `e440b025445006c64e151b0c0f5adf51de3d24c7`. -- A seed-only stale fixture fails on the component map and affected component - reference. A story-only stale fixture fails on the affected component - reference. -- Both new-name and reproducible old-name tarball probes contain `skills/`, - exclude `agent-skills/` and `skill.seed.json`, validate all Markdown - references, and expose no repository source paths. -- A disposable consumer allowlists the packed package, discovers exactly - `@inkcre/ui-web#ui-web`, and loads a real path inside the extracted tarball. -- The working and frozen-install root checks pass Intent, generation, - package-contract, tests, build, and Histoire. -- Sir authorized the bounded commit and release-PR merge on 2026-07-28. - Commit `f9a65a3` passed CI; release PR #31 merged as `7b0034c`, and the exact - `@inkcre/ui-web@1.3.0` registry artifact passed installed-package discovery - and loading. - -## Primary References - -- [TanStack Intent overview](https://tanstack.com/intent/latest/docs/overview) -- [Intent maintainer quick start](https://tanstack.com/intent/latest/docs/getting-started/quick-start-maintainers) -- [Intent configuration and trust allowlist](https://tanstack.com/intent/latest/docs/concepts/configuration) -- [partner-up-dev/ui web skill](https://github.com/partner-up-dev/ui/tree/main/packages/web/skills/ui-web) diff --git a/tasks/ui-engineering/execution-09.md b/tasks/ui-engineering/execution-09.md deleted file mode 100644 index 7e7452c..0000000 --- a/tasks/ui-engineering/execution-09.md +++ /dev/null @@ -1,144 +0,0 @@ -# Execution 09 — Opt-In Local UI Source Loop - -Execution 09 is implemented and locally verified across this producer and -`../client-web`. Sir authorized the slice on 2026-07-28 after -`@inkcre/ui-web@1.3.0` was published and its installed-package contract was -proven. The bounded producer and consumer changes are committed locally and -remain unpushed. - -## Outcome - -The normal consumer lane remains an exact registry dependency. A developer can -now opt one process into the sibling UI source graph without linking packages, -editing a manifest, changing the workspace, or writing a machine path: - -```bash -pnpm dev:ui --ui-source ../ui/packages/web -pnpm type-check:ui --ui-source ../ui/packages/web -``` - -`../client-web` owns the overlay because its Vite, Vitest, TypeScript, Sass, -Module Federation, SVC, and Portless pipelines compile and serve the external -source. This producer owns package-source compatibility, generated inputs, its -package README, and the Changeset. - -## Consumer Contract - -The tracked consumer helper validates the real package root before returning -any configuration: - -- `package.json` must name `@inkcre/ui-web`; -- all ten public source entries must exist: root, styles, functions, mixins, - ref/sys/comp tokens, utilities, locales, and UnoCSS; -- the global component declaration must exist; -- environment-based configuration must be an absolute path; -- build mode rejects the source overlay. - -The resulting aliases are exact regular expressions, so an undeclared private -subpath cannot silently become public. Source mode extends Vite's filesystem -allowlist with both the detected client workspace and the validated package -root. No absolute path is stored in Vite configuration. - -Vue and other shared peers are deduplicated to the consumer installation. The -UI package is excluded from dependency pre-bundling in source mode. The same -contract is used by the client Vite server, client Vitest project, and Twitter -remote. - -## Sass Ownership - -The previous substring test for `src/components/` could classify a sibling UI -component as client source and inject client-only `@/styles`. Source mode uses -real path containment instead: - -- client components, views, and host extensions receive UI functions/mixins - plus client styles; -- sibling UI components receive only UI functions/mixins; -- unrelated files receive no injected prelude. - -This keeps `@/` consumer-owned while allowing UI component Sass to compile and -hot-reload inside the host graph. - -## Lifecycle And Identity - -The root `dev:ui` launcher: - -1. accepts `--ui-source` or `INKCRE_UI_SOURCE_ROOT`, never both; -2. resolves and validates the source package; -3. prints one `NON-RELEASE` banner with its version and real root; -4. asks SVC to ensure the separate worktree-scoped `web-ui` capability; -5. lets the Vite identity endpoint and SVC probe compare a non-path source - identity hash, preventing a route for a different checkout from being - reused silently. - -`dev:all:ui` carries the same environment into extension development. -`dev:stop` knows the additional Portless route. The established database -capability remains shared with normal client development. - -## Type Graph - -`type-check:ui` writes a temporary tsconfig below ignored -`.runtime/ui-source/`, maps the same exact source entries, maps peer packages -to the consumer installation, includes the UI global component declaration, -runs Vue TSC, and removes the directory. - -The strict cross-repository graph exposed two producer compatibility defects: - -- type-only public exports were emitted as value exports; -- JSON language-service versions disagree on whether a diagnostic message is - always a string or may be markup content. - -The producer now uses type-only exports and normalizes an unknown diagnostic -message into a CodeMirror string. Both the producer's pinned graph and the -consumer source graph pass. - -## Durable Consumer Documentation - -The complete operating guide lives in -`../client-web/apps/client-web/docs/development.md`. It covers prerequisites, -the recommended checkout shape, environment-variable use, remote development, -source type checking, generated tokens, cleanup, Portless behavior, and the -release-fidelity boundary. - -Short routes to that guide are present in the consumer root README, docs -index, app `AGENTS.md`, extension guide, architecture, and filesystem map. This -producer links to it from both the repository README and the published -package-local README, so a consumer inspecting the repository or installed -package can find the canonical instructions. - -## Local Proof - -- `pnpm exec vitest run scripts/ui-source.test.mjs`: 5 contract tests pass. -- `pnpm type-check:ui --ui-source ` passes and removes its - temporary config. -- Source-mode client Vitest passes 3 files / 19 tests. -- Vite-transformed client and Twitter modules import the sibling UI source - rather than `node_modules`. -- WebSocket observation proves both a Vue template edit and an SCSS edit under - the sibling package emit HMR updates for the external source path. -- UI-owned Sass compiles in both the client and Twitter source graphs. -- A source-enabled production build fails with the intentional - development-only error. -- Source SVC startup reports a healthy `web-ui` capability and a distinct - `client-web-ui-` route. -- SHA-256 values for the consumer root manifest, client manifest, Twitter - manifest, and lockfile are byte-identical before startup and after route - shutdown. -- The complete consumer check passes 11 test files / 40 tests and all builds. -- The complete producer check passes 12 test files / 104 tests, both packed - contracts, and 21 stories / 108 variants. - -The initial consumer run warned that the interactive shell used Node `26.3.0` -while the repository declared Node `22.22.3`. Sir chose organization -consistency rather than a Node 26 adoption. The consumer now matches this -producer's pnpm-managed `devEngines.runtime`: `pnpm exec node` and the -repository doctor report exact Node `22.22.3` independently of system Node, -and setup-node reads the same package authority. Frozen installation, the -complete consumer check, source-mode tests, and the source type graph pass -after the migration. - -## Rollback - -The consumer overlay is isolated to the new helper, launch/type-check scripts, -three Vite-family configurations, one SVC target, and documentation. Removing -that slice restores the exact registry-only graph. No dependency, lockfile, -workspace, or persisted local-link state must be repaired. diff --git a/tasks/ui-engineering/packet.md b/tasks/ui-engineering/packet.md deleted file mode 100644 index 3722b6c..0000000 --- a/tasks/ui-engineering/packet.md +++ /dev/null @@ -1,196 +0,0 @@ -# UI Engineering And Design-to-UI Migration - -- **Objective**: establish a reproducible, agent-friendly engineering and development contract for the InKCre UI library, migrate the repository and published package identity from `design` to `ui` without carrying existing package-contract defects into the new identity, and add an explicit consumer-owned local source loop only after the registry, tooling, and installed-package contracts are proven. -- **Guardrails**: preserve current product behavior, Vue component APIs (`Ink*`), CSS classes (`.ink-*`), and token contracts (`--ref-*`, `--sys-*`, `--comp-*`) unless a separate breaking-change decision is explicitly approved; retain accurate domain terms such as “Design System” and “design tokens” instead of mechanically replacing every `design` string; keep `tokens/inkcre.tokens.json` authoritative and generated Sass, UnoCSS, component facts, and Agent Skill references derived; keep reviewed intent/composition guidance explicit rather than inferring product judgment from source syntax; treat the published tarball rather than a source alias as the consumer contract; preserve the frozen-install contract in `../client-web`; keep repository, package, consumer, and remote-governance changes in bounded slices; do not implement, commit, publish, rename a remote repository, or mutate `../client-web` until Sir explicitly starts the relevant slice. -- **Verification**: prove one pinned runtime and one lockfile can reproduce installation; provide one green root check covering package-local formatting/linting, one workspace TypeScript host, Vue type/declaration checking, tests, build, generator consistency, Intent validation/load, and package-contract smoke tests; verify the packed target web package through its JavaScript, types, CSS, Sass, token, locales, utilities, UnoCSS, and installed skill surfaces; run the complete `../client-web` check and affected extension builds against the published package; confirm generated artifacts are deterministic; confirm release and token-update workflows produce the required changeset and package through a deterministic workflow fixture; verify active code, configuration, and consumer documentation no longer depend on the old identity except for an explicitly approved historical or compatibility surface; verify GitHub Packages and remote URLs after the repository rename, with a live Figma dispatch retained as a post-deployment smoke rather than the only gate. -- **Current Truth**: Executions 01–08 are committed and pushed; the consumer registry migration is `b08cade`, and the producer DX/Intent change is `f9a65a3`. Release PR #31 merged as `7b0034c`, and exact `@inkcre/ui-web@1.3.0` is tagged, released, registry-installable, and proven through its installed Intent skill. Execution 09 is implemented and locally verified across this producer and `../client-web`: an explicit source root drives exact Vite/Vitest/TypeScript aliases, a distinct SVC `web-ui` capability, consumer-owned peer resolution, path-owned Sass injection, source HMR, and consumer-visible operating documentation. Both active TypeScript repositories now derive exact Node `22.22.3` from pnpm `devEngines.runtime`; system Node is not project authority. The bounded producer and consumer changes, including the producer patch Changeset, are committed locally and remain unpushed. Live Figma integration remains an external handoff. -- **Next Step**: when explicitly authorized, push both bounded Execution 09 commits and let their normal CI lanes prove the committed state. The local checkout directory rename remains deferred to a session boundary. - -## Classification And Active Posture - -- Constraint: engineering, package, registry, workspace, CI, and cross-repository development boundaries must change while product behavior remains stable. -- Reality: the migration artifact remains frozen at `@inkcre/ui-web@1.2.2`, - while `1.3.0` proves the later Oxc/native-TypeScript and installed Intent - contracts. The optional source loop is additive and never substitutes for - either published artifact. -- Artifact: this packet, the phased migration plan, package-contract fixture, - story-coverage gate, web-DX, Intent and source-loop task files, migration - guide, durable consumer instructions, and execution evidence. -- Active posture: Close. The identity, registry-backed consumer, remote, - producer-DX, installed-skill, and local source-loop contracts are proven; - only bounded Execution 09 commit/CI closure and external handoffs remain. - -## Evidence Snapshot - -- `package.json` now carries the private `@inkcre/ui` workspace identity and exposes the pinned toolchain and canonical root development/check commands. -- `packages/web/package.json` names `@inkcre/ui-web@1.3.0`, publishes to GitHub Packages with restricted access, and exposes only built JavaScript, declarations, CSS, Sass, token, locale, utility, UnoCSS, migration, and `skills/` surfaces. -- `scripts/lib/ui-package.ts` resolves the renamed package once; token, package-metadata, and Intent skill generators derive their outputs from repository and manifest authority instead of caller cwd. -- `.github/workflows/ci.yml` runs the root frozen-install contract, generated-output gates, story coverage, tests, build, packed contract, and Histoire smoke with read-only contents permission. The token-update workflow validates input and creates a deterministic package changeset. -- `.npmrc` contains only the `@inkcre` registry route. Local credentials belong to trusted user configuration, and CI publication credentials exist only on the release step. -- The root does not claim publication metadata. `@inkcre/ui-web` owns its `InKCre/ui` repository link, package directory, restricted access policy, and GitHub Packages registry; GitHub links the private package to `InKCre/ui`. -- The package manifest lists 21 public components; a mechanical gate proves exactly 21 stories, 21 story documents, and 108 variants across six user-facing categories. -- The revised suite passes 104 behavior-focused tests in 12 files. Ten public components without focused tests remain a visible behavior-test backlog. -- Declaration diagnostics fail the build. The bridge-backed full declaration tree normalizes Vue declaration names inside `dist`; the packed contract resolves every relative type import, rejects undeclared external type packages, and contains no workspace/private source-path leaks. -- Package metadata, tokens, and the 27-file Intent skill regenerate repeatably. Two skill passes have aggregate SHA-1 `e440b025445006c64e151b0c0f5adf51de3d24c7`, and seed/story stale fixtures fail as intended. -- Oxlint `1.75.0` and Oxfmt `0.60.0` are pinned at the root and exposed through focused package-local web commands. The root gate checks Vue/TypeScript source, tests, stories, styles, and configuration without Oxlint's incomplete Vue type-aware mode. -- The exact workspace override uses `typescript-native-bridge@6.0.3-bridge.7.tsgo.7.0.2`. Root `tsc`, `vue-tsc`, Vite declaration generation, and subpath declaration generation load one classic host backed by TypeScript 7; removing the override restores stock `typescript@5.9.3`. -- A same-source stock compiler copy and the bridge build pass with the same declaration file set. A separate artifact-free copy passes frozen installation and the complete bridge-backed root check on macOS arm64. -- TanStack Intent `0.3.6` validates one canonical `skills/ui-web` skill. Both packed identities are discoverable and loadable from an explicitly allowlisted disposable consumer; `agent-skills/` and the maintainer seed are excluded. -- `partner-up-dev/ui` uses a package-local `skills/ui-web` surface and pinned Intent validation, but its custom generator and reviewed seed—not Intent—own component facts, composition guidance, caveats, and deterministic output. -- `../client-web/apps/client-web/vitest.config.ts` no longer bypasses the UI exports map; its four old direct filesystem aliases were removed. -- `../client-web` has three exact `@inkcre/ui-web@1.2.2` importers: the web app, extension development utilities, and the Twitter remote. The browser extension does not consume it. -- `../client-web` now also owns an opt-in source overlay with exact public - aliases, a temporary source type graph, a distinct SVC/Portless route, and - durable instructions reachable from its root README, docs index, app agent - guide, extension guide, architecture, and filesystem map. -- The consumer lock resolves the published new-package URL and integrity, including the required text-document peer and optional UnoCSS peer. Node `22.22.3` and pnpm `11.11.0` pass frozen install, the full 35-test/root build gate, type-aware Oxlint, and native TypeScript 7. -- GitHub reports `InKCre/ui` as public with the same repository ID as the old - name. The old web URL redirects, the local remote uses the new SSH URL, - default workflow permissions are `read`, and workflow-token PR approval is - disabled. The existing ruleset still only blocks deletion and non-fast-forward - updates until the canonical PR check is green. -- `@inkcre/ui-web@1.2.2` remains the immutable consumer-migration artifact. - `@inkcre/ui-web@1.3.0` is also published with private visibility, an - `InKCre/ui` source association, the Oxc/native-TypeScript contract, and the - installed `@inkcre/ui-web#ui-web` Intent skill. -- A fresh clone from `InKCre/ui` passes frozen install and the full 104-test, - package, packed-consumer, and Histoire baseline. The renamed repository's - Release workflow also passes and creates release PR #31 without publishing. -- Cloudflare Pages still displays the cached `InKCre/design` source label, but - its functional integration receives renamed-repository PRs. The corrected - `pnpm story` and `packages/web/.histoire/dist` configuration passes a preview - build of all 21 stories / 108 variants. -- Both repositories were clean at the opening audit on 2026-07-27. - -## Approved Target Identity - -| Surface | Legacy | Approved/current | -| ------------------------ | ------------------------------------ | ---------------- | -| GitHub repository | `InKCre/design` | `InKCre/ui` | -| Local checkout directory | `design` | `ui` | -| Private workspace | `inkcre-design` | `@inkcre/ui` | -| Package directory | `packages/web-design` | `packages/web` | -| Published package | `@inkcre/web-design` | `@inkcre/ui-web` | -| Vite library identifier | `InKCreWebDesign` | `InKCreUIWeb` | -| Vue, CSS, and token APIs | `Ink*`, `.ink-*`, `--ref/sys/comp-*` | unchanged | -| Domain vocabulary | Design System, design tokens | unchanged | - -Sir approved this identity on 2026-07-27. The workspace, package directory, -published package metadata, library identifier, and GitHub repository are -renamed. Only the local checkout directory remains `design`, deferred to a -session boundary so no running tool keeps the old absolute path. - -## Working Topology - -```mermaid -flowchart LR - Figma["Figma"] --> Dispatch["repository_dispatch"] - Dispatch --> Tokens["tokens/inkcre.tokens.json"] - Tokens --> Generator["Token generator"] - Source["Vue, Sass, locales, skills"] --> Package["@inkcre/ui-web tarball"] - Generator --> Package - Contract["PR and package contract checks"] --> Package - Package --> Web["client-web"] - Package --> Extensions["ext-dev-utils and Twitter remote"] -``` - -## Supporting Material - -- Implementation and migration roadmap: [`roadmap.md`](roadmap.md) -- Implementation preflight and mental rehearsal: [`preflight.md`](preflight.md) -- Execution 01 implementation evidence: [`execution-01.md`](execution-01.md) -- Execution 02 implementation evidence: [`execution-02.md`](execution-02.md) -- Execution 03 implementation evidence: [`execution-03.md`](execution-03.md) -- Execution 04 implementation evidence: [`execution-04.md`](execution-04.md) -- Execution 05 implementation evidence: [`execution-05.md`](execution-05.md) -- Execution 06 implementation evidence: [`execution-06.md`](execution-06.md) -- Execution 07 implementation evidence: [`execution-07.md`](execution-07.md) -- Execution 08A implementation and local evidence: [`execution-08a.md`](execution-08a.md) -- Execution 08B implementation and local evidence: [`execution-08b.md`](execution-08b.md) -- Execution 09 implementation and cross-repository evidence: [`execution-09.md`](execution-09.md) -- External engineering reference: [`partner-up-dev/ui`](https://github.com/partner-up-dev/ui) - -## Open Decisions - -There are no unresolved naming, tooling, Intent, or source-loop architecture -decisions. The source overlay is consumer-owned, process-scoped, and -development-only; the registry and packed artifact remain authoritative. -Remaining decisions are whether to install the proven workspace check as -required and who owns the supplementary live Figma dispatch. - -The package remains private/restricted, and the old package is frozen for -rollback, retained without a forwarding wrapper, and deprecated only after -coordinated consumer migration. - -Broad producer-side SVC adoption is not part of this task. Execution 09 reuses -the consumer's established SVC lifecycle only for its `web-ui` host capability. - -## Decision Log - -- 2026-07-27: Sir opened a discussion to improve engineering and developer experience and to unify the project identity from `design` to `ui`. -- 2026-07-27: read-only audits of this repository and `../client-web` established the package, generator, CI, registry, and consumer blast radius. -- 2026-07-27: the recommended migration order became stabilize -> publish new identity -> migrate consumers -> rename remote. -- 2026-07-27: Sir explicitly required a task packet and directed the agent to current SVC and `../core-py` usage. -- 2026-07-27: this packet was created as the only authorized mutation; no implementation start has been granted. -- 2026-07-27: Sir challenged the generic web package name, requested a `partner-up-dev/ui` engineering audit, and asked for concrete registry-auth and local-source development designs. -- 2026-07-27: `partner-up-dev/ui` confirmed that web and UniApp packages can share the npm registry; `@inkcre/ui-web` became the recommended candidate while remaining unapproved. -- 2026-07-27: migration sequencing and implementation details moved to `roadmap.md` so this file remains the compact control surface. -- 2026-07-27: Sir approved the npm authority boundary but rejected a custom doctor/auth-probe layer; direct package-manager failures and concise setup documentation are sufficient until repeated evidence justifies more machinery. -- 2026-07-27: the source overlay was constrained to a process-scoped validated path with no tracked machine-specific value, and the real frozen-registry proof moved from producer pre-publish checks to the post-publication consumer migration gate. -- 2026-07-27: final preflight moved the optional source loop after the registry-backed consumer migration so aliases cannot mask publication defects. -- 2026-07-27: isolated QA established the existing 11-test failure baseline, non-fatal declaration errors, deterministic token output, and stale committed Agent Skills. -- 2026-07-27: GitHub preflight established that the current package is private, the candidate repository/package are not currently visible, workflow defaults are overly broad, and the external Figma dispatch sender is not observable from either repository. -- 2026-07-27: token update verification was tightened to require deterministic changeset generation in CI; live dispatch remains a supplementary integration smoke. Broad doctor and compatibility-check abstractions remain rejected on ROI grounds. -- 2026-07-27: Sir explicitly started Execution 01, allowed removal of broken tests during the planned cleanup, and accepted the recommended target identity ending in `@inkcre/ui-web`. -- 2026-07-27: Execution 01 established the pinned toolchain, single lockfile, root check, deterministic generator check, hard declaration diagnostics, behavior-oriented test baseline, frozen PR CI, and refreshed developer documentation. -- 2026-07-27: Sir corrected the pnpm target to the sole linked Homebrew installation, `11.17.0`; the old repository pin was confirmed to be what made pnpm report `10.25.0` inside the project. All workflow and manifest pins were aligned, and pnpm 11's dependency build-script allowlist was made explicit. -- 2026-07-27: the local and disposable-copy root checks passed; remote PR evidence remains pending. -- 2026-07-27: Sir authorized a bounded Execution 01 commit and explicitly started Execution 02. -- 2026-07-27: Execution 01 was committed as `b1e0d6a`. -- 2026-07-27: Execution 02 removed the project-owned credential placeholder, moved publish metadata to the leaf package, scoped CI registry configuration, narrowed release authority, and passed native missing/trusted-auth probes plus the complete root check. -- 2026-07-27: Sir removed the unused Copilot setup workflow and selected pnpm's locked runtime instead of `.node-version` as Node authority. -- 2026-07-27: a disposable `../client-web` copy passed frozen installation from GitHub Packages with trusted temporary auth and lifecycle scripts disabled; all three current UI consumers resolved `@inkcre/web-design@1.2.2`. -- 2026-07-27: Sir authorized the bounded Execution 02 commit after the consumer auth proof and pnpm runtime adjustment. -- 2026-07-27: Execution 02 was committed as `322dcf6`. -- 2026-07-27: Sir authorized implementation through completion of Execution 05. -- 2026-07-27: Execution 03 replaced the invalid package boundary with explicit built exports, one component manifest, deterministic generators, changeset enforcement, and a complete packed consumer contract; both old-name and new-name `1.2.2` tarballs pass. -- 2026-07-27: Execution 04 separated the Histoire catalog from runtime source, established category, preset, theme, and coverage contracts for all 21 public components and 108 variants, and retained behavior tests as a distinct proof layer. -- 2026-07-27: Execution 05 locally renamed the workspace, package path, package, build identity, generated surfaces, and documentation; selected restricted/private publication and the freeze/deprecate/no-wrapper compatibility policy. -- 2026-07-27: final review closed the manually dispatched CI base case, orphan story-document detection, reproducible old-name identity probe, historical preflight labeling, and the newly explicit text-document peer migration note. -- 2026-07-27: GitHub granted the existing CLI credential the additional `write:packages` scope after account-level confirmation; no token was written to repository configuration. -- 2026-07-27: `@inkcre/ui-web@1.2.2` was published privately, installed and imported from a disposable registry consumer, linked to `InKCre/design`, and granted `InKCre/client-web` Actions `Read` access. Execution 05 is complete. -- 2026-07-27: Sir authorized the bounded Executions 03–05 commit; it was created as `5d05693`. -- 2026-07-27: Sir expanded the remaining task to give `packages/web` first-class Oxlint, Oxfmt, and TypeScript 7 development ergonomics and challenged the existing Agent Skill delivery in favor of a PartnerUp/TanStack Intent model. -- 2026-07-27: preflight established that TypeScript 7 itself cannot directly host `vue-tsc`, while an exact `typescript-native-bridge` candidate can run the full web type/declaration build after the package declares its real development peers and non-TypeScript modules. -- 2026-07-27: native type-aware Oxlint was rejected from the required Vue gate because it cannot replace Volar's virtual-file graph; package-local Vue/Vitest linting and `vue-tsc` keep distinct responsibilities. -- 2026-07-27: current Intent validation proved that `agent-skills/` is not discoverable. The plan adopted one clean `skills/ui-web` surface, explicit semantic seed data, custom deterministic generation, pinned Intent validation, and packed installed-package discovery/load proof. -- 2026-07-27: the two producer improvements were initially drafted as Executions 05A and 05B. -- 2026-07-27: Sir corrected the dependency order. The already-published `@inkcre/ui-web@1.2.2` remains the immutable Execution 06 migration target; remote identity closure moves to Execution 07, web DX and Intent delivery become Executions 08A and 08B, and the optional source loop becomes Execution 09. -- 2026-07-27: Sir explicitly started Execution 06. -- 2026-07-27: all three `../client-web` importers moved to exact `@inkcre/ui-web@1.2.2`; old invalid-exports aliases were deleted rather than renamed, and active old-name references reached zero. -- 2026-07-27: trusted temporary authentication downloaded the exact GitHub Packages artifact without persisting a credential. Frozen installation, the complete client check, type-aware Oxlint, and native TypeScript 7 passed on the supported Node runtime. Execution 06 is locally complete. -- 2026-07-28: Sir authorized the bounded Execution 06 commits and explicitly started Execution 07. -- 2026-07-28: the `../client-web` consumer migration was committed as `b08cade`. -- 2026-07-28: `b08cade` was pushed to `InKCre/client-web`; all Client checks passed. -- 2026-07-28: GitHub accepted `InKCre/design -> InKCre/ui` while preserving repository ID, old-URL redirects, Git history, and the private `@inkcre/ui-web` source association. -- 2026-07-28: producer commits through `1d4ab92` were pushed to the renamed repository; the Release workflow and a separate fresh-clone full check passed. -- 2026-07-28: a post-rename rerun of the complete `client-web` workflow passed, proving that repository Actions access to the private package survived the source-repository rename. -- 2026-07-28: default Actions authority was reduced to read-only and workflow-token PR approval was disabled. -- 2026-07-28: release PR #31 exposed stale generated version metadata; the bounded Changesets custom-version fix passed a disposable `1.2.2 -> 1.2.3` rehearsal and awaits explicit commit authorization. -- 2026-07-28: authenticated Cloudflare logs proved that Pages still used the removed `web-design` filter and output path. -- 2026-07-28: Sir confirmed the Cloudflare and bounded commit mutations; Pages now uses `pnpm story` and `packages/web/.histoire/dist`, and retried deployment `2aae170b-edb4-4a14-a86c-86a6bfb51f96` passes. -- 2026-07-28: commit `a423ea0` connected Changesets to deterministic package-metadata regeneration; the refreshed release PR carries matching `1.2.3` manifest and generated version values. -- 2026-07-28: the refreshed PR passed its complete workspace check, then exposed an `ENOENT` in the final changeset gate because release PR deletions were treated as readable current files. A bounded deletion-aware follow-up passes the actual release diff and a negative missing-changeset fixture. -- 2026-07-28: Sir explicitly authorized the bounded changeset-gate follow-up commit. -- 2026-07-28: the changeset-gate follow-up was committed and pushed as `59ec82f`; release PR #31 now reports a clean merge state with both reproducible workspace and Cloudflare checks passing. -- 2026-07-28: Sir explicitly started Executions 08A and 08B. -- 2026-07-28: package-local Oxc workflows, the exact TypeScript native bridge, clean-checkout peer and ambient declarations, editor settings, and a bridge-compatible declaration tree were implemented. Stock and bridge builds expose the same declaration file topology. -- 2026-07-28: the package moved from non-discoverable `agent-skills/` folders to one generated `skills/ui-web` Intent router backed by reviewed seed data, component/source facts, story facts, deterministic checks, and packed installed-package discovery/load proof. -- 2026-07-28: both the working checkout and an artifact-free frozen-install copy pass the complete root check on macOS arm64. Ubuntu glibc CI and exact-version registry proof remain post-commit gates; no commit or publication was made in this implementation turn. -- 2026-07-28: Sir explicitly authorized the combined 08A/08B commit, merge of the refreshed release PR #31, and post-release verification before starting Execution 09. -- 2026-07-28: Execution 08 was committed as `f9a65a3`; Ubuntu CI passed. Release PR #31 merged as `7b0034c`, and `@inkcre/ui-web@1.3.0` was tagged, released, registry-installed, and loaded as `@inkcre/ui-web#ui-web`. -- 2026-07-28: Sir explicitly started Execution 09 and required durable usage documentation visible to consumers. -- 2026-07-28: `../client-web` gained a process-scoped exact source overlay, temporary source type graph, and worktree SVC `web-ui` capability. Client and Twitter transformed modules resolve sibling UI source; Vue and Sass edits emit HMR updates. -- 2026-07-28: source mode rejects builds and leaves the consumer root/client/Twitter manifests plus lockfile byte-identical across startup and shutdown. The complete consumer and producer checks pass, and the canonical consumer guide is linked from both repositories and the published package README. -- 2026-07-28: Sir selected organization runtime consistency over adopting Node 26 Current. `client-web` replaced `.node-version` and `engines` with the same exact pnpm-managed Node `22.22.3` authority as UI; setup-node derives its version from `package.json`. -- 2026-07-28: Sir authorized bounded commits in both repositories. The consumer source-loop and runtime-alignment slice was committed as `9aed28d`; the matching producer source-compatibility, documentation, task-packet, and Changeset slice was committed locally. Neither repository was pushed. diff --git a/tasks/ui-engineering/preflight.md b/tasks/ui-engineering/preflight.md deleted file mode 100644 index 16da1ff..0000000 --- a/tasks/ui-engineering/preflight.md +++ /dev/null @@ -1,107 +0,0 @@ -# UI Engineering Implementation Preflight - -> Historical snapshot: this file records the evidence and risks observed before -> implementation began on 2026-07-27. [`packet.md`](packet.md) and the execution -> records own current truth; later executions intentionally supersede several -> states below. - -This file records the 2026-07-27 implementation rehearsal and volatile evidence behind [`packet.md`](packet.md) and [`roadmap.md`](roadmap.md). It is not implementation authorization. - -## Verdict - -The migration is feasible, but a rename-first execution would carry existing failures into a new repository and package identity. The safe order is: - -```text -reproducible baseline --> auth authority --> packed package contract --> story/behavior baseline --> new identity and exact-version publication --> registry-backed consumer migration --> remote rename and external integration smoke --> web DX and installed Agent Skill delivery --> optional source loop -``` - -The source loop deliberately follows the registry migration and remote identity closure. That makes it an optimization of a known-good package relationship instead of a way to conceal missing exports, declarations, registry access, or an incomplete repository rename. - -## Isolated Baseline - -The QA run used `git archive` at `c97259c6480a7cc152f1d13489b3fd14d7678b7f` in a disposable directory. It did not read untracked task files into the snapshot or write implementation changes into the workspace. - -| Probe | Result | Meaning | -|---|---|---| -| Node `v22.22.3`, project-selected pnpm `10.25.0` | observed during the initial probe | The repository's old `packageManager` field masked the linked Homebrew pnpm `11.17.0`; Execution 01 now pins the confirmed Homebrew version. | -| `pnpm install --frozen-lockfile` | pass | Root lock reproduces the snapshot, but pnpm warns that the committed token placeholder is untrusted and that selected dependency build scripts are ignored. | -| `pnpm build-tokens` twice | pass; byte-stable | Token generation itself is deterministic in the tested root invocation. Style Dictionary reports token-collision warnings that should be classified, not silently normalized. | -| `pnpm build-skills` twice | stable second run; dirty against HEAD | Generated component skill index plus `InkImage` and `InkScrim` references are stale in the repository. | -| web package build | exit 0 | Not a clean signal: Vite warns about the invalid mixed exports map and declaration generation reports TS2742 for `inkPicker` without failing. | -| Vitest | fail; 11/116 tests | Three `InkDialog` assertions target stale VM names; eight `InkImage` failures expose an optional-model behavior defect rather than test-only drift. | -| Histoire build | pass; 21 stories / 108 variants | The catalog is buildable, with the same exports/declaration warnings; this does not replace behavior or package-contract proof. | -| npm/pnpm pack | pass; identical 40-file paths | The allowlist is bounded, but the extracted artifact is not consumable: every Node entry fails with `ERR_INVALID_PACKAGE_CONFIG`, `./utils` has no target, and the `./locales` declaration target is absent. | -| `pnpm changeset status` | inconclusive in archive | The command requires Git ancestry that a `git archive` intentionally omits; this result is an environment limit, not evidence of broken Changesets configuration. | - -## GitHub And Registry Boundary - -All checks were read-only. - -| Surface | Confirmed state | Precondition before mutation | -|---|---|---| -| `InKCre/design` | public, active, default branch `main`; current identity has admin access | none for local baseline | -| `InKCre/ui` | API 404, absent from visible org listing/search | confirm rename acceptance immediately before the remote operation | -| `@inkcre/web-design` | GitHub npm package is private, associated with `InKCre/design`, latest `1.2.2` | reconcile actual private visibility with root `publishConfig.access=public` | -| `@inkcre/ui-web` | absent from visible org packages and registry | confirm canonical name, visibility, repository association, and first-publish permissions | -| `client-web` package access | latest main CI succeeds with `packages: read`; lock resolves `1.2.2` | grant and prove access to the new package; existing success is not proof of a future ACL | -| Actions authority | repository default is `write`; release inherits broad defaults | use explicit job permissions, then lower the default to `read` after CI exists | -| `main` governance | active ruleset blocks deletion/non-fast-forward only; no required status check | add the canonical PR check as a separate governance mutation after it is green | -| Figma dispatch | receiver and 11 historical runs are visible; external sender is not | identify the sender/owner before remote rename; use live dispatch only as post-deploy smoke | -| webhooks | no repository hooks; organization hooks are not visible with current scope | do not infer that no organization-level integration exists | - -## Consumer Blast Radius - -The current `../client-web` snapshot contains: - -- three package manifests with the old dependency; -- 44 files, 62 matching lines, and 66 occurrences of `@inkcre/web-design` including historical task records; -- 40 files, 56 matching lines, and 60 occurrences when `tasks/**` is excluded; -- active package, lock, source, Vite, Vitest, TypeScript, Sass, documentation, extension-utility, and Twitter-remote surfaces. - -Migration proof must therefore check the three manifests and lockfile together with key configuration. A single import search or a successful source alias is insufficient. - -## Mental Rehearsal And Failure Containment - -| Stage | Likely failure if executed naïvely | Planned containment and rollback | -|---|---|---| -| Baseline | Existing tests fail; declaration errors remain warnings; lockfiles diverge; a formatter rewrite obscures behavioral fixes | Freeze current evidence, make type/test failures non-zero, converge the lock first, and stage lint/format adoption without a mass rewrite. | -| Auth | Project config owns a token placeholder; release inherits broad write authority; private-package ACL is assumed | Keep only scope routing in the repository, use trusted user/setup-node auth, bind tokens per step, and prove the new package grant before migration. | -| Package contract | Source build passes while tarball has invalid exports, absent utilities, leaked `.vue` declarations, or bundled peers | Make `npm pack` plus a disposable consumer fixture the producer gate; never substitute a sibling alias. | -| Token workflow | Figma PR updates generated files but omits a changeset, or repeated runs collide on one filename | Generate a workflow-identity-scoped changeset from validated input and test the transformation with a deterministic fixture. | -| Identity/publish | New name is unavailable, first publish gets wrong visibility, or old consumers lose rollback | Check identifiers just-in-time, publish as a new immutable package, install the exact version, retain the old final artifact, and document migration before consumers move. | -| Consumer | Only one manifest changes, lockfile silently repairs, or legacy Vitest aliases mask the new package | Update all three manifests and the lock in one bounded slice, delete workarounds, run a fresh frozen registry install, and rollback by reverting that consumer slice. | -| Source loop | Absolute sibling paths leak into Git; Vite blocks external files; Vue is duplicated; source success masks registry defects | Introduce it only after registry migration, keep the path process-scoped, validate exact entries, preserve Vite's workspace root, dedupe peers, and leave manifests/locks byte-identical. | -| Remote rename | Figma sender still targets `design`; package association or docs point to the old remote; the active tool loses its cwd | Rename immediately after consumer migration, inventory the external owner first, rely on deterministic workflow proof, run live dispatch afterward, and defer local directory rename to a session boundary. | - -## Deliberately Rejected Complexity - -- No custom auth doctor until repeated failures demonstrate positive ROI. -- No `link:`, `file:`, nested workspace, local registry, or committed machine path for source development. -- No compatibility framework merely to duplicate static old-name searches, packed-fixture checks, and frozen consumer installation. -- No forwarding old package by default when all known consumers can migrate and immutable old versions already provide rollback. -- No live external dispatch as the sole workflow test. -- No repository-wide formatter rewrite hidden inside the baseline repair. -- No SVC adoption inside the UI migration critical path; open it as a separate task if desired. - -## Decision And Authorization Gates - -Execution 01 was explicitly started and completed locally on 2026-07-27. Its current evidence is recorded in [`execution-01.md`](execution-01.md). - -Before Execution 05: - -1. confirm private versus public GitHub Package visibility; -2. accept the recommended freeze/deprecate/no-wrapper old-package policy or request a compatibility package. - -Before Execution 07: - -1. confirm GitHub accepts the `InKCre/ui` rename; -2. identify the external Figma dispatch owner and update mechanism; -3. explicitly authorize remote, package-association, governance, and local-remote mutations. diff --git a/tasks/ui-engineering/roadmap.md b/tasks/ui-engineering/roadmap.md deleted file mode 100644 index 00c5a16..0000000 --- a/tasks/ui-engineering/roadmap.md +++ /dev/null @@ -1,433 +0,0 @@ -# UI Engineering And Migration Roadmap - -This file owns the task-local implementation sequence, phase dependencies, exit proofs, and rollback boundaries. The compact current state and human steering point remain in [`packet.md`](packet.md). - -## Target Outcome - -```text -Repository: InKCre/ui -Private workspace: @inkcre/ui -Web package path: packages/web -Published package: @inkcre/ui-web -Consumer: ../client-web -``` - -Sir approved these target names on 2026-07-27. The family is entity-first (`ui-web`) because the repository owns UI as the product surface and web is one renderer. A registry-specific generic `@inkcre/ui` would imply that npm can contain only one UI renderer; `partner-up-dev/ui` demonstrates that web and UniApp renderers can occupy the same registry. - -## Delivery Dependency Graph - -```mermaid -flowchart LR - Baseline["01 engineering baseline"] --> Auth["02 auth boundary"] - Auth --> Contract["03 package contract"] - Contract --> Story["04 story and behavior baseline"] - Decisions["Close visibility and compatibility"] --> Identity["05 local identity and publish"] - Story --> Identity - Identity --> Consumer["06 registry-backed client migration"] - Consumer --> Remote["07 remote rename and identity closure"] - Remote --> DX["08A web DX and native TypeScript"] - DX --> Skills["08B Intent-based skill delivery"] - Skills --> Source["09 optional local source loop"] - RemoteInput["Confirm remote name and dispatch owner"] --> Remote -``` - -Each node must be independently releasable or reversible. A later node may not compensate for a failed earlier gate. - -## PartnerUp Reference Audit - -Reference: [`partner-up-dev/ui`](https://github.com/partner-up-dev/ui), default branch `main`, audited at commit `25e2f72570580b97f75d8a241b9149c0b4f4699c`. - -### Adopt or adapt - -- Root private package `@partner-up-dev/ui`, platform directories `packages/web` and `packages/uniapp`, and published packages `@partner-up-dev/ui-web` and `@partner-up-dev/ui-uniapp`. -- One root pnpm lockfile, explicit Node/pnpm pins, and frozen CI installation. -- Package-local `verify` composition and explicit `files`/`exports` allowlists. -- Generated component registry, version, global component types, and `--check` stale-generation gates. -- Package-local `skills/ui-web`, reviewed semantic seed data, a custom - deterministic generator, and pinned TanStack Intent validation. -- `npm pack` -> extracted fixture -> consumer `vue-tsc` probe for the actual published type surface. -- Histoire story taxonomy, responsive/background presets, theme bridge, and mechanical story coverage. -- Changesets release PR, package-local `MIGRATION.md`, and repository metadata with package directory. - -### Do not copy without correction - -- The repository has only a publish workflow; no independent pull-request quality workflow exists, and release runs package builds rather than the full web `verify` gate. -- Its committed `.npmrc` still contains `${NODE_AUTH_TOKEN}` in repository-controlled auth configuration, which current pnpm treats as untrusted. -- `shamefully-hoist=true` and `strict-peer-dependencies=false` can hide dependency-boundary defects. -- Histoire coverage proves catalog presence, not behavior, accessibility, interaction, or screenshot stability; the reference has no Vitest, Playwright, or visual-regression suite. -- Mutable action tags and beta Histoire versions require an explicit InKCre policy rather than blind copying. -- Source-oriented UniApp exports are platform-specific and are not a model for the compiled web artifact. -- PartnerUp's custom generator, rather than Intent itself, owns its component - extraction and intent/composition content. Its older Intent integration is a - reference architecture, not a dependency version or workflow to copy - verbatim. - -## Execution 01 — Reproducible Engineering Baseline - -**Status:** implemented and locally verified on 2026-07-27. Remote PR execution is pending a later commit/push authorization. See [`execution-01.md`](execution-01.md). - -### State diff - -```text -Two lockfiles, incomplete runtime contract, and leaf-only commands --> -One pinned toolchain, one lockfile, and one canonical root developer contract -``` - -### Planned work - -1. Choose and pin one Node and pnpm pair from the package's actual compatibility evidence. Cross-repository pnpm-major alignment is not required because the repositories do not share a workspace or lockfile. -2. Remove the package-local lockfile and regenerate the root lock through the pinned package manager. -3. Establish root `dev`, `build`, `type-check`, `test`, `story`, and `check` entrypoints whose local and CI implementations are identical. Make declaration/type errors fail instead of surviving as build warnings. -4. Inventory existing formatting and lint rules before making them gates. Add stable `format` and `lint` entrypoints without bundling a repository-wide mechanical rewrite into the first corrective change. -5. Fix the known failing test baseline, separating three stale `InkDialog` assertions from the eight failures that expose the `InkImage` optional-model defect. -6. Fix stale root/package documentation and broken development entrypoints. -7. Add a pull-request workflow using frozen installation and explicit read-only permissions. -8. After the check is green, separately reduce the repository's default workflow permission from `write` to `read` and add the canonical check as a required `main` rule. This is a GitHub governance mutation and requires an explicit execution handshake. - -### Exit proof - -- A clean checkout requires no package-directory install. -- Runtime, lock, and tooling failures are exposed directly by the canonical install and check commands without adding a parallel diagnostic layer. -- Type/declaration failures and unit-test failures produce non-zero exits. -- The canonical root `check` is green locally and in a pull request. - -### Actual proof - -- A disposable copy installed from the root with `pnpm install --frozen-lockfile` and passed the same `pnpm check` used by CI. -- The final suite passes 11 files / 103 tests; Histoire builds 21 stories / 108 variants. -- A second generator run changes no generated token or Agent Skill output. -- Rolled declarations contain no `.pnpm`, relative `node_modules`, or `@vue/shared` imports. -- `pnpm changeset status` identifies `@inkcre/web-design` for a patch bump. -- Pull-request workflow syntax and commands are present locally; a real GitHub run remains the final external proof after the changes are committed and pushed. - -## Execution 02 — Registry Authentication Boundary - -**Status:** implemented and locally verified on 2026-07-27. A disposable `../client-web` copy passed frozen installation of the current private package through trusted temporary auth. Remote PR and release execution, future-package visibility, new-package consumer Actions access, and Dependabot proof remain tied to their real pushed/published artifacts. See [`execution-02.md`](execution-02.md). - -### Authority model - -```mermaid -flowchart LR - RepoNpmrc["Committed .npmrc: @inkcre route only"] --> Registry["npm.pkg.github.com"] - LocalAuth["Trusted user config"] --> Registry - SetupNode["setup-node ephemeral user config"] --> Registry - LocalAuth -. "read:packages" .-> Install["Local frozen install"] - SetupNode -. "step-scoped GITHUB_TOKEN" .-> CI["CI install or publish"] -``` - -Repository configuration owns registry routing. A developer's trusted user configuration or a CI-created user configuration owns credentials. The repository never owns a token placeholder. - -### Planned local boundary - -1. Keep only `@inkcre:registry=https://npm.pkg.github.com/` in the committed root `.npmrc`. -2. Remove every project-level `_auth`, `_authToken`, password, token helper, and environment-expanded credential. -3. Store the developer read token in trusted user-level pnpm/npm configuration or inject it into the current process from a credential manager. Never write or print the value from repository tooling. -4. Document the one-time trusted user-auth setup and the native pnpm/GitHub 401/403 remediation path. Do not add a repository-owned credential probe or diagnostic abstraction unless repeated failures later prove that its maintenance cost has positive ROI. - -### Planned CI boundary - -1. Use `actions/setup-node` with the GitHub Packages registry and `@inkcre` scope so CI receives an ephemeral trusted user config. -2. Bind `NODE_AUTH_TOKEN` only to the exact install or publish step. -3. Consumer jobs use `contents: read` and `packages: read`. -4. Release jobs use explicit `contents: write`, `pull-requests: write`, and `packages: write`; remove shell `npm config set` calls and never change the global default registry. -5. Put `publishConfig.registry` and `repository` metadata on the publishable web package, not only on the private workspace root. -6. Link the GitHub Package to the UI repository and grant `client-web` read access. Prefer GitHub's repository package-access grant for Actions and Dependabot; use an encrypted Dependabot read-only PAT only if that automatic path is proven insufficient. -7. Do not expose a package-read token to arbitrary dependency lifecycle scripts without an explicit risk decision. If installation scripts are disabled while the token is present, run required trusted preparation scripts explicitly after the token leaves the environment. - -### Forbidden states - -- `${NODE_AUTH_TOKEN}` or any credential in the committed `.npmrc`. -- A shell command containing `${{ secrets.* }}` as an npm config value. -- A job-wide or workflow-wide package token. -- `registry=https://npm.pkg.github.com` as the default for unscoped dependencies. -- Auth config, response bodies, or token-derived details in install or CI logs. - -### Exit proof - -- Trusted user auth resolves the current private package, local frozen installation succeeds without a project credential, and missing or invalid auth remains a direct package-manager error documented in the setup guide. -- A consumer pull-request install that resolves a private `@inkcre` package succeeds with `packages: read`; producer-only jobs retain `contents: read` until they have such a dependency. -- Changesets publishes with the repository `GITHUB_TOKEN` and no long-lived publish PAT. -- Dependabot can resolve the package through an explicitly proven access path. -- Repository search finds no persisted package credential. -- Package visibility matches the approved policy; repository metadata no longer claims `access: public` while the actual package is private. - -## Execution 03 — Package And Generator Contract - -**Status:** implemented and locally verified on 2026-07-27. See [`execution-03.md`](execution-03.md). - -### Planned work - -1. Correct the invalid `exports` map, including the `./uno` subpath. -2. Make every claimed export exist in the packed artifact; remove or build `./utils`, locales, styles, Sass partials, tokens, and declarations coherently. -3. Externalize peer dependencies consistently and record intentional bundling. -4. Make token and Agent Skill generators independent of process cwd. -5. Generate the component registry, global types, version, and Agent Skills from one public component authority; add stale-output checks. -6. Add a packed consumer fixture covering: - - Node import and resolution; - - Vue/TypeScript declarations and global components; - - CSS presence and side effects; - - Sass styles, functions, mixins, and tokens; - - locales, utilities, and UnoCSS; - - rejection of unintended raw component subpaths. -7. Require a changeset for package behavior, contents, public documentation, or generated token changes. -8. Make the token-update workflow create a collision-resistant changeset for the package being released, derived from validated dispatch input and workflow identity. A deterministic workflow fixture must prove payload -> token source -> generated artifacts -> changeset without requiring a live Figma request. - -### Exit proof - -- The packed old-name artifact passes the complete consumer fixture without direct `node_modules` aliases. -- Generators produce a clean Git diff on a second run. -- Token-update pull requests cannot be created without a valid package changeset; the deterministic fixture is the primary gate and a live dispatch is only an integration smoke. -- `../client-web` can remove its invalid-exports workaround after consuming the fixed artifact. - -## Execution 04 — Story And Component Verification Baseline - -**Status:** implemented and locally verified on 2026-07-27. See [`execution-04.md`](execution-04.md). - -### Planned work - -1. Keep Histoire as the primary interactive component catalog. -2. Separate stories from runtime component directories and organize them by user-facing category. -3. Generate or validate a public-component-to-story coverage map; require complete coverage or an explicit reviewed backlog. -4. Add responsive, background, and light/dark theme presets and a runtime theme smoke check. -5. Retain focused Vitest behavior tests for component contracts; prioritize the ten currently untested public components. -6. Add automated Histoire build smoke in PR CI. -7. Evaluate Playwright component/story smoke and screenshot regression only after deterministic fonts, animations, viewports, and browser ownership are defined. - -### Exit proof - -- Every public component has a discoverable story or an explicit exception. -- Theme and responsive catalog states build reproducibly. -- Behavioral tests and story catalog checks have distinct, documented responsibilities. - -## Execution 05 — Local Identity Migration And New Package Publication - -**Status:** completed and verified on 2026-07-27. `@inkcre/ui-web@1.2.2` is published privately, installable by exact version, linked to `InKCre/design`, and readable by `InKCre/client-web` Actions. See [`execution-05.md`](execution-05.md). - -### Planned work - -1. Rename the private root to `@inkcre/ui`. -2. Move `packages/web-design` to `packages/web`. -3. Rename the web package to the approved target, currently recommended as `@inkcre/ui-web`. -4. Update build, generator, Histoire, documentation, migration guide, changeset, package metadata, and generated identities in one local slice. -5. Preserve `Ink*`, `.ink-*`, token APIs, and valid design-system vocabulary. -6. Carry version lineage forward unless the registry/release proof supports a different explicit policy. -7. Publish and install the new package before touching consumer manifests. -8. Publish a migration guide and record the compatibility decision. The recommended low-complexity policy is to leave the final old-package version immutable and installable, migrate known consumers, then deprecate rather than unpublish it; do not build a forwarding wrapper without evidence of unknown active consumers. -9. Apply the approved package visibility, repository association, and `client-web` package-read grant before starting consumer mutation. - -### Exit proof - -- The repaired artifact can be reproducibly repacked and probed under both old and new identities; this identity proof is distinct from the immutable historical registry tarball. -- The new registry package is installable by exact version. -- The old exact version remains recoverable under the documented compatibility policy, and the migration guide names the bounded consumer commit that can be reverted. - -## Execution 06 — Consumer Migration - -**Status:** completed on 2026-07-28. The migration is committed and pushed in -`../client-web` as `b08cade`; complete client checks passed before and after the -producer repository rename. See -[`execution-06.md`](execution-06.md). - -The already-published `@inkcre/ui-web@1.2.2` registry path becomes green before -the producer toolchain, skill delivery, or source loop changes. - -### Planned work - -1. Update all three consumer manifests to exact `@inkcre/ui-web@1.2.2`, plus - the lockfile, runtime/type/style imports, Sass injection, Vite/Vitest - configuration, tests, and active documentation. -2. Remove the old invalid-exports aliases rather than renaming them. -3. Run the web app, Twitter remote, extension utilities, and repository-wide client gates. -4. Record the pre-migration manifest and lock revision. Rollback is a bounded revert to that exact old-package state; dual dependencies or a forwarding package are not required. - -### Exit proof - -- A fresh `../client-web` CI job performs `pnpm install --frozen-lockfile` and the complete check against the new package. This is a consumer-migration gate, not a producer pre-publish or every-release gate: it proves the committed consumer lock resolves the actual registry artifact, access policy, integrity, peers, exports, and declarations without silently repairing the lock. -- All three manifests, the lockfile, and key Vite, Vitest, TypeScript, and Sass configuration are verified together. -- No active consumer reference to the old package remains outside an approved historical record or migration guide. - -## Execution 07 — Remote Rename And Identity Closure - -**Status:** remote rename applied and core identity proofs passed on -2026-07-28; integration and governance closure is in progress. See -[`execution-07.md`](execution-07.md). - -The repository rename now immediately follows consumer migration. At that -point code, registry package, and all known consumers use the UI identity; the -remote is the last migration-owned identity boundary. Later engineering -enhancements should land as ordinary `InKCre/ui` work rather than prolonging -the transition from `design`. - -### Planned work - -1. Confirm `InKCre/ui` repository-name availability immediately before mutation; current 404/search absence is encouraging but does not prove that GitHub will accept the rename. -2. Rename the GitHub repository only after the Execution 06 registry-backed consumer gates pass. -3. Update local remotes, package repository metadata, Figma dispatch, webhooks, workflows, badges, docs, and clone instructions. -4. Verify release PR, package publication, GitHub Release, and a fresh clone through deterministic checks. Then run one live Figma dispatch as a supplementary post-rename smoke after the external sender/owner is identified. -5. Deprecate or freeze the old package according to the approved policy; do not unpublish recoverable artifacts by default. -6. Rename the local checkout directory only at a user/session boundary so an active development tool does not lose its workspace root. - -### Exit proof - -- Fresh clone -> frozen install -> root check -> package publish -> consumer install works through the UI identity. -- The deterministic token-workflow fixture remains green; a live Figma dispatch reaches the renamed repository and produces a changeset-bearing pull request as supplementary integration evidence. -- Rollback instructions and retained artifacts are tested and recorded. - -## Execution 08A — Web DX And Native TypeScript - -**Status:** completed and released on 2026-07-28. Ubuntu glibc CI passed and -the contract is published in `@inkcre/ui-web@1.3.0`. See -[`execution-08a.md`](execution-08a.md). - -This slice gives `packages/web` direct lint/format/fix ergonomics, closes its -clean-checkout source-development dependency gaps, and adopts the native -TypeScript 7 checker through an exact-pinned classic-API bridge after one-time -stock/compiler parity proof. - -### Key boundaries - -- The leaf package owns web editing commands and focused Oxc configuration; - the root keeps CI orchestration. -- TypeScript resolution remains workspace-wide so `tsc`, `vue-tsc`, Volar, - `tsx`, Vite declaration tooling, and subpath declaration emit do not load - incompatible compiler hosts. -- Vue-aware Oxlint and Oxfmt are required; Oxlint's type-aware/type-check mode - is not. `vue-tsc` remains authoritative for Vue virtual files. -- The bridge becomes canonical only after the complete root and packed-package - contracts pass; no permanent TS5/TS7 dual lane is retained. - -### Exit proof - -- A disposable frozen installation can develop, type-check, test, format, - lint, and build `packages/web` without stale workspace dependencies. -- Component source, Vue SFCs, stories, tests, and styles are covered by the - package-local Oxc commands. -- The exact native bridge is active throughout type/declaration generation and - passes macOS arm64 local plus Ubuntu glibc CI proof. -- The cutover is a bounded dependency/config/lockfile revert. - -## Execution 08B — Intent-Based Agent Skill Delivery - -**Status:** completed and released on 2026-07-28. Exact -`@inkcre/ui-web@1.3.0` publication and installed-skill loading passed. See -[`execution-08b.md`](execution-08b.md). - -This slice replaces the non-discoverable `agent-skills/` documentation -categories with one installed-package `skills/ui-web` intent router, curated -composition knowledge, progressively disclosed generated references, and a -real TanStack Intent package contract. - -### Key boundaries - -- Intent owns path/schema validation, discovery, trust allowlisting, and - installed-version loading. -- The InKCre generator owns component authority, Vue/TypeScript/story facts, - reviewed intent/composition seed data, reference generation, and - deterministic stale checks. -- `agent-skills/` is removed rather than mirrored because repository/consumer - searches find no direct use of that path and the old path is not an Intent - discovery contract. -- `intent stale` is informational until meaningful source/sync metadata is - proven; an empty result is not accepted as freshness evidence. - -### Exit proof - -- Pinned Intent validates the package without packaging warnings. -- The packed artifact is discoverable and loadable as - `@inkcre/ui-web#ui-web` from a disposable explicitly allowlisted consumer. -- Custom generation checks catch component, story/source, seed, and reference - drift. -- A reviewed Changeset and exact registry publication upgrade the - already-migrated consumer through the normal release path. - -## Execution 09 — Opt-In Local UI Source Loop - -**Status:** implemented and locally verified across the producer and -`../client-web` on 2026-07-28. The bounded changes are committed locally and -remain unpushed. See [`execution-09.md`](execution-09.md). - -This is a fast development lane, never the release contract. - -### Ownership and invocation - -- `../client-web` owns the source-consumption overlay because the host Vite/Vitest/TypeScript pipeline determines how external source is compiled. -- An explicit `INKCRE_UI_SOURCE_ROOT` or `--ui-source ` opt-in selects the sibling `ui/packages/web` source. The normal command has no overlay. -- No machine-specific path is stored in tracked configuration. A tracked helper reads the process-scoped opt-in, resolves its real path at startup, and validates the package name and expected entry files before returning configuration. With no opt-in, it returns no aliases or filesystem allowance, so other contributors retain the normal registry-backed development path. -- No `link:`, `file:`, workspace member, manifest, lockfile, or persistent `node_modules` mutation is allowed. - -### Vite source graph - -1. Map exact public specifiers, never a broad package-directory alias: - - package root -> `src/index.ts`; - - styles -> the source Sass entry; - - functions, mixins, and ref/sys/comp tokens -> their exact partials; - - utilities, locales, and UnoCSS -> their exact source entries. -2. Only in source mode, extend `server.fs.allow` with both `searchForWorkspaceRoot(process.cwd())` and the validated `packages/web` root. Vite disables automatic workspace-root detection when an explicit allowlist is supplied, so retaining the discovered root is required. The path comes from the current command, never a committed absolute path. -3. Set `resolve.dedupe` for Vue and shared peers so external UI source resolves the consumer's runtime instance. -4. Exclude the source package from dependency pre-bundling when needed. -5. Restrict client Sass `additionalData` to files actually inside the client application root; a substring such as `src/components/` must not inject client styles into sibling UI source. -6. Reuse the same source mapping in the Twitter remote when that remote is part of the active integration loop. - -### Vitest and TypeScript source graph - -- Vitest reuses the same exact aliases and Vue transform; it does not mix source aliases with the current direct-dist workaround. -- A generated temporary tsconfig overlay maps root, utilities, locales, and UnoCSS entries and includes the UI global-component declaration. It is ignored and removed with the session. -- The UI package's own type-check/watch remains authoritative for UI source. Registry declarations remain authoritative in the normal consumer lane. - -### Lifecycle - -```mermaid -sequenceDiagram - participant Dev as Developer - participant Client as client-web Vite - participant UI as ui/packages/web source - participant Browser as Browser - - Dev->>Client: start dev:ui with validated source root - Client->>UI: build exact source aliases into module graph - Dev->>UI: edit Vue, TS, or Sass - UI-->>Client: watched external module changes - Client-->>Browser: Vue/Sass HMR - Dev->>Client: stop through normal dev cleanup -``` - -Generated tokens require the UI token generator before Sass HMR; editing token JSON alone does not bypass generation. - -### Release-fidelity lane - -With the source overlay disabled: - -1. Build the UI package. -2. Pack it into an explicit temporary directory. -3. Install/extract it only inside a disposable consumer fixture and run Node, TypeScript, Sass, CSS, locale, utility, and UnoCSS probes. -4. Stop at the disposable package consumer for producer-side pre-publish - verification. Registry upgrade proof belongs to the normal post-08B release - path, not this source overlay. - -If the source lane passes while the packed lane fails, release is blocked. This prevents aliases from hiding missing files, invalid exports, or declaration leaks. - -### Exit proof - -- Editing an external UI Vue/Sass file updates the running client through HMR. -- Starting and stopping the source loop leaves both manifests and lockfiles byte-identical. -- Source-mode startup prints one clear non-release banner containing the resolved package root but no credential or unrelated machine state. -- The default check and CI never enable the overlay. - -## Review And Rollback Gates - -- Naming: repository, private workspace, directory, package, generated skill, dev route, and domain vocabulary are classified separately. -- Package: every export points to a packed file and every declaration resolves without repository source. -- Auth: routing and credential authority remain separate; logs contain no secrets. -- Story: catalog coverage does not substitute for behavior or visual assertions. -- Source loop: no local alias result is accepted as release proof. -- Native tooling: one workspace TypeScript host feeds every compiler consumer; - Oxlint does not impersonate the Vue declaration checker. -- Agent guidance: installed tarball discovery/load and custom semantic - generation are separate required proofs. -- Cross-repository: the proven `1.2.2` producer publication precedes consumer - mutation; later DX and Skill releases do not redefine migration success. -- Compatibility: use a documented exact-version and commit rollback; do not add a verification framework whose only purpose is to restate static searches and frozen-install results. -- Remote: GitHub rename follows the registry-backed consumer migration - immediately and is never relied on as the only rollback mechanism. -- Rollback: published versions remain immutable; recover by dependency rollback, forward fix, or explicit deprecation rather than destructive unpublish.