@mriekki/project-forge 0.0.0-stage → 2.0.0

package/assets/generated/core/core/agents/reviewer.agent.md

@@ -0,0 +1,85 @@
+---
+name: Reviewer
+description: Independent read-only review perspective over the configured work-item authority, plan/implementation diff, tests, and repository conventions.
+tools: ["read", "search", "execute"]
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Reviewer
+
+You are the independent review perspective. Start from fresh/minimal context.
+
+## Rules
+
+- Read `.github/project-forge-workspace.json` when present before assuming requirement authority.
+- Review only sources actually available.
+- Do not edit production code or implement fixes.
+- Do not broaden approved scope.
+- Do not invoke subagents.
+- Do not assume a plan, test result, or previous AI claim is correct.
+- Existing repository conventions and policies outrank Project Forge defaults.
+- Do not pin/request/switch models automatically.
+- When the host exposes the `execute` tool, use it only for non-mutating inspection or verification commands. Never use shell execution to alter files, the Git index/working tree/refs, dependencies, environments, services, or remote state.
+
+## Plan review
+
+Use the authoritative work-item/requirements plus directly relevant architecture/code.
+
+Check:
+- scope alignment and hidden assumptions,
+- dependencies and integration boundaries,
+- transactions/concurrency/data-loss implications,
+- security/operational risk,
+- test/verification strategy,
+- reversibility,
+- unnecessary complexity.
+
+## Implementation review
+
+Start from:
+- authoritative work-item/requirements,
+- current diff/changed files,
+- relevant tests and observed test evidence,
+- directly relevant repository conventions/architecture.
+
+Review for:
+- requirement fit/correctness,
+- defects/edge cases/regressions,
+- data/security/concurrency/error-handling risk,
+- architecture/maintainability,
+- tests/evidence,
+- UX/accessibility when relevant,
+- repository conventions.
+
+Classify findings:
+
+```text
+BLOCKING
+NON-BLOCKING
+OBSERVATION
+EVIDENCE GAP
+```
+
+Include file/location references when possible and state what was not verified.
+
+End with:
+
+```text
+VERDICT
+READY / CHANGES REQUIRED / INSUFFICIENT EVIDENCE
+```
+
+## Guided ending
+
+After findings use CURRENT STATE, RECOMMENDED NEXT STEP, and a small OPTIONS menu. Reviewer itself does not commit, push, create/merge PRs, or deploy.
+
+When implementation is READY and the human accepts the meaningful local diff, explicitly recommend:
+
+```text
+/deliver
+```
+
+Do not vaguely say `merge when ready`.
+
+If the delivered work item owns deployment engineering, successful engineering delivery may later hand off to `/deployment-readiness <environment>` for state-driven environment preparation; Reviewer readiness never authorizes remote or production deployment.

package/assets/generated/core/core/instructions/project-forge-docs.instructions.md

@@ -0,0 +1,45 @@
+---
+applyTo: "**/*.md"
+---
+
+# Project Forge Documentation Rules
+
+Respect `.github/project-forge-workspace.json`, `docs/project-forge-docs.json` when present, and existing repository documentation.
+
+## Authority
+
+- Do not create Product/Feature Briefs when the profile says they are unused.
+- Do not create duplicate requirement authorities.
+- `PROJECT_BRIEF.md` is a project briefing/navigation surface unless the repository explicitly says otherwise; do not let it silently compete with the accepted product/work-item authority.
+- Label experimental/supplemental briefs clearly.
+- Do not assume a Jira Epic is a Feature Brief.
+- Prefer one useful combined requirements artifact over a conveyor belt of docs when local requirements are appropriate.
+
+## Ownership
+
+When `docs/project-forge-docs.json` is present, preserve its ownership boundary:
+
+- `project` — project-owned prose/decisions; update only when the current change actually owns that documentation.
+- `project-forge` — reusable Project Forge-managed material; update through the controlled reusable-package/baseline path rather than hand-diverging it in consumers.
+- `generated-evidence` — disposable projections reconstructed from current evidence; do not hand-edit or treat them as requirements.
+
+ADRs are project-owned decisions. Do not create or approve an architectural decision on the human's behalf merely because implementation evidence suggests one.
+
+## Generated views
+
+- Markdown is canonical; the local documentation website is a projection.
+- DB/System diagrams are current-by-default projections. Do not tell the developer to maintain, rebuild, or manually synchronize generated diagrams.
+- Keep disposable site/lab output under `.project-forge/` or another repository-approved ignored cache path by default.
+- A generated view may report `CURRENT`, `STALE`, `AVAILABLE / FRESHNESS UNKNOWN`, or `NOT GENERATED`; do not claim freshness without supporting evidence.
+- Repository/runtime/database evidence outranks stale generated views.
+
+## Change impact
+
+When a change materially affects public contracts, architecture, persistence, deployment/environments, developer workflow, testing strategy, or an architectural tradeoff, surface the likely documentation impact. Safe generated projections may be rebuilt automatically; human/project-authored prose should not be silently rewritten merely because code changed.
+
+Documentation follow-up is non-blocking unless the work item's acceptance criteria explicitly require documentation.
+
+## Safety
+
+- Keep sensitive values out of tracked Markdown, documentation manifests, and generated site data.
+- Preserve evidence labels and uncertainty rather than turning inference into authoritative architecture facts.

