@mriekki/project-forge 0.0.0-stage → 1.0.0

package/assets/generated/core/core/skills/project-forge-update/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: project-forge-update
+description: Guided whole-profile update for package-managed Project Forge consumers using the exact published @mriekki/project-forge artifact while preserving Core, Deployment, umbrella, and generated-consumer provenance integrity.
+argument-hint: "[optional exact package version]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Project Forge Update
+
+`/project-forge-update` is the normal update workflow for consumers that contain `PROJECT_FORGE_BASELINE.json` and were installed/generated from the public Project Forge package.
+
+The governing rule is:
+
+```text
+package-managed consumer
+→ update the whole Project Forge profile through the published package
+→ keep PROJECT_FORGE_BASELINE.json + component baselines coherent
+→ when the consumer is Bootstrap-generated, keep approved generation metadata and generated package-verification surfaces coherent too
+```
+
+Do not replace this with direct Core-only or Deployment-Kit-only synchronization when `PROJECT_FORGE_BASELINE.json` is present.
+
+Invocation starts read-only. One explicit update choice may authorize safe branch setup plus the exact package apply, generated-consumer companion metadata updates when applicable, and verification. `/deliver`, merge, release publication, and production deployment remain separate.
+
+## 1. Establish package-managed provenance
+
+From the consumer root read:
+
+- `PROJECT_FORGE_BASELINE.json`;
+- `CORE_BASELINE.json` when present;
+- `DEPLOYMENT_BASELINE.json` when present;
+- `POC_BOOTSTRAP.json` when present;
+- current Git status, branch, remotes, and default branch when observable.
+
+Require `PROJECT_FORGE_BASELINE.json` to identify:
+
+- package name;
+- installed package version;
+- profile;
+- recorded Core component commit/version/distribution;
+- recorded Deployment component commit/distribution when that component is present.
+
+If `PROJECT_FORGE_BASELINE.json` is absent, report `NOT A PACKAGE-MANAGED PROJECT FORGE CONSUMER` and stop. A Core-only consumer may use `/core-sync`; another component-only consumer must use that component's canonical component update path.
+
+Do not synthesize or repair missing umbrella provenance by hand.
+
+### Bootstrap-generated consumers
+
+If `POC_BOOTSTRAP.json` exists, treat it as approved generated-consumer provenance, not unrelated product data.
+
+Before planning an update, require `generation.projectForge.package`, `generation.projectForge.version`, and `generation.projectForge.profile` to agree exactly with the installed `PROJECT_FORGE_BASELINE.json`. Require `generation.projectForge.integrity` to be a non-empty exact registry integrity value for that installed package/version. Verify that integrity read-only from the registry when registry access is available.
+
+If those values disagree before the update, report `GENERATED PROJECT FORGE METADATA DRIFT` and stop. Do not use `/project-forge-update` to silently reconcile an already-incoherent generated consumer.
+
+Also inspect generated package-verification surfaces such as `.github/workflows/ci.yml` when present. If they duplicate the approved package version/integrity literally, record that current shape as companion generated metadata that must remain coherent with `POC_BOOTSTRAP.json` during the update. Do not rewrite locally customized or unrecognized generated surfaces by guesswork.
+
+## 2. Verify the installed package baseline first
+
+Before planning an update, verify that the current managed state still matches the exact installed package version recorded in `PROJECT_FORGE_BASELINE.json`.
+
+For the standard package this is equivalent to:
+
+```text
+npx --yes @mriekki/project-forge@<installed-version> check
+```
+
+Use the package identity recorded by the baseline rather than silently substituting another package.
+
+If the exact installed package cannot be obtained, or `check` reports stale/drifted Core, Deployment, or umbrella metadata, stop. Do not use an update as a way to overwrite unexplained managed drift.
+
+Also inspect Git state. Preserve unrelated consumer work; never auto-stash, reset, clean, rebase, force-update, or discard it.
+
+## 3. Resolve one exact target package
+
+If the human supplied an exact version, use that exact version after confirming it exists.
+
+Otherwise resolve the registry's current published version first, then pin that exact value for the remainder of the operation. For the standard package, typical read-only evidence is:
+
+```text
+npm view @mriekki/project-forge@latest version --json
+npm view @mriekki/project-forge@<resolved-version> dist.integrity --json
+```
+
+Capture the target package's full exact `dist.integrity` together with the resolved version. For a Bootstrap-generated consumer, that exact integrity is part of the reviewed companion metadata update.
+
+Do not use a moving `@latest` reference for the modifying apply after preview. Use the same exact package version for preview, apply, and final check.
+
+If the resolved version equals the installed version and the exact-version check passes, report `PROJECT FORGE ALREADY CURRENT` and stop without creating a branch or commit.
+
+If the resolved target is semantically older than the installed package, report `PROJECT FORGE DOWNGRADE REQUESTED` and stop. Normal `/project-forge-update` does not authorize a downgrade or rollback; that requires a separate explicit recovery/rollback decision with repository-specific evidence.
+
+## 4. Preview the whole-profile update
+
+Run the target package's update command without `--apply` and inspect the complete plan. For the standard package:
+
+```text
+npx --yes @mriekki/project-forge@<target-version> update
+```
+
+Do not approve the package's interactive apply prompt during preview. When needed, invoke preview in the environment's non-interactive/read-only form so the printed plan is observed without applying it.
+
+The preview must cover every component in the installed profile together. A managed conflict/drift in any component blocks the whole update.
+
+Stop on unsafe states such as:
+
+- `LOCAL_DRIFT`;
+- `CONFLICT`;
+- `LOCAL_MISSING`;
+- `UNTRACKED_CONFLICT`;
+- path collisions/conflicts;
+- Core `RETIRED_DRIFT` when the retired file no longer matches its recorded managed hash.
+
+A package-managed retired path that is unchanged from its recorded baseline may be classified as `REMOVE` and deleted safely; an already-missing retired path may be classified as `RETIRED_MISSING`. These states do not require a separate ownership decision because the baseline proves there is no consumer edit to preserve.
+
+A modified retired Core path is different: never auto-add `--accept-retired core:<path>` merely to make the update pass. Explain that the file differs from its recorded Core-managed hash and require a separate explicit ownership-transfer decision before re-previewing it. When that exact transfer is accepted, the package updater preserves the file as consumer-owned content and drops it from the new Core baseline.
+
+For a Bootstrap-generated consumer, also preview the companion generated-consumer changes:
+
+- `POC_BOOTSTRAP.json` keeps the same package/profile but changes `generation.projectForge.version` and `generation.projectForge.integrity` to the exact reviewed target;
+- generated package-verification surfaces should consume `POC_BOOTSTRAP.json` dynamically when the accepted Bootstrap contract supports that form;
+- a recognized older Bootstrap-generated verification block may be migrated only when its embedded old package/version/integrity exactly match the currently approved manifest metadata;
+- an unrecognized or locally modified generated verification surface is a stop condition, not permission to reconstruct Bootstrap output by hand.
+
+## 5. Present one bounded update choice
+
+When the exact target package plan and any generated-consumer companion plan are safe, present:
+
+```text
+PROJECT FORGE UPDATE READY
+
+Installed: <package>@<installed-version>
+Target: <package>@<target-version>
+Target integrity: <exact dist.integrity>
+Profile: <profile>
+Core: <old> → <new>
+Deployment: <old> → <new> / unchanged
+Generated consumer metadata: <not present / coherent update planned>
+Managed drift/conflicts: NONE
+
+1. Apply the exact Project Forge package update [GIT + FILE WRITE] — recommended
+2. Keep inspecting only [READ ONLY]
+3. Stop [NO ACTION]
+```
+
+Choosing option 1 authorizes only:
+
+- creation/switch to one repository-appropriate short-lived update branch when needed;
+- exact target package apply;
+- removal of unchanged retired package-managed files that the reviewed preview classified as `REMOVE`;
+- when `POC_BOOTSTRAP.json` is present, update of its exact `generation.projectForge.version` and `generation.projectForge.integrity` to the reviewed target while preserving package/profile;
+- migration of a recognized Bootstrap-generated package-verification block from duplicated current literals to the accepted manifest-driven form, only when the existing block still exactly matches the current approved metadata;
+- package/baseline/generated-consumer verification;
+- inspection of the resulting meaningful diff.
+
+It does not authorize `/deliver`, merge, npm/Core/Deployment/Bootstrap release publication, arbitrary regeneration, or deployment.
+
+## 6. Apply only the exact previewed package
+
+If the consumer is on its default branch, create/switch to a short-lived branch such as:
+
+```text
+chore/update-project-forge-<target-version>
+```
+
+Branch setup is routine inside the selected bounded update action when safe and unambiguous.
+
+Apply using the same exact package version that was previewed, for example:
+
+```text
+npx --yes @mriekki/project-forge@<target-version> update --apply
+```
+
+If explicit Core retired-path ownership transfer was separately approved, pass only the exact reviewed modified paths using the package's `--accept-retired core:<path>` contract. Never widen that set implicitly. Unchanged retired managed paths do not need this flag; the package updater removes them according to the reviewed `REMOVE` plan.
+
+For a Bootstrap-generated consumer, complete the reviewed companion metadata changes in the same bounded update before declaring success. Preserve every unrelated `POC_BOOTSTRAP.json` field. Never change package identity or profile as an incidental version update.
+
+Do not run direct `tools/package/sync.py`, Deployment Kit sync, or a remote `[sync-core]` request as part of a package-managed update.
+
+## 7. Verify all baselines, generated metadata, and the diff
+
+After apply, run the exact target package check:
+
+```text
+npx --yes @mriekki/project-forge@<target-version> check
+```
+
+Then inspect:
+
+```text
+git status --short --branch
+git diff --stat
+git diff -- PROJECT_FORGE_BASELINE.json CORE_BASELINE.json DEPLOYMENT_BASELINE.json POC_BOOTSTRAP.json .github/workflows/ci.yml
+```
+
+Confirm:
+
+- `PROJECT_FORGE_BASELINE.json` records the exact target package/version/profile;
+- component baseline commits/distributions match the umbrella baseline;
+- package check passes for the whole profile;
+- unchanged retired managed files shown as `REMOVE` in the preview are actually absent after apply, while any explicitly transferred modified retired Core file remains present and is no longer Core-managed;
+- when `POC_BOOTSTRAP.json` exists, its package/version/profile agree with `PROJECT_FORGE_BASELINE.json` and its integrity equals the exact reviewed target registry integrity;
+- when the repository contains `tools/project-forge-package/check-managed-baselines.py`, that generated baseline checker passes after all companion metadata changes;
+- generated package-verification surfaces no longer contradict the approved manifest metadata;
+- consumer-owned content was not overwritten;
+- only intended package-managed changes, reviewed generated-consumer companion changes, reviewed removals, and reviewed ownership transfers occurred.
+
+If generated CI still embeds a different package version/integrity after the update, report `GENERATED PROJECT FORGE VERIFICATION DRIFT` and stop before delivery.
+
+Present the meaningful diff for human review. After acceptance, recommend `/deliver` for normal commit/push/PR/CI mechanics.
+
+## 8. Boundaries
+
+`/project-forge-update` never:
+
+- updates only Core or only Deployment when `PROJECT_FORGE_BASELINE.json` manages them together;
+- uses a different package version for apply than the reviewed preview;
+- performs a downgrade/rollback as an ordinary update;
+- overwrites unexplained managed drift;
+- auto-accepts Core retired-path ownership transfer for a modified retired file;
+- silently repairs a pre-existing mismatch between `POC_BOOTSTRAP.json` and `PROJECT_FORGE_BASELINE.json`;
+- changes a generated consumer's package identity/profile or regenerates the repository as an incidental version update;
+- guesses at locally modified/unrecognized Bootstrap-generated verification logic;
+- publishes npm/Core/Deployment/Bootstrap releases or tags;
+- merges the consumer PR;
+- deploys an environment.
+
+If reusable shared content is wrong rather than merely outdated, route the defect through `/upstream-fix` first. Package-managed adoption of the accepted fix happens only after an accepted Project Forge package release contains that upstream commit.

