@thiaq/project-skill 0.1.0 → 0.1.2

package/README.md

@@ -26,6 +26,7 @@ npx thiaq-project-skill install --agent codex
 ```text
 Use the thiaq-project skill. Refresh the existing ThiaQ project additively:
 read existing project context, scan the repo, use live discovery evidence if
-available, and propose a reviewed product map without making the customer or
-project name the root node.
+available, show me a draft three-level product tree for review, and only then
+propose a reviewed product map without making the customer or project name the
+root node.
 ```

package/SKILL.md

@@ -57,12 +57,15 @@ Jira, browser traces, tests, or other connected tools.
    selector gaps, blocked paths, screenshots, and bug candidates.
 8. Fuse static repo analysis with live discovery. Prefer names that match the
    product's own docs, routes, UI labels, tests, and issue language.
-9. Propose a reviewable product map shaped like
-   `Product Area -> Feature or Workflow -> Surface or Control`. The customer or
-   project name is context, not the root tree node.
-10. Ask the first user to review naming, split/merge areas, confirm critical
-   paths, and flag anything ThiaQ should never automate.
-11. Call ThiaQ MCP tools to submit summaries and proposed changes.
+9. Draft an explicit tree before any hierarchy write. It must have at least
+   three levels: `Product Area -> Feature or Workflow -> Surface`. Controls may
+   be fourth-level leaves. The customer or project name is context, not the
+   root tree node.
+10. Show the proposed tree to the first user in the chat, using indentation or
+   bullets so the structure is visible. Ask what should be renamed, merged,
+   split, moved, marked uncertain, or treated as release-critical.
+11. Only after the first user reviews or explicitly asks you to proceed, call
+   ThiaQ MCP tools to submit summaries and proposed changes.
 12. After discovery, use ThiaQ test ideas and issue categories to propose
    deterministic coverage work.
 
@@ -194,11 +197,35 @@ Use `get_project_context` first. Then call the smallest useful write operation:
 - `propose_access_profile_changes` for test URL, role, auth, and secret refs.
 - `propose_safety_policy_changes` for safe/unsafe action boundaries.
 - `list_test_ideas` after discovery.
+- `list_operational_state` to inspect the agent-manageable workspace backlog:
+  ideas, groups, issues, journey candidates, runner work, and proposals.
+- `update_test_idea` to soft-triage, archive, restore, or annotate test ideas.
+- `group_test_ideas` to dedupe or collect ideas into scenario, area, or review
+  groups.
+- `merge_test_ideas` to archive duplicate ideas under a primary idea.
 - `propose_test_idea_promotion` to create reviewable promotion work.
 - `list_issue_categories` for UX confusion, selector, driver, assertion, and
   safety gaps.
+- `create_issue_category` to store an operational issue category from evidence.
+- `update_issue_category` to close, reopen, archive, restore, relabel, or
+  reprioritize operational issue categories.
+- `merge_issue_categories` to archive duplicate issues under a primary issue.
 - `create_repair_proposal` when an issue needs product, adapter, selector, or
   assertion repair.
+- `update_journey_candidate` to reprioritize, archive, restore, or annotate
+  candidate journeys without approving executable coverage.
+- `cancel_runner_job` for stale queued/running discovery or scenario work.
+- `retry_runner_job` to clone failed/stale runner work without changing original
+  evidence.
+- `update_proposal_status` to withdraw, archive, restore, or supersede draft
+  proposals. Do not use it for final accept/reject review gates.
+- `bulk_archive_operational_records` to dry-run and then archive large noisy
+  operational backlogs by type, status, source run, and explicit keep IDs.
+- `reconcile_operational_state` to dry-run or apply safe stale runner cleanup.
+
+Use soft mutation statuses instead of deletion. Evidence, run artifacts,
+approved flows, approved journeys, manifests, safety policy, and CI tier changes
+remain review-gated.
 
 For tool schemas and payload examples, read
 `references/mcp-tools.md` only when preparing MCP calls.