package/assets/generated/core/core/instructions/project-forge-workflow.instructions.md

@@ -0,0 +1,79 @@
+---
+applyTo: "**"
+---
+
+# Project Forge Agentic Workflow
+
+Read `.github/project-forge-workspace.json` when present before assuming how requirements/work items are organized.
+
+Existing team conventions outrank Project Forge defaults.
+
+Possible sources include Product Briefs, Feature Briefs, Engineering Enablers, Jira Epics/Stories, GitHub Issues, local requirements, ADRs, or small session context.
+
+Use proportional rigor: `LIGHT`, `STANDARD`, `ELEVATED`.
+
+Keep explicit human gates for material requirements, substantive plans, meaningful implementation acceptance, the final merge/delivery decision, and production deployment.
+
+Once a bounded action is authorized, routine mechanics inside that scope should proceed without repeated ceremonial confirmation.
+
+For implementation, establish the repository-appropriate short-lived work branch as routine setup once implementation itself is authorized; do not add a separate branch-creation gate when branch policy/naming and scope are clear.
+
+Continuous modes such as `/grill-me`, `/grill-with-docs`, `/refine-requirements`, `/coach`, `/learning-review`, and `/deployment-readiness` continue until stopped or naturally complete.
+
+During interactive questioning, prefer concise choice-first options for genuinely bounded human decisions, including `Other / specify` and `Not sure — recommend one` when appropriate. Keep factual/environment-specific values and questions intended to elicit the human's own framing, reasoning, debugging approach, design rationale, or understanding open-ended unless options are later useful as scaffolding.
+
+For deployment readiness, inspect existing non-secret configuration before asking setup questions. Show already-known simple machine facts such as hostname/address, deployment user, port, and target OS for confirmation. Ask only for missing or conflicting facts. Keep deployment-tool implementation identifiers such as logical target names, `targetName`, SSH aliases, profile paths, and trust-file paths internal unless troubleshooting or genuine ambiguity requires them.
+
+Shared managed code keeps its canonical owner. When a consumer contains `CORE_BASELINE.json` or `DEPLOYMENT_BASELINE.json`, treat those baselines as ownership evidence. A temporary edit to a shared-managed consumer file may be used to diagnose or prove a reusable defect, but it is not the canonical deliverable.
+
+Before consumer delivery, run available managed-baseline integrity checks. If Core- or Deployment-Kit-managed files have unexplained local drift, stop before staging/commit/push and route the reusable change through `/upstream-fix`. Fix the owning canonical repository, deliver/merge it there under normal gates, then adopt the exact accepted shared commit back into the consumer through the appropriate sync mechanism and retest in consumer context.
+
+Do not manually preserve a private consumer fork of shared managed code merely because the consumer exposed the bug. Consumer-owned product/application files remain normal consumer implementation scope.
+
+After implementation review and local human acceptance, manually invoking `/deliver` authorizes routine short-lived-branch recovery/setup as needed, selective stage/commit/push, PR creation/update, and PR-CI inspection. `/deliver` then stops once for the explicit `Merge and finalize delivery` decision. When the PR still exactly matches the accepted implementation, that one choice combines final PR acceptance, merge authorization, post-merge CI observation, and safe delivered-branch finalization.
+
+Changed PR evidence re-opens the relevant review gate. Merge never implies production-deployment authorization.
+
+## Post-delivery documentation and learning handoff
+
+After engineering delivery is complete, documentation impact and learning are **non-blocking follow-ups**, not new delivery states or gates.
+
+Use the accepted work-item/PR diff conservatively to classify likely documentation impact. Examples:
+
+- public API/contract changes may affect architecture/runtime/API narrative;
+- services, dependencies, messaging, caches, auth, observability, deployment topology, or failure handling may affect System evidence;
+- entities, migrations, schema/DDL, ORM, queries, constraints, or indexes may affect DB evidence;
+- environment/deployment changes may affect operations docs;
+- durable developer/test workflow changes may affect engineering docs;
+- a consequential architectural tradeoff may deserve an ADR recommendation.
+
+A changed file proves relevant evidence was touched; it does not by itself prove a runtime or physical-schema change.
+
+When the relevant tools exist and prerequisites are safe, `/deliver` may best-effort prepare **disposable** evidence/site projections under:
+
+```text
+.project-forge/docs-cache/system/
+.project-forge/docs-cache/database/
+.project-forge/docs-site/
+```
+
+System evidence may be reconstructed from the current repository. Database evidence may be generated automatically only when a safe local development/test database path is already explicit; never guess a path merely to populate docs.
+
+If `tools/project-forge-docs/docs-site.py` exists, a build of the local documentation projection may follow safe lab preparation. Failure to build docs or a lab projection does not change `DELIVERY COMPLETE`.
+
+Do not silently rewrite project-owned narrative or approve/create an ADR solely because implementation evidence changed. Instead surface a compact `DOCUMENTATION IMPACT` handoff, for example:
+
+```text
+DOCUMENTATION IMPACT
+
+✓ Project brief: no material change detected
+★ System evidence: changed; current projection prepared
+★ Database evidence: changed; /db-lab recommended
+○ ADR consideration: new synchronous external dependency introduced
+
+/docs — explore the current project documentation
+```
+
+Use only claims supported by observed evidence. Keep `/docs`, `/db-lab`, `/system-lab`, `/code-walkthrough`, and `/learning-review` visible when useful, but never require them solely to complete engineering delivery.
+
+Do not pin or automatically escalate models.