package/assets/generated/core/core/skills/pull-latest/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: pull-latest
+description: Guided fast-forward-only Git update so a developer can safely get the latest remote branch state without remembering Git syntax.
+argument-hint: "[optional branch name]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Pull Latest
+
+`/pull-latest` is a small convenience wrapper for routine Git updates. It removes the need to remember `fetch`, `switch`, `pull --ff-only`, or upstream-status syntax while preserving normal repository safety.
+
+Existing repository conventions outrank Project Forge defaults.
+
+Invocation starts read-only.
+
+## 1. Inspect current state
+
+Inspect:
+
+```text
+git status --short --branch
+git branch --show-current
+git remote -v
+git branch -vv
+```
+
+Resolve:
+- current branch,
+- configured upstream for the current branch,
+- configured default branch when observable,
+- requested branch when one was supplied,
+- whether the working tree is clean enough to switch/update safely.
+
+Do not fetch, switch branches, pull, stash, merge, rebase, reset, clean, or delete anything during this first inspection.
+
+## 2. Safety stop conditions
+
+Stop before update when:
+- tracked/staged/untracked work could be overwritten or makes branch switching unsafe,
+- a merge/rebase/cherry-pick is in progress,
+- the requested branch or remote is ambiguous,
+- no usable upstream exists for the branch being updated,
+- authentication/remote access fails,
+- repository policy requires a different update method.
+
+Never auto-stash user work.
+Never use `reset --hard`, force-push, merge, or rebase as part of `/pull-latest`.
+
+## 3. Choose the update target
+
+If the human supplied a branch, use that branch as the requested target when it can be resolved safely.
+
+If no branch was supplied and the current branch is the default branch, present:
+
+```text
+PULL LATEST READY
+
+Current branch: <branch>
+Working tree: CLEAN
+
+1. Refresh remote state and pull latest <branch> [GIT WRITE] — recommended
+2. Stop [NO ACTION]
+```
+
+If no branch was supplied and the current branch is a non-default branch, present:
+
+```text
+PULL LATEST READY
+
+Current branch: <branch>
+Default branch: <default>
+Working tree: CLEAN
+
+1. Refresh and pull the current branch [GIT WRITE]
+2. Switch to the default branch and pull latest [GIT WRITE] — recommended for returning to baseline
+3. Stop [NO ACTION]
+```
+
+Only the selected option authorizes fetch/switch/pull mechanics for the selected branch.
+
+## 4. Refresh remote state
+
+For the selected remote/branch, run the repository-normal equivalent of:
+
+```text
+git fetch <remote> --prune
+```
+
+Then re-evaluate local branch, upstream, and remote head before pulling.
+
+Classify the branch as:
+- `CURRENT` — local and upstream point to the same commit,
+- `BEHIND` — local can be fast-forwarded to upstream,
+- `AHEAD` — local has commits not on upstream,
+- `DIVERGED` — both local and upstream contain unique commits,
+- `UNKNOWN` — state cannot be established safely.
+
+## 5. Apply only a fast-forward-safe update
+
+### CURRENT
+
+Do not create a no-op commit or other change. Report that the branch is already current.
+
+### BEHIND
+
+Use the repository-normal equivalent of:
+
+```text
+git pull --ff-only
+```
+
+If the user selected the default branch while currently on another branch, first switch to the existing local default branch only after confirming the working tree is safe, then perform the same fast-forward-only update.
+
+### AHEAD
+
+Do not pull, merge, rebase, reset, or push. Report `LOCAL AHEAD` and the observed commit counts when available.
+
+### DIVERGED
+
+Stop. Report `DIVERGED` and recommend explicit inspection. `/pull-latest` must not choose merge, rebase, reset, or force-push on the user's behalf.
+
+### UNKNOWN
+
+Stop and report the missing/ambiguous evidence.
+
+## 6. Verification
+
+After a successful update, inspect:
+
+```text
+git status --short --branch
+git log -1 --oneline
+```
+
+When useful, also confirm the local branch head matches its upstream.
+
+## 7. Completion report
+
+Use:
+
+```text
+PULL LATEST COMPLETE
+
+Branch: <branch>
+Remote/upstream: <remote>/<branch>
+Result: UPDATED | ALREADY CURRENT | LOCAL AHEAD | DIVERGED | BLOCKED
+Head: <sha>
+Working tree: <state>
+```
+
+Do not claim an update succeeded unless the resulting branch/upstream state was observed.
+
+## 8. Boundaries
+
+`/pull-latest` never:
+- modifies application/source files directly,
+- stashes work automatically,
+- creates or deletes branches,
+- commits or pushes,
+- merges or rebases,
+- resets or cleans the worktree,
+- resolves conflicts automatically,
+- changes remotes/upstreams unless a separate explicit action authorizes that configuration change.
+
+It is intentionally just the safe convenience path for `refresh remote state → fast-forward if possible → verify`.