@@ -216,9 +243,11 @@ When submitting repo evidence, keep findings structured:
   "personas": [{ "name": "Workspace Admin", "evidence": ["docs/admin.md"] }],
   "jobs": [{ "title": "Create and share a workflow", "personaName": "Analyst" }],
   "hierarchy": {
-    "areas": [{ "areaId": "area.dashboard", "name": "Dashboard" }],
-    "features": [{ "featureId": "feature.projects", "areaId": "area.dashboard", "name": "Projects" }],
-    "surfaces": [{ "surfaceId": "surface.project-list", "featureId": "feature.projects", "name": "Project list" }]
+    "nodes": [
+      { "nodeId": "area.dashboard", "parentId": null, "level": 1, "kind": "product_area", "name": "Dashboard" },
+      { "nodeId": "feature.projects", "parentId": "area.dashboard", "level": 2, "kind": "feature", "name": "Projects" },
+      { "nodeId": "surface.project-list", "parentId": "feature.projects", "level": 3, "kind": "surface", "name": "Project list" }
+    ]
   },
   "accessProfile": {
     "loginUrl": "https://staging.example.com",
@@ -240,13 +269,20 @@ should expose product behavior, not account metadata:
 - Top visible level: product areas such as Dashboard, Canvas Authoring,
   Collaboration, Admin, Billing, Reporting, or Workspace Organization.
 - Second level: features or workflows inside each area.
-- Third level: surfaces, controls, states, or canvas affordances that scenarios
-  can anchor to.
+- Third level: surfaces, states, or canvas affordances that scenarios can
+  anchor to.
+- Optional fourth level: controls only when the control is stable, named, and
+  useful as a scenario anchor.
 - Scenario and issue counts should attach to the most specific useful node.
 - Never use the customer, project, tenant, or product name as the visible root
   node. Keep that as surrounding context.
 - Carry evidence and confidence for inferred nodes so the first user can
   rename, merge, split, or reject suggestions.
+- Do not submit a flat list of sections as a hierarchy. The hierarchy proposal
+  must contain explicit tree nodes with stable `nodeId`, `parentId`, `level`,
+  `kind`, `name`, evidence, confidence, and review questions.
+- Do not submit the hierarchy before showing the draft tree to the user unless
+  the user explicitly tells you to proceed without review.
 
 Use repo structure alone only as a starting hypothesis. Prefer the fused view:
 what users can see in live discovery, what code/routes/tests call it, and what

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thiaq/project-skill",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "private": false,
   "description": "ThiaQ project setup skill for Codex and Claude Code agents.",

package/references/mcp-tools.md

@@ -111,12 +111,18 @@ but mark them as proposals that should be fused with live discovery.
 ## Product Hierarchy Proposal
 
 Use `propose_product_hierarchy_changes` after fusing live discovery evidence
-with static repo analysis. The proposal should be reviewable by the first user;
-do not treat inferred names as final.
+with static repo analysis. Before calling it, show the proposed tree to the
+first user and ask what should be renamed, merged, split, moved, marked
+uncertain, or treated as release-critical. Do not treat inferred names as final.
 
 The visible tree should start with product areas. Do not make the customer,
 tenant, project, or product name the root node.
 
+The proposal must include an explicit tree with at least three levels:
+`Product Area -> Feature or Workflow -> Surface`. Controls may be fourth-level
+leaves when they are stable scenario anchors. Flat sections or areas with nested
+free-form metadata are not enough.
+
 ```json
 {
   "name": "propose_product_hierarchy_changes",
@@ -126,26 +132,29 @@ tenant, project, or product name the root node.
     "summary": "Combines live UI discovery with repo routes, tests, and docs.",
     "source": "discovery:job-id + repo-summary:main",
     "payload": {
-      "areas": [
+      "nodes": [
         {
-          "areaId": "area.canvas-authoring",
+          "nodeId": "area.canvas-authoring",
+          "parentId": null,
+          "level": 1,
+          "kind": "product_area",
           "name": "Canvas Authoring",
           "evidenceRefs": ["discovery:screen.canvas", "app/routes/canvas.tsx"],
           "confidence": 0.82
-        }
-      ],
-      "features": [
+        },
         {
-          "featureId": "feature.canvas-shapes",
-          "areaId": "area.canvas-authoring",
+          "nodeId": "feature.canvas-shapes",
+          "parentId": "area.canvas-authoring",
+          "level": 2,
+          "kind": "feature",
           "name": "Shapes",
           "evidenceRefs": ["discovery:control.shape-toolbar", "tests/e2e/shapes.spec.ts"]
-        }
-      ],
-      "surfaces": [
+        },
         {
-          "surfaceId": "surface.shape-toolbar",
-          "featureId": "feature.canvas-shapes",
+          "nodeId": "surface.shape-toolbar",
+          "parentId": "feature.canvas-shapes",
+          "level": 3,
+          "kind": "surface",
           "name": "Shape toolbar",
           "evidenceRefs": ["discovery:control.shape-toolbar"]
         }
@@ -231,3 +240,262 @@ flow code.
   }
 }
 ```
+
+## Operational Workspace Mutations
+
+Agents may directly manage living QA workspace state when the operation is
+soft, reversible, and reasoned. Do not hard-delete evidence. Do not accept or
+reject review gates. Do not mutate approved flow code, journey specs, manifests,
+safety policy, access policy, or CI tiers.
+
+### List Operational State
+
+Use this before cleanup work to inspect all MCP-manageable backlog records in
+one bounded payload.
+
+```json
+{
+  "name": "list_operational_state",
+  "arguments": {
+    "projectId": "project-id",
+    "limit": "50",
+    "status": "draft"
+  }
+}
+```
+
+### Update A Test Idea
+
+Use this to triage, annotate, archive, restore, or reprioritize discovery
+findings.
+
+```json
+{
+  "name": "update_test_idea",
+  "arguments": {
+    "projectId": "project-id",
+    "ideaId": "idea.dashboard.create",
+    "status": "archived",
+    "reason": "Covered by scenario group scenario.dashboard.create"
+  }
+}
+```
+
+### Group Test Ideas
+
+Use this to dedupe or collect findings into scenario, product-area, or review
+groups.
+
+```json
+{
+  "name": "group_test_ideas",
+  "arguments": {
+    "projectId": "project-id",
+    "groupId": "scenario.dashboard.create",
+    "groupKind": "scenario",
+    "label": "Dashboard create path",
+    "ideaIds": ["idea.dashboard.create", "idea.dashboard.empty-state"],
+    "rationale": "These findings describe one scenario candidate."
+  }
+}
+```
+
+### Merge Test Ideas
+
+Use this when several findings describe the same coverage need. The primary is
+kept; secondaries are archived with merge evidence.
+
+```json
+{
+  "name": "merge_test_ideas",
+  "arguments": {
+    "projectId": "project-id",
+    "primaryIdeaId": "idea.dashboard.create",
+    "secondaryIdeaIds": ["idea.dashboard.empty-state"],
+    "reason": "Both findings describe the same dashboard create scenario."
+  }
+}
+```
+
+### Create An Issue Category
+
+Use this to persist a new operational gap that the agent found in evidence.
+
+```json
+{
+  "name": "create_issue_category",
+  "arguments": {
+    "projectId": "project-id",
+    "categoryId": "selector-gap.dashboard-create",
+    "categoryType": "selector_gap",
+    "label": "Dashboard create selector gap",
+    "severity": "medium",
+    "sourceIds": ["idea.dashboard.create"],
+    "reason": "No stable role/test-id locator exists for the create action."
+  }
+}
+```
+
+### Update An Issue Category
+
+Use this to close, reopen, archive, restore, relabel, or reprioritize UX,
+selector, driver, assertion, or safety gaps.
+
+```json
+{
+  "name": "update_issue_category",
+  "arguments": {
+    "projectId": "project-id",
+    "categoryId": "selector-gap.dashboard-create",
+    "status": "closed",
+    "reason": "Stable role locator added to the reviewed interaction contract."
+  }
+}
+```
+
+### Merge Issue Categories
+
+Use this when multiple issues describe the same gap. The primary issue remains;
+secondaries are archived.
+
+```json
+{
+  "name": "merge_issue_categories",
+  "arguments": {
+    "projectId": "project-id",
+    "primaryCategoryId": "selector-gap.dashboard-create",
+    "secondaryCategoryIds": ["selector-gap.create-button"],
+    "reason": "Both point at the same missing create-button locator."
+  }
+}
+```
+
+### Update A Journey Candidate
+
+Use this for ranking and triage only. It does not approve executable coverage.
+
+```json
+{
+  "name": "update_journey_candidate",
+  "arguments": {
+    "projectId": "project-id",
+    "candidateId": "journey-candidate-id",
+    "priority": "high",
+    "status": "active",
+    "reason": "Matches release-critical onboarding path."
+  }
+}
+```
+
+### Cancel Runner Work
+
+Use this for queued or running discovery/scenario jobs that are stale or unsafe.
+Completed jobs are immutable.
+
+```json
+{
+  "name": "cancel_runner_job",
+  "arguments": {
+    "projectId": "project-id",
+    "runnerJobId": "runner-job-id",
+    "runnerJobRequestId": "runner-request-id",
+    "reason": "Superseded by discovery run with updated safety boundaries."
+  }
+}
+```
+
+### Retry Runner Work
+
+Use this to clone a failed or stale runner job/request into new queued work. The
+original evidence remains unchanged.
+
+```json
+{
+  "name": "retry_runner_job",
+  "arguments": {
+    "projectId": "project-id",
+    "runnerJobId": "runner-job-id",
+    "reason": "Runner environment is now healthy."
+  }
+}
+```
+
+### Withdraw Or Supersede A Proposal
+
+Use this for draft proposal lifecycle cleanup. Final accept/reject remains a UI
+review gate.
+
+```json
+{
+  "name": "update_proposal_status",
+  "arguments": {
+    "projectId": "project-id",
+    "proposalId": "proposal-id",
+    "status": "superseded",
+    "supersededById": "replacement-proposal-id",
+    "reason": "Merged into a broader repair proposal."
+  }
+}
+```
+
+### Bulk Archive Operational Records
+
+Use this for large discovery-noise resets when thousands of proposals or test
+ideas would otherwise require one call per record. It is dry-run by default and
+returns compact counts plus sample IDs, not full proposal or idea bodies.
+
+By default, it targets only `proposals` and `test_ideas`. Add more record types
+explicitly when clearing groups, issues, journey candidates, or stale runner
+work. It never hard-deletes evidence, never archives accepted/rejected
+proposals, never archives approved/promoted/implemented test ideas, and only
+cancels queued/running runner work.
+
+Preview first:
+
+```json
+{
+  "name": "bulk_archive_operational_records",
+  "arguments": {
+    "projectId": "project-id",
+    "recordTypes": ["proposals", "test_ideas"],
+    "sourceRunIds": ["runner.discovery.ffe22c16"],
+    "proposalTypes": ["coverage-gap", "candidate-pathway", "bug-candidate"],
+    "dryRun": "true",
+    "excludeIds": ["proposal-to-keep", "idea.to.keep"],
+    "reason": "Preview cleanup of superseded discovery noise."
+  }
+}
+```
+
+Apply after reviewing the returned counts:
+
+```json
+{
+  "name": "bulk_archive_operational_records",
+  "arguments": {
+    "projectId": "project-id",
+    "recordTypes": ["proposals", "test_ideas"],
+    "sourceRunIds": ["runner.discovery.ffe22c16"],
+    "dryRun": "false",
+    "excludeIds": ["proposal-to-keep", "idea.to.keep"],
+    "reason": "Archive superseded discovery noise after preserving latest real findings."
+  }
+}
+```
+
+### Reconcile Operational State
+
+Use this to find stale queued/running runner work. It is dry-run by default.
+Only set `dryRun` to `"false"` when the cancellation is safe.
+
+```json
+{
+  "name": "reconcile_operational_state",
+  "arguments": {
+    "projectId": "project-id",
+    "staleRunnerHours": "24",
+    "dryRun": "true",
+    "reason": "Nightly cleanup of stale queued discovery work."
+  }
+}
+```