package/assets/generated/core/core/learning/CODING_DRILLS.md

@@ -0,0 +1,35 @@
+# Coding / DSA Drills
+
+Optional interview-style practice.
+
+Preferred loop:
+
+```text
+problem
+→ clarifying questions
+→ approach
+→ complexity
+→ code
+→ tests/edge cases
+→ hints only when needed
+→ alternatives
+→ feedback
+```
+
+Patterns:
+
+- arrays/strings,
+- hash map/set,
+- stack/queue,
+- two pointers,
+- sliding window,
+- sorting,
+- binary search,
+- linked lists,
+- trees,
+- BFS/DFS,
+- graph basics,
+- recursion,
+- Big-O.
+
+Prefer project-themed exercises when practical.

package/assets/generated/core/core/learning/DIAGRAM_GUIDE.md

@@ -0,0 +1,59 @@
+# Diagram Guide
+
+Diagrams are learning views, not architecture authorities.
+
+Use current repository/runtime/database evidence first. Generated diagrams are disposable projections and should normally be regenerated from current evidence when the relevant lab is invoked rather than manually maintained.
+
+## Lightweight diagrams
+
+Coach may use ephemeral Mermaid/text diagrams in chat for:
+
+- architecture,
+- request flow,
+- sequence,
+- state machine,
+- ER/data relationships,
+- CI/CD,
+- deployment,
+- concurrency,
+- messaging timelines,
+- failure propagation.
+
+Only save them as durable project artifacts when explicitly requested.
+
+## Interactive diagrams
+
+Prefer `/db-lab` when the learning question needs schema/query/index/ORM/plan evidence. Prefer `/system-lab` when it needs architecture/runtime/API/dependency/failure/scale/observability/security/deployment evidence.
+
+Interactive views should support learning, not merely look attractive. Useful interactions include:
+
+- select a scenario and highlight participating nodes/edges;
+- click a component/table/dependency for evidence and responsibilities;
+- show query/index/plan relationships;
+- show work-item change overlays;
+- show failure or scale perturbations;
+- link system database nodes to `/db-lab` depth;
+- distinguish current evidence from inferred topology.
+
+## Evidence provenance
+
+Use explicit labels where ambiguity matters:
+
+```text
+CONFIRMED BY CODE
+CONFIRMED BY RUNTIME
+DOCUMENTED INTENT
+INFERRED
+UNKNOWN
+LEARNER ASSUMPTION
+```
+
+A static dependency edge is not automatically proof that the call occurred at runtime. A generated ERD is not more authoritative than the physical database metadata from which it was generated.
+
+## Learning behavior
+
+After a diagram, ask the developer to explain the relevant flow, state, failure path, boundary, scaling concern, or tradeoff.
+
+For advanced exercises, ask the learner to predict a failure/plan/scale consequence before revealing the overlay when useful.
+
+Never require the human to "refresh" or "rebuild" a learning diagram as routine maintenance. Running the lab means inspect current evidence and create/show the current view.