package/assets/generated/core/core/skills/refine-requirements/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: refine-requirements
+description: Assess and continuously refine requirement coverage for the configured authoritative work-item source without forcing a local requirements hierarchy.
+argument-hint: "<work-item ID, external key, or topic>"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Refine Requirements
+
+Purpose: make requirements implementation-ready when the work benefits from detailed precision.
+
+This skill is proportional; it is not mandatory for every change.
+
+## 1. Resolve authority and context
+
+Read `.github/project-forge-workspace.json` when present.
+
+Determine:
+- authoritative work-item source,
+- parent/grouping context when actually available,
+- permitted Product/Feature Brief roles,
+- whether local detailed requirements are authoritative, supplemental, read-only, or not used,
+- relevant accepted ADR/design rules.
+
+Read only the minimum relevant context. Do not preload unrelated work items. Do not claim external content was read unless it is actually available.
+
+Never assume `Jira Epic == Feature Brief`.
+
+## 2. Decide whether detail is warranted
+
+Detailed refinement is useful for behavior such as:
+- lifecycle/state transitions,
+- archive/delete/restore,
+- validation/uniqueness,
+- identity/permissions/attribution,
+- data integrity,
+- concurrency/transactions,
+- destructive/reversible behavior,
+- failure handling,
+- multiple related workflows,
+- cross-layer behavior needing testable boundaries.
+
+For LIGHT/obvious work, say detailed refinement is unnecessary and return to `/start-work`.
+
+## 3. Requirement shape depends on authority
+
+### Local combined requirements permitted
+
+Prefer one combined file rather than separate user-story/domain files.
+
+Product Feature:
+
+```text
+requirements.md
+├── User Stories
+├── Domain Requirements
+├── Acceptance / Validation Scenarios
+├── Open Decisions
+├── Traceability
+└── Approval
+```
+
+Engineering Enabler:
+
+```text
+requirements.md
+├── Engineering Requirements
+├── Acceptance Criteria / Validation Scenarios
+├── Open Decisions
+├── Traceability
+└── Approval
+```
+
+Do not invent personas for technical enablers.
+
+### External work item is primary
+
+If Jira/Issue/another external system is primary and local detailed requirements are not an approved supplement:
+- assess the external content actually provided/accessible,
+- maintain concise proposed external-work-item updates during the session,
+- do not create `requirements.md` merely as a dumping ground.
+
+## 4. Initial behavior is read-only
+
+Report an evidence-backed coverage assessment first:
+
+```text
+REQUIREMENTS COVERAGE
+
+User / engineering outcomes:
+✓ ...
+○ ...
+
+Domain / engineering rules:
+✓ ...
+○ ...
+
+Acceptance / validation:
+✓ ...
+○ ...
+
+Cross-work-item/grouping context:
+✓ / ○ / N/A
+
+Open material decisions:
+- ...
+
+AUTHORITATIVE SOURCE
+<source>
+
+STATUS
+<DRAFT / APPROVED / external status / not represented locally>
+```
+
+Then present only relevant choices, for example:
+
+```text
+1. Review outcomes [READ ONLY]
+2. Review rules [READ ONLY]
+3. Review acceptance scenarios [READ ONLY]
+4. Refine identified gaps [MODIFIES DOCS or PROPOSED EXTERNAL UPDATE]
+5. Grill an unresolved decision [READ ONLY]
+6. Review full requirements/work item [READ ONLY]
+7. Approve local requirements when applicable [REQUIREMENTS GATE]
+8. Stop [NO ACTION]
+```
+
+## 5. Active refinement session
+
+Once the human selects a modifying refinement option, enter a bounded continuous session:
+
+```text
+ask one material requirement question
+→ human answers
+→ reconcile/update/propose only what was resolved
+→ update directly affected validation scenario when useful
+→ summarize exactly what changed
+→ next material question
+```
+
+For bounded requirement decisions such as lifecycle policy, validation behavior, destructive/reversible handling, or a small set of credible alternatives, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. Keep outcome wording, workflow descriptions, acceptance intent, and other human-authored framing open-ended when predefined choices would constrain the requirement.
+
+Do not ask after each answer whether to update.
+
+For local combined requirements:
+- preserve stable IDs,
+- do not renumber approved IDs,
+- keep implementation convenience out unless it is itself an approved requirement.
+
+For external-primary requirements without write authorization:
+- accumulate `PROPOSED EXTERNAL WORK-ITEM UPDATES`.
+
+If a permitted external write integration exists, require explicit `[EXTERNAL WRITE]` authorization before applying those updates.
+
+## 6. Pause only for material conflicts
+
+Stop automatic reconciliation when an answer would:
+- materially change approved higher-level scope,
+- contradict an approved Product/Feature/Enabler rule,
+- contradict an accepted ADR/design decision,
+- require a cross-cutting architecture decision,
+- remain too ambiguous to record faithfully.
+
+Then present a small explicit choice.
+
+## 7. Approval gate
+
+Local detailed requirements use only meaningful authoring states:
+
+```text
+DRAFT
+APPROVED
+```
+
+Human approval is explicit. Do not infer approval from review/planning/implementation.
+
+Before approval report coverage and open material decisions. Only an explicit `[REQUIREMENTS GATE]` choice may change local status to `APPROVED`.
+
+External work-item status/approval follows the external team's conventions; Project Forge must not fabricate a local approval state.
+
+## 8. Natural completion
+
+Summarize:
+
+```text
+REQUIREMENTS REFINEMENT COMPLETE
+
+Updated/proposed:
+- <outcomes>
+- <rules>
+- <acceptance scenarios>
+
+Open material decisions:
+None / list
+
+Authority/status:
+<source and status>
+```
+
+Then offer review, more grilling/refinement, approval when applicable, or stop.
+
+## 9. Stop boundary
+
+Do not create implementation plans or production code.
+
+When requirements are ready, recommend `/start-work <ID-or-key>`.