package/assets/generated/core/core/learning/ENGINEERING_LEARNING_WORKBOOK.md

@@ -0,0 +1,108 @@
+# Engineering Learning Workbook
+
+This is an optional, repository-neutral learning scaffold.
+
+Use the actual project first. The goal is to understand, trace, debug, defend, and explain real engineering work rather than memorize a generic curriculum.
+
+## Learning tools
+
+Use the learning tools for different purposes:
+
+```text
+/code-walkthrough — instructional walkthrough of actual implementation changes
+/learning-review   — assessment of whether the developer can explain and defend the implementation
+/coach             — targeted concept learning, debugging practice, design discussion, drills, and deeper follow-up
+/db-lab            — evidence-backed database/schema/ORM/query-plan/change exploration and database interview practice
+/system-lab        — evidence-backed architecture/runtime/failure/scale/change exploration and system-design interview practice
+```
+
+All learning activity is optional and never an engineering delivery gate.
+
+For database usage examples, see `docs/process/DATABASE_LEARNING_WORKBENCH.md` in a greenfield consumer. For advanced system-design usage, see `docs/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md`.
+
+## Preferred project-first sequence
+
+When an implementation is stable enough to study, a useful optional sequence is:
+
+```text
+implementation
+→ /code-walkthrough
+→ /learning-review
+→ targeted /coach, /db-lab, or /system-lab where gaps remain
+```
+
+After successful delivery, the workflow may surface the relevant evidence labs again while the change is fresh. A work item that changed persistence may make `/db-lab changes <work-item>` especially useful; one that changed APIs, dependencies, messaging, runtime topology, security, observability, performance or failure behavior may make `/system-lab changes <work-item>` especially useful. These are recommendations, not gates.
+
+A code walkthrough should connect two views of every meaningful change:
+
+```text
+FUNCTIONAL
+What behavior changed? What can the user/system do now?
+
+TECHNICAL
+Which files, classes, functions, data structures, framework mechanisms, tests, and dependencies make that behavior work?
+```
+
+Then connect the files into an end-to-end flow such as request, data, state, event, persistence, UI, or operational behavior. Use the repository's actual architecture rather than forcing a generic sequence.
+
+During a walkthrough, deeper learning can branch into tracing, interactive diagrams, debugging discussion, design tradeoffs, quizzes, capacity/failure reasoning, or interview-style explanation. The walkthrough and labs remain read-only; discovered implementation issues return to the normal engineering workflow rather than being silently fixed inside learning mode.
+
+## Advanced learning pattern
+
+Evidence labs should favor active reasoning:
+
+```text
+current evidence
+→ learner prediction/assumption
+→ reveal strongest available evidence
+→ explain discrepancy
+→ trace/apply/debug
+→ defend tradeoff
+→ change one constraint
+→ reason again
+```
+
+Use explanation-first when the human asks for it. Do not turn every learning interaction into a quiz.
+
+Generated workbench diagrams are disposable projections. The repository/database/runtime evidence remains authoritative, and invoking a lab should rebuild its view from current evidence automatically.
+
+## Suggested practice loop
+
+```text
+concept or changed code
+→ project example
+→ developer explains in own words
+→ trace/apply/debug
+→ tradeoff/failure-mode follow-up
+→ interview-style explanation when useful
+```
+
+## Core areas
+
+- language/framework fundamentals,
+- application/request/data flow,
+- APIs and integration boundaries,
+- database/SQL/ORM behavior,
+- frontend state/validation/accessibility when relevant,
+- testing/debugging/observability,
+- messaging/distributed systems when relevant,
+- CI/CD/deployment/operations,
+- security and data protection,
+- architecture/system design,
+- capacity/performance/reliability,
+- coding/DSA interview patterns.
+
+Use `LEARNING_MAP.md` to choose a small number of high-value topics and the drill files for focused practice. Database and system-design depth should be tracked by independent competencies rather than one broad score. Learning progress is optional and never an engineering gate.
+
+## Experience credibility
+
+Keep these categories distinct:
+
+```text
+actually implemented/used
+AI-generated but reviewed/understood
+studied/practiced
+not yet understood
+```
+
+A code walkthrough or lab can help move AI-assisted implementation toward reviewed/understood code, but it does not by itself prove mastery or professional experience. Generated diagrams and completed exercises must not become false claims of professional experience.

package/assets/generated/core/core/learning/LEARNING_MAP.md

@@ -0,0 +1,108 @@
+# Optional Engineering Learning Map
+
+Use only when useful.
+
+Tracks:
+
+- language/framework fundamentals,
+- application architecture,
+- APIs/HTTP,
+- databases/SQL/ORM,
+- frontend,
+- testing/debugging,
+- messaging/event-driven systems,
+- Docker/CI/CD/operations,
+- security,
+- system design,
+- coding/DSA,
+- interview communication.
+
+Levels:
+
+```text
+L1 Recognize
+L2 Explain
+L3 Trace
+L4 Apply / Debug
+L5 Defend / Design
+L6 Interview Ready
+```
+
+## Database learning is multi-dimensional
+
+Do not reduce database learning to one "SQL" level. When database depth matters, assess the relevant areas independently:
+
+```text
+relational modeling
+keys + integrity constraints
+normalization + anomalies
+SQL query construction
+indexes + access patterns
+query plans + performance reasoning
+transactions + concurrency
+ORM translation
+schema evolution + migrations
+database debugging
+design defense / interview communication
+```
+
+Use `/db-lab` for evidence-backed exploration of the current project's schema, queries, ORM translation, query plans, migrations, change impact, and query-to-ERD relationships. Invoking the lab means inspect current evidence; generated views are disposable rather than manually maintained diagrams. Use `/coach` for adaptive teaching and reinforcement.
+
+## System-design learning is multi-dimensional
+
+Do not reduce system design to one generic architecture score. Assess the relevant areas independently:
+
+```text
+requirements + scope framing
+capacity estimation + workload modeling
+API + contract design
+service/module decomposition
+data/storage selection
+caching
+messaging + asynchronous workflows
+consistency + distributed coordination
+scaling + partitioning
+availability + fault tolerance
+latency + performance
+runtime/deployment topology
+observability + SLO reasoning
+security + abuse resistance
+cost/complexity awareness
+architecture evolution
+incident/debug reasoning
+testing/verification strategy
+tradeoff defense
+interview communication
+```
+
+Use `/system-lab` for evidence-backed exploration of the current project's architecture, runtime/data/event flows, dependencies, failure behavior, capacity/performance, observability, security, messaging, deployment, testing, work-item architecture impact, evolution, and interview practice. Generated interactive diagrams are disposable projections of current evidence; they are not a second architecture authority and should be regenerated from current evidence when the lab is invoked.
+
+Use `/coach system design` for conceptual teaching, adaptive questions, and transfer practice. Prefer prediction-before-reveal for plans, failures, scale changes, consistency situations, and design perturbations when that improves learning.
+
+## How real-code learning maps to the levels
+
+A structured `/code-walkthrough` is especially useful for the first three levels:
+
+```text
+L1 Recognize — identify important changed files, responsibilities, and concepts
+L2 Explain   — describe the functional and technical changes in own words
+L3 Trace     — follow request/data/state/event flow across the implementation
+```
+
+Deeper follow-up can move into:
+
+```text
+L4 Apply / Debug   — reason through failure modes, evidence, and debugging approach
+L5 Defend / Design — explain choices, alternatives, tradeoffs, and architecture
+L6 Interview Ready — explain the implementation clearly under follow-up questioning
+```
+
+For database work, L4-L6 should include evidence-based reasoning about schema choices, constraints, access patterns, indexes/plans, transactions, ORM behavior, migration safety, and credible alternatives where relevant.
+
+For system-design work, L4-L6 should include evidence-based reasoning about workload assumptions, boundaries, APIs/data flows, failure propagation, consistency, latency, scaling, reliability, observability, security, deployment, testing, cost/complexity, architecture evolution, and credible simpler alternatives.
+
+A learner can be L5 in API design and L2 in distributed consistency, or strong in SQL construction and weak in indexing. Preserve that shape instead of averaging it away.
+
+Use `/learning-review` to assess understanding after a walkthrough. Use `/coach` for targeted reinforcement, practice, or deeper exploration. Use `/db-lab` and `/system-lab` when concrete project evidence is the learning material. These activities are optional and do not affect engineering delivery state.
+
+Coach should recommend only a small number of next topics based on the actual repository/work item.

package/assets/generated/core/core/learning/LEARNING_PROGRESS.md

@@ -0,0 +1,39 @@
+# Optional Learning Progress
+
+This file is optional and never an engineering gate.
+
+| Topic | Level | Evidence/session | Next target | Last reviewed |
+|---|---:|---|---|---|
+| Language/framework | Not assessed | | | |
+| Architecture | Not assessed | | | |
+| Database/SQL | Not assessed | | | |
+| Frontend | Not assessed | | | |
+| Testing/debugging | Not assessed | | | |
+| CI/CD/operations | Not assessed | | | |
+| Security | Not assessed | | | |
+| System design | Not assessed | | | |
+| Coding/DSA | Not assessed | | | |
+
+## Evidence examples
+
+Record evidence only when the human explicitly chooses to update learning progress. Useful evidence can include:
+
+- completed `/code-walkthrough` of a real implementation change set;
+- explained the functional and technical purpose of important changed files;
+- traced a request/data/state/event path across the implementation;
+- explained a design choice and a credible alternative;
+- reasoned through a failure mode or debugging approach;
+- predicted then explained query-plan/index behavior using `/db-lab` evidence;
+- explained schema/ORM/migration consequences from `/db-lab changes <work-item>`;
+- traced an evidence-backed runtime/dependency path using `/system-lab`;
+- predicted failure propagation, bottlenecks, consistency behavior, or latency consequences and reconciled the prediction with evidence;
+- defended an architecture choice against a simpler credible alternative;
+- adapted a design after an interview-style scale/reliability/security constraint changed;
+- passed a `/learning-review` question at a demonstrated level;
+- completed a focused `/coach` exercise or drill.
+
+For database and system-design depth, prefer recording the demonstrated competency rather than one broad level. For example, capacity estimation, distributed consistency, API design, relational modeling and query-plan reasoning can legitimately be at different levels.
+
+A walkthrough, generated workbench, or completed lab invocation is evidence of learning/review activity, not automatic proof of mastery. Record demonstrated understanding conservatively.
+
+Do not update automatically.

package/assets/generated/core/core/learning/RESOURCE_CATALOG.md

@@ -0,0 +1,25 @@
+# Optional External Learning Resources
+
+Prefer:
+
+1. official docs,
+2. official/vendor tutorials,
+3. current high-quality videos,
+4. interactive practice.
+
+Show only 1–3 resources at a time.
+
+Suggested source families:
+
+- language/framework official docs,
+- database vendor docs,
+- MDN for web/HTTP,
+- Docker docs,
+- GitHub/Git docs,
+- testing-framework docs,
+- LeetCode or equivalent for targeted DSA/SQL practice.
+
+When current web access is available, verify specific current video/tutorial
+recommendations rather than relying on stale links.
+
+External resources never become an engineering requirement.