prizmkit 1.1.173 → 1.1.175

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,109 +4,122 @@ Use this reference when the user adds features to an existing app/plan.
4
4
 
5
5
  ## Pre-Checks
6
6
 
7
- 1. Read existing `feature-list.json`.
8
- 2. Determine current max ID and continue from next `F-NNN`.
9
- 3. **Detect existing writing style** (see §Style Detection below).
10
- 4. Preserve compatibility with existing dependency structure.
11
- 5. **Project conventions** — handled by the main SKILL.md flow (rule #6) before incremental planning begins. No additional action needed here; conventions are loaded automatically.
7
+ 1. Do not read the complete existing `feature-list.json`. Run:
8
+ ```bash
9
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py context --input .prizmkit/plans/feature-list.json
10
+ ```
11
+ 2. Consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and the five most recent `{id, description}` pairs.
12
+ 3. Use the returned `next_id` for the first addition and continue sequentially.
13
+ 4. Preserve confirmed project conventions and dependency correctness without treating recent chronology as relevance.
14
+ 5. Project conventions remain handled by the main `SKILL.md` flow before incremental planning begins.
12
15
 
13
- If `feature-list.json` is missing, ask whether to initialize a new plan.
16
+ If `feature-list.json` is missing, ask whether to initialize a new plan. If the context command reports invalid input or exhausted ID capacity, stop and resolve that explicit blocker instead of reading or rewriting the entire list in AI context.
14
17
 
15
- ## Style Detection (Automatic)
18
+ ## Recent-History Relevance Gate
16
19
 
17
- Before drafting new features, analyze existing plan to preserve consistency:
20
+ The five recent pairs are a bounded continuity and conflict check, not a default source of new feature content.
18
21
 
19
- 1. **Language Detection**
20
- - Scan `title` and `description` fields
21
- - If >70% English titles → default to English
22
- - If >70% Chinese titles → suggest Chinese (or allow bilingual)
22
+ - Add no historical content by default.
23
+ - Inspect recent descriptions only for material continuation, duplication, conflict, a shared public behavior contract, or a real execution prerequisite.
24
+ - Chronology, broad module overlap, shared technology, reusable implementation ideas, and similar wording alone do not establish relevance.
25
+ - When omission would make the new feature's scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect, incorporate only the minimum exact contract-affecting information into that feature.
26
+ - Do not persist vague text such as `related to F-123` and do not copy an entire historical description merely because it overlaps.
27
+ - Add an old ID to `dependencies` only when it is a real execution prerequisite.
23
28
 
24
- 2. **Description Density**
25
- - Calculate avg word count per description
26
- - If avg <30 words → draft concise descriptions
27
- - If avg 30-80 words → draft standard detail
28
- - If avg >80 words → draft detailed descriptions
29
+ When the user explicitly identifies an old feature ID for modification or detailed review, or a validation error names it, load only that complete top-level feature:
29
30
 
30
- 3. **Acceptance Criteria Patterns**
31
- - Count avg AC per feature
32
- - Identify dominant format (Given/When/Then Gherkin, BDD, or loose)
33
- - Draft new AC in same format
34
-
35
- 4. **Complexity Distribution**
36
- - Count low/medium/high distribution in existing features
37
- - Alert if new features deviate significantly (>20 percentile points)
38
- - Suggest rebalancing if needed
39
-
40
- ### Style Consistency Prompt
41
-
42
- If new features deviate significantly from detected style:
43
-
44
- ```
45
- "Your new features use avg X words/description, but existing features use Y.
46
- Current ratio: low:M%, medium:N%, high:O%.
47
- Adjust new features to match? (Y/n)"
31
+ ```bash
32
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-NNN
48
33
  ```
49
34
 
50
- Accept user choice, then adjust draft accordingly before JSON generation.
35
+ Do not perform default full-history keyword search.
51
36
 
52
37
  ## Incremental Planning Flow
53
38
 
54
39
  ### Step 1: Clarify Increment Scope
40
+
55
41
  Capture:
56
- - business objective of the new increment
57
- - affected existing modules/features
58
- - timeline or priority constraints
42
+ - business objective of the new increment;
43
+ - affected existing capabilities and current project modules established from project evidence;
44
+ - timeline or priority constraints.
59
45
 
60
46
  ### Step 2: Impact Mapping
47
+
61
48
  For each candidate feature, identify:
62
- - upstream dependencies
63
- - downstream impacts
64
- - risk hotspots (auth, data migration, API compatibility)
49
+ - real upstream prerequisites;
50
+ - downstream impacts;
51
+ - risk hotspots such as auth, data migration, and API compatibility.
65
52
 
66
- ### Step 3: Append Features
67
- Append new items only (do not rewrite old validated features unless user asks).
53
+ Use current project evidence as the primary source. The recent five-task window supplies only the narrow relevance evidence permitted by the gate above.
54
+
55
+ ### Step 3: Draft Additions
56
+
57
+ Draft new items only; do not rewrite old validated features unless the user explicitly requested an old ID operation.
68
58
 
69
59
  For each new feature:
70
- - assign next ID
71
- - set `status: "pending"`
72
- - link dependencies to existing IDs where needed
73
- - keep title in English
74
- - **write rich descriptions** (see `planning-guide.md` §4):
75
- - minimum 15 words (validation error below this)
76
- - recommended minimum: 30+ (low), 50+ (medium), 80+ (high), 100+ (critical) — no upper limit, more detail is always better
77
- - include: what to build, key behaviors, integration points, data model, error/edge cases
60
+ - assign the next sequential ID returned by `context`;
61
+ - omit `status` or set it to `pending`;
62
+ - link dependencies to old IDs only for real execution prerequisites;
63
+ - keep the title in English for stable slug generation;
64
+ - write a self-contained description with objective, current and desired behavior, selected decisions, constraints, non-goals, relevant integrations, edge cases, and completion evidence;
65
+ - add concrete measurable acceptance criteria.
66
+
67
+ The additions-only `.prizmkit/plans/feature-list.draft.json` has exactly one root field:
68
+
69
+ ```json
70
+ {
71
+ "features": [
72
+ {
73
+ "id": "F-NNN",
74
+ "title": "English stable title",
75
+ "description": "Self-contained feature contract",
76
+ "priority": "medium",
77
+ "dependencies": [],
78
+ "acceptance_criteria": ["Concrete measurable result"]
79
+ }
80
+ ]
81
+ }
82
+ ```
83
+
84
+ Each item uses the unchanged final feature-item schema. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional feature fields remain allowed. Root project metadata and historical features must not be copied into this draft.
78
85
 
79
86
  ### Step 4: Rebalance Priority
80
- Allow priority updates for both old and new features if user requests reprioritization.
81
- Keep dependency correctness as first constraint.
82
87
 
83
- ### Step 5: Validate
84
- Write a draft and generate the final list:
88
+ Default to append only. Reprioritizing historical tasks is an explicit old-task modification, not part of ordinary append flow; require the user to identify the affected IDs and load only those tasks with `show`.
89
+
90
+ ### Step 5: Append and Validate
91
+
92
+ Merge the additions-only draft with untouched history outside AI context:
93
+
85
94
  ```bash
86
- python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
95
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
87
96
  ```
88
97
 
89
- Fix and re-run until pass.
98
+ The append command validates the existing base, exact sequential new IDs, all old/new dependencies, and the complete DAG before atomically replacing the final list. Fix the additions draft and rerun until valid. Use `generate` only for an initial plan or an explicit full-list rewrite.
90
99
 
91
100
  ## Merge/Rewrite Rules
92
101
 
93
- - Default: append only
94
- - Rewrite existing features only when user explicitly asks
95
- - Never break valid IDs/references
96
- - Never set new features to `in_progress` or `completed`
102
+ - Default: append only through the additions-only draft.
103
+ - Preserve every historical task and root value unchanged.
104
+ - Rewrite existing features only when the user explicitly identifies them.
105
+ - Never break valid IDs/references.
106
+ - Never set new features to `in_progress` or `completed`.
97
107
 
98
108
  ## Practical Prompts
99
109
 
100
110
  Use concise prompts during interaction:
101
- - "What is the goal of this increment? Which user problem is the priority?"
102
- - "Which existing Feature IDs do these new features depend on?"
103
- - "Do you want to reprioritize at the same time, or just append to the current sequence?"
111
+ - “What is the goal of this increment? Which user problem is the priority?”
112
+ - “Does any of the five recent descriptions represent a real continuation, conflict, shared contract, or prerequisite? If not, no historical content will be carried forward.”
113
+ - “Do you want only an append, or are you explicitly modifying identified historical Feature IDs?”
104
114
 
105
115
  ## Final Delivery Checklist
106
116
 
107
- - [ ] Existing file read before edits
108
- - [ ] New IDs continue sequence
109
- - [ ] Existing style preserved
110
- - [ ] Dependency graph still DAG
111
- - [ ] Validation passes
117
+ - [ ] Bounded `context` command used; complete historical list not loaded
118
+ - [ ] At most five recent `{id, description}` pairs inspected
119
+ - [ ] No historical content added by default
120
+ - [ ] Any incorporated history is minimum, contract-affecting, and task-scoped
121
+ - [ ] Old dependency IDs represent real execution prerequisites
122
+ - [ ] Additions-only draft contains no root metadata or historical features
123
+ - [ ] Existing project conventions preserved from project evidence
124
+ - [ ] Complete merged dependency graph validates through `append`
112
125
  - [ ] Next step recommendation: `feature-pipeline-launcher`
@@ -6,6 +6,9 @@ for the dev-pipeline system.
6
6
  Commands:
7
7
  validate Validate an existing .prizmkit/plans/feature-list.json
8
8
  template Generate a blank template .prizmkit/plans/feature-list.json
9
+ context Print bounded project context plus the five most recent features
10
+ show Print one explicitly requested top-level feature
11
+ append Merge an additions-only draft into an existing validated list
9
12
  generate Validate a draft JSON and generate final feature-list.json with defaults
10
13
  summary Print a summary table of features from a .prizmkit/plans/feature-list.json
11
14
  grade Generate grading results from eval runs (for npm run skill:review)
@@ -13,6 +16,9 @@ Commands:
13
16
  Usage:
14
17
  python3 validate-and-generate.py validate --input .prizmkit/plans/feature-list.json [--output validated.json]
15
18
  python3 validate-and-generate.py template --output .prizmkit/plans/feature-list.json
19
+ python3 validate-and-generate.py context --input .prizmkit/plans/feature-list.json
20
+ python3 validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-001
21
+ python3 validate-and-generate.py append --input additions.json --output .prizmkit/plans/feature-list.json
16
22
  python3 validate-and-generate.py generate --input draft.json --output .prizmkit/plans/feature-list.json
17
23
  python3 validate-and-generate.py summary --input .prizmkit/plans/feature-list.json [--format markdown|json]
18
24
  python3 validate-and-generate.py grade --workspace /.codebuddy/skill-evals/feature-planner-workspace --iteration iteration-1
@@ -26,10 +32,12 @@ Python 3.6+ required. No external dependencies.
26
32
 
27
33
  import argparse
28
34
  import collections
35
+ import copy
29
36
  import json
30
37
  import os
31
38
  import re
32
39
  import sys
40
+ import tempfile
33
41
  from datetime import datetime, timezone
34
42
 
35
43
  # ---------------------------------------------------------------------------
@@ -115,6 +123,25 @@ def _write_json(path, data):
115
123
  fh.write("\n")
116
124
 
117
125
 
126
+ def _write_json_atomic(path, data):
127
+ """Atomically replace *path* with pretty-printed JSON data."""
128
+ parent = os.path.dirname(os.path.abspath(path))
129
+ if parent and not os.path.isdir(parent):
130
+ os.makedirs(parent, exist_ok=True)
131
+ fd, temp_path = tempfile.mkstemp(prefix=".feature-list-", suffix=".tmp", dir=parent)
132
+ try:
133
+ with os.fdopen(fd, "w", encoding="utf-8") as fh:
134
+ json.dump(data, fh, indent=2, ensure_ascii=False)
135
+ fh.write("\n")
136
+ os.replace(temp_path, path)
137
+ except Exception:
138
+ try:
139
+ os.unlink(temp_path)
140
+ except OSError:
141
+ pass
142
+ raise
143
+
144
+
118
145
  # ---------------------------------------------------------------------------
119
146
  # Cycle detection (Kahn's algorithm)
120
147
  # ---------------------------------------------------------------------------
@@ -745,6 +772,148 @@ def cmd_template(args):
745
772
  return 0
746
773
 
747
774
 
775
+ def _load_valid_existing(path):
776
+ """Load and validate one existing feature list."""
777
+ data, load_err = _load_json(path)
778
+ if load_err:
779
+ _err(load_err)
780
+ return None, None, 2
781
+ if not isinstance(data, dict):
782
+ _err("Feature list root must be an object")
783
+ return None, None, 1
784
+
785
+ result = validate_feature_list(data, is_new_plan=False)
786
+ if not result["valid"]:
787
+ _err("Existing feature list is invalid")
788
+ for error in result["errors"]:
789
+ _err(" " + error)
790
+ return None, result, 1
791
+ return data, result, 0
792
+
793
+
794
+ def _next_top_level_id(features):
795
+ """Return the next F-NNN ID, or None when numeric capacity is exhausted."""
796
+ numbers = []
797
+ for feature in features:
798
+ match = FEATURE_ID_RE.match(str(feature.get("id", "")))
799
+ if match:
800
+ numbers.append(int(str(feature["id"])[2:5]))
801
+ next_number = max(numbers, default=0) + 1
802
+ if next_number > 999:
803
+ return None
804
+ return "F-{:03d}".format(next_number)
805
+
806
+
807
+ def cmd_context(args):
808
+ """Print bounded existing-list context for incremental planning."""
809
+ data, _, exit_code = _load_valid_existing(args.input)
810
+ if exit_code:
811
+ return exit_code
812
+
813
+ features = data["features"]
814
+ next_id = _next_top_level_id(features)
815
+ if next_id is None:
816
+ _err("Feature ID capacity exhausted at F-999")
817
+ return 1
818
+
819
+ context = {
820
+ "project_name": data.get("project_name"),
821
+ "project_description": data.get("project_description"),
822
+ "global_context": data.get("global_context") or {},
823
+ "task_count": len(features),
824
+ "next_id": next_id,
825
+ "recent_tasks": [
826
+ {"id": feature.get("id"), "description": feature.get("description")}
827
+ for feature in features[-5:]
828
+ ],
829
+ }
830
+ print(json.dumps(context, indent=2, ensure_ascii=False))
831
+ return 0
832
+
833
+
834
+ def cmd_show(args):
835
+ """Print one explicitly requested top-level feature."""
836
+ data, _, exit_code = _load_valid_existing(args.input)
837
+ if exit_code:
838
+ return exit_code
839
+ if not FEATURE_ID_RE.match(str(args.id)):
840
+ _err("Feature ID '{}' must match F-NNN or F-NNN-X".format(args.id))
841
+ return 1
842
+
843
+ for feature in data["features"]:
844
+ if feature.get("id") == args.id:
845
+ print(json.dumps(feature, indent=2, ensure_ascii=False))
846
+ return 0
847
+ _err("Feature '{}' not found".format(args.id))
848
+ return 1
849
+
850
+
851
+ def cmd_append(args):
852
+ """Append a collection-only draft to an existing validated feature list."""
853
+ base, _, exit_code = _load_valid_existing(args.output)
854
+ if exit_code:
855
+ return exit_code
856
+
857
+ draft, load_err = _load_json(args.input)
858
+ if load_err:
859
+ _err(load_err)
860
+ return 2
861
+ if not isinstance(draft, dict) or set(draft.keys()) != {"features"}:
862
+ _err("Additions draft must be an object containing only 'features'")
863
+ return 1
864
+ additions = draft.get("features")
865
+ if not isinstance(additions, list) or not additions:
866
+ _err("Additions draft 'features' must be a non-empty array")
867
+ return 1
868
+ if not all(isinstance(feature, dict) for feature in additions):
869
+ _err("Every feature addition must be an object")
870
+ return 1
871
+
872
+ merge_base = copy.deepcopy(base)
873
+ if args.replace_tail:
874
+ addition_ids = [feature.get("id") for feature in additions]
875
+ tail_ids = [feature.get("id") for feature in base["features"][-len(additions):]]
876
+ if len(base["features"]) < len(additions) or tail_ids != addition_ids:
877
+ _err("--replace-tail requires additions IDs to match the existing final-list suffix exactly")
878
+ return 1
879
+ merge_base["features"] = merge_base["features"][:-len(additions)]
880
+
881
+ next_id = _next_top_level_id(merge_base["features"])
882
+ if next_id is None:
883
+ _err("Feature ID capacity exhausted at F-999")
884
+ return 1
885
+ start_number = int(next_id[2:])
886
+ prepared = copy.deepcopy(additions)
887
+ for offset, feature in enumerate(prepared):
888
+ expected_id = "F-{:03d}".format(start_number + offset)
889
+ if start_number + offset > 999:
890
+ _err("Feature ID capacity exhausted at F-999")
891
+ return 1
892
+ if feature.get("id") != expected_id:
893
+ _err("Feature addition {} must use next sequential ID '{}'".format(offset, expected_id))
894
+ return 1
895
+ feature.setdefault("status", "pending")
896
+
897
+ merged = copy.deepcopy(merge_base)
898
+ merged["features"].extend(prepared)
899
+ result = validate_feature_list(merged, is_new_plan=False)
900
+ result["appended_ids"] = [feature["id"] for feature in prepared]
901
+ print(json.dumps(result, indent=2, ensure_ascii=False))
902
+ if not result["valid"]:
903
+ _err("Merged feature list validation failed")
904
+ for error in result["errors"]:
905
+ _err(" " + error)
906
+ return 1
907
+
908
+ try:
909
+ _write_json_atomic(args.output, merged)
910
+ except Exception as exc:
911
+ _err("Failed to write merged feature list: {}".format(exc))
912
+ return 2
913
+ _info("Appended {} feature(s) to {}".format(len(prepared), args.output))
914
+ return 0
915
+
916
+
748
917
  def cmd_generate(args):
749
918
  """Handle the 'generate' command.
750
919
 
@@ -943,6 +1112,9 @@ def main():
943
1112
  " %(prog)s validate --input .prizmkit/plans/feature-list.json\n"
944
1113
  " %(prog)s validate --input .prizmkit/plans/feature-list.json --output validated.json\n"
945
1114
  " %(prog)s template --output .prizmkit/plans/feature-list.json\n"
1115
+ " %(prog)s context --input .prizmkit/plans/feature-list.json\n"
1116
+ " %(prog)s show --input .prizmkit/plans/feature-list.json --id F-001\n"
1117
+ " %(prog)s append --input additions.json --output .prizmkit/plans/feature-list.json\n"
946
1118
  " %(prog)s generate --input draft.json --output .prizmkit/plans/feature-list.json\n"
947
1119
  " %(prog)s summary --input .prizmkit/plans/feature-list.json\n"
948
1120
  " %(prog)s summary --input .prizmkit/plans/feature-list.json --format json\n"
@@ -972,6 +1144,44 @@ def main():
972
1144
  "--output", required=True, help="Path to write template file"
973
1145
  )
974
1146
 
1147
+ # -- context --
1148
+ p_context = subparsers.add_parser(
1149
+ "context",
1150
+ help="Print root context and the five most recent feature id/description pairs",
1151
+ )
1152
+ p_context.add_argument(
1153
+ "--input", required=True, help="Path to existing .prizmkit/plans/feature-list.json"
1154
+ )
1155
+
1156
+ # -- show --
1157
+ p_show = subparsers.add_parser(
1158
+ "show",
1159
+ help="Print one explicitly requested top-level feature",
1160
+ )
1161
+ p_show.add_argument(
1162
+ "--input", required=True, help="Path to existing .prizmkit/plans/feature-list.json"
1163
+ )
1164
+ p_show.add_argument(
1165
+ "--id", required=True, help="Exact top-level feature ID"
1166
+ )
1167
+
1168
+ # -- append --
1169
+ p_append = subparsers.add_parser(
1170
+ "append",
1171
+ help="Append a features-only draft to an existing validated feature list",
1172
+ )
1173
+ p_append.add_argument(
1174
+ "--input", required=True, help="Path to additions-only draft JSON"
1175
+ )
1176
+ p_append.add_argument(
1177
+ "--output", required=True, help="Path to existing final feature-list.json"
1178
+ )
1179
+ p_append.add_argument(
1180
+ "--replace-tail",
1181
+ action="store_true",
1182
+ help="Replace the exact existing suffix with the same IDs after local review",
1183
+ )
1184
+
975
1185
  # -- generate --
976
1186
  p_generate = subparsers.add_parser(
977
1187
  "generate",
@@ -1024,6 +1234,9 @@ def main():
1024
1234
  dispatch = {
1025
1235
  "validate": cmd_validate,
1026
1236
  "template": cmd_template,
1237
+ "context": cmd_context,
1238
+ "show": cmd_show,
1239
+ "append": cmd_append,
1027
1240
  "generate": cmd_generate,
1028
1241
  "summary": cmd_summary,
1029
1242
  "grade": cmd_grade,
@@ -20,6 +20,8 @@ Use this Skill for:
20
20
 
21
21
  Do not use it for unrelated application implementation, general server administration, or resources outside the selected environment and its necessary deployment dependencies. If the user says only “ship it” without explicitly invoking this Skill, clarify commit versus deploy; explicit invocation means deploy.
22
22
 
23
+ Deployment verification is Release-and-target convergence, not a generic software-development lifecycle. A caller cannot add hidden planning, review, commit, or exhaustive unit/integration/contract/browser test prerequisites. Run only checks required by the selected project-native deployment/preflight controller or by target-appropriate deployment verification, unless the user separately requests broader development work. A selected immutable worktree Release does not require creating a Git commit.
24
+
23
25
  ## Invocation and Authority
24
26
 
25
27
  ```text
@@ -36,6 +38,8 @@ User intent controls optional confirmation and backup policy for the selected op
36
38
 
37
39
  An explicit no-confirmation instruction satisfies any confirmation or effect decision already identified within the user's established authority; do not ask again. An explicit no-backup instruction creates no new data backup, snapshot, or retained application rollback copy for this operation. Preserve current live only until the desired candidate is proven, then retire exact superseded runtime after handoff. Leave unrelated pre-existing backups untouched unless the user explicitly requests their deletion. These instructions do not invent missing facts, choose whether uncommitted code is deployed, make unknown effects bounded, bypass target identity, or establish ownership the user has not demonstrated.
38
40
 
41
+ Explicit permission to use local SSH credentials authorizes target-scoped use of configured SSH aliases, agent identities, and key files through the installed `ssh` executable. Do not ask whether to use them again. Let SSH consume the credential; do not read, copy, print, upload, or request the private-key value. This permission does not identify a missing destination, accept an unverified or changed host key, or authorize unrelated hosts.
42
+
39
43
  Do not ask for a second complete-plan confirmation for standard actions. Before returning `WAITING_USER`, exhaust bounded read-only discovery, unambiguous target resolution, configured non-interactive authentication, and every safe bounded forward action. Pause only when no safe automatic continuation remains and the next action requires:
40
44
 
41
45
  1. a release-source choice because tracked or untracked worktree changes exist;
@@ -46,6 +50,8 @@ Do not ask for a second complete-plan confirmation for standard actions. Before
46
50
 
47
51
  A missing Profile record, ordinary first deployment, selected-target connection, known bounded downtime, material work inside the standard envelope, or missing rollback mechanism does not create a confirmation. Disclose relevant effects while continuing. Privileged or global work outside the selected environment's established target boundary is an authorization/ownership decision and pauses before execution.
48
52
 
53
+ When SSH still cannot connect after bounded target-scoped discovery and use of authorized local credentials, diagnose the observed failure class before pausing. Report why connection failed, which non-sensitive binding was attempted, and exactly which destination, username, port, proxy/VPN, trusted host-key fingerprint, public-key registration, network rule, SSH service, or remote permission fact must change for future automatic access. Return one connection-enablement action, then retry and perform the server work yourself. Never ask the user to log into the server and run deployment commands on this Skill's behalf.
54
+
49
55
  ## Managed Artifacts
50
56
 
51
57
  Prefer project-native deployment configuration. PrizmKit owns only:
@@ -81,6 +87,8 @@ Read `${SKILL_DIR}/references/fast-path-selection.md` after resolving the operat
81
87
 
82
88
  Products and tools are evidence examples, not protocol identifiers. Existing project-native coordination decides whether multiple units deploy together or independently.
83
89
 
90
+ A cloud server, virtual machine, or directly managed host remains a direct remote-runtime target when project evidence establishes shell access. On that path, use the installed `ssh` executable as the default connection transport. A provider dashboard does not reclassify the machine as repository-hosted deployment. Do not use browser automation or a web terminal as a substitute for SSH to transfer a Release, execute deployment commands, or inspect runtime state. Browser automation is eligible only for an exact authoritative control-plane operation when no project-native command, API, CLI, or SSH path can perform that operation; it never bypasses identity or authentication boundaries.
91
+
84
92
  ## AutoDeploy Workflow
85
93
 
86
94
  ### 1. Resolve Unit and Environment
@@ -166,6 +174,7 @@ Report:
166
174
 
167
175
  - terminal status and operation;
168
176
  - selected environment and target reference, plus the internal Profile record result when one exists;
177
+ - for failed SSH access, the observed failure class, attempted non-sensitive binding, exact missing connection fact or durable server/cloud configuration change, and one retry action;
169
178
  - desired and actual live release;
170
179
  - concise verification observations and residual resources;
171
180
  - rollback availability without treating it as required approval;
@@ -31,7 +31,7 @@ A maintained recipe is reusable only while its project, tool, target, artifact,
31
31
 
32
32
  Select concrete controller guidance through `${SKILL_DIR}/references/fast-path-selection.md` and its matching playbook before deriving a material action. The playbook supplies observed command knowledge; this contract still owns semantic action fields, evidence, effects, Gates, and verification.
33
33
 
34
- For a direct remote target, load `${SKILL_DIR}/references/playbook-remote-runtime.md`. A remote playbook cannot bypass target identity, host-key, authentication, ownership, or unknown-outcome boundaries.
34
+ For a direct remote target, load `${SKILL_DIR}/references/playbook-remote-runtime.md`. When that target exposes shell access, the installed `ssh` executable is the default implementation of semantic `connect`; a browser dashboard or web terminal is not an equivalent transport. Explicit permission to use local SSH credentials resolves the credential-use decision: allow SSH to use the selected target's configured alias, agent, and key files without another question, while never reading or exposing private-key material. Browser automation is considered only for an exact authoritative control-plane operation with no supported project-native command, API, CLI, or SSH path. An SSH authentication failure does not authorize a silent transport change. A remote playbook cannot bypass target identity, host-key, authentication, ownership, or unknown-outcome boundaries.
35
35
 
36
36
  ## Base Action Contract
37
37
 
@@ -56,7 +56,7 @@ Before creating a Human Checkpoint:
56
56
  3. try established non-interactive authentication;
57
57
  4. honor an explicit decision already made for the exact identified effect.
58
58
 
59
- Return one human action only when identity, target, irreversible or unbounded data effect, or shared ownership still requires a person. Missing facts and unproven ownership remain information boundaries because user intent cannot make them known. When no safe action can be established, report the missing evidence or unsupported capability instead of fabricating a command.
59
+ Return one human action only when identity, target, irreversible or unbounded data effect, or shared ownership still requires a person. For failed SSH access, classify the observed resolver, network, host-key, authentication, service, or remote-authorization failure and request only the missing durable connection fact or configuration change; never delegate the deployment commands to the user. Missing facts and unproven ownership remain information boundaries because user intent cannot make them known. When no safe action can be established, report the missing evidence or unsupported capability instead of fabricating a command.
60
60
 
61
61
  Evidence derivation basis such as maintained recipe or current dynamic derivation is internal provenance, not a user-visible deployment status and not a risk classification.
62
62
 
@@ -28,6 +28,12 @@ Select the smallest authoritative controller in this order:
28
28
 
29
29
  The presence of several configuration files does not mean every controller should run. Resolve conflicts through current live state and one bounded read-only observation.
30
30
 
31
+ ## Connection Transport Precedence
32
+
33
+ Controller selection and connection transport are separate decisions. A project-native controller may remain authoritative when it internally owns transport. Otherwise, when a directly managed machine exposes or is configured for shell access, use the installed `ssh` executable and the verified SSH binding as the default transport for observation, transfer, execution, and verification. When the user authorizes local SSH credentials, resolve only the selected target's alias/configuration and let SSH try its configured agent and key files without another permission question; do not enumerate unrelated hosts or reveal key material.
34
+
35
+ A cloud provider dashboard does not make a server a repository-hosted deployment target. Browser automation—for example, a browser-driving test tool—is a last-resort control-plane adapter, not a remote-shell transport. Use it only when the exact authoritative operation has no supported project-native command, API, CLI, or SSH path. Never type deployment commands into a web terminal or upload a Release through a dashboard when an SSH binding exists or can be established. If SSH reaches a user-only authentication boundary, diagnose it and return one exact durable connection-enablement action instead of silently switching to a browser console or asking the user to execute the deployment remotely.
36
+
31
37
  ## Conditional Playbook Loading
32
38
 
33
39
  - project-native controller → `playbook-project-native.md`
@@ -4,9 +4,37 @@ Use this playbook when the selected environment is a directly managed remote mac
4
4
 
5
5
  ## Connection
6
6
 
7
- Use the installed `ssh` executable as the default implementation of semantic `connect` when the target exposes shell access. Derive the destination from an explicit target, project evidence, or an observed/user-supplied SSH config alias. Reuse its user, port, proxy, agent/key, and host-verification settings.
7
+ Use the installed `ssh` executable as the default implementation of semantic `connect` when the target exposes shell access. This includes a cloud server, virtual machine, or directly managed host even when its provider also offers a dashboard. Derive the destination from an explicit target, project evidence, or an observed/user-supplied SSH config alias. Reuse its user, port, proxy, agent/key, and host-verification settings.
8
8
 
9
- Attempt one bounded non-interactive probe before requesting authentication. Do not guess host, user, port, key path, bastion, or fingerprint, and do not bypass host-key verification. Use a project-native controller instead when the target exposes no shell or defines another authoritative path.
9
+ A provider dashboard or browser-accessible terminal does not outrank SSH. Do not use browser automation to type into a web shell, upload the application, execute deployment commands, or inspect ordinary runtime state when the verified SSH binding can perform the operation. Browser automation—for example, a Playwright-driven dashboard—is eligible only for an exact provider control-plane operation that has no supported project-native command, API, CLI, or SSH path.
10
+
11
+ ### Authorized Local Credential Path
12
+
13
+ When the user authorizes local SSH credential use, proceed without another key-use question:
14
+
15
+ 1. Resolve only the selected destination's effective configuration with the installed SSH client, such as `ssh -G <verified-destination>`; do not enumerate unrelated aliases.
16
+ 2. When relevant, inspect only public agent fingerprints through `ssh-add -l`. Let SSH use the configured agent and `IdentityFile` paths; never read, copy, print, or upload private-key contents.
17
+ 3. Attempt one bounded non-interactive probe through the resolved binding, equivalent to `ssh -o BatchMode=yes -o ConnectTimeout=<bounded-seconds> <verified-destination> true`. Preserve ordinary host-key checking and bounded diagnostics.
18
+ 4. Continue immediately through the same binding when the probe succeeds. Do not ask the user to confirm SSH again.
19
+
20
+ Do not guess host, user, port, key path, bastion, or fingerprint, and do not bypass host-key verification. Use a project-native controller instead when the target exposes no shell or defines another authoritative path.
21
+
22
+ ### Connection Failure Diagnosis
23
+
24
+ Diagnose a failed probe before returning `WAITING_USER`:
25
+
26
+ | Observed failure | Durable information or configuration needed |
27
+ |---|---|
28
+ | destination absent or name resolution failed | SSH alias or hostname/IP, login user, port, and any required proxy, bastion, VPN, or private-network route |
29
+ | timeout or no route | reachable address/network path and the cloud security-group or firewall inbound rule for the selected SSH port and trusted source |
30
+ | connection refused | correct SSH port plus an enabled/listening SSH service and non-rejecting host firewall |
31
+ | unknown or changed host key | trusted expected host-key fingerprint, or verified key-rotation evidence before updating local trust |
32
+ | no usable local identity or encrypted key unavailable | target-specific SSH `IdentityFile`/agent configuration or a locally unlocked agent identity; never request the private key or passphrase in chat |
33
+ | public-key authentication denied | correct login user and registration of the matching local public-key fingerprint in the account's authorized-key or cloud-managed SSH-key configuration, with public-key authentication enabled |
34
+ | connected user lacks project access | deploy username, project-owned remote directory, and the minimum durable file/runtime/supervisor permission or bounded privilege policy |
35
+ | target intentionally exposes no shell | the authoritative project-native API, CLI, or controller binding instead of browser-emulated shell access |
36
+
37
+ Return exactly one connection-enablement action containing only the applicable missing facts or configuration changes and the instruction to retry. Explain the observed failure safely, but do not ask the user to log into the server and run deployment commands; after access is enabled, this Skill reconnects and performs those operations itself. Do not switch to a browser console merely because SSH authentication or reachability failed.
10
38
 
11
39
  ## Build, Transfer, and Runtime
12
40
 
@@ -1,6 +1,6 @@
1
1
  # Repository-Hosted Deployment Playbook
2
2
 
3
- Use this playbook when an observed hosting control plane owns build, release, promotion, traffic, or runtime operations and the project contains matching native configuration or binding evidence.
3
+ Use this playbook when an observed hosting control plane owns build, release, promotion, traffic, or runtime operations and the project contains matching native configuration or binding evidence. A cloud server or virtual machine does not match merely because its provider has a web dashboard; when the project directly owns the machine and shell access is established, use the remote-runtime playbook and SSH.
4
4
 
5
5
  ## Discovery
6
6
 
@@ -10,7 +10,7 @@ An explicit deploy invocation authorizes the selected Profile's standard deploym
10
10
 
11
11
  The standard envelope covers project-owned, bounded actions needed to build/package, resolve project-declared dependencies, apply non-destructive native migrations, create a candidate, start/restart, hand off live traffic, verify, retain bounded rollback when not explicitly declined, retire exact old runtime resources, clean failed/temporary resources, and update the selected Profile record.
12
12
 
13
- For a selected directly managed remote machine, connecting and running bounded project-scoped actions through the established SSH destination are part of that standard envelope. Do not ask for another confirmation merely because the next executable is `ssh`; use established non-interactive credentials first. A missing Profile record or ordinary first deployment also does not create a checkpoint when one non-conflicting target resolves from current evidence.
13
+ For a selected directly managed remote machine, connecting and running bounded project-scoped actions through the established SSH destination are part of that standard envelope. Do not ask for another confirmation merely because the next executable is `ssh`; use established non-interactive credentials first. Explicit permission to use local SSH credentials authorizes the installed SSH client to consume the selected target's configured alias, agent, and key files without another question, but never authorizes reading or exposing private-key values. A missing Profile record or ordinary first deployment also does not create a checkpoint when one non-conflicting target resolves from current evidence.
14
14
 
15
15
  ### User Intent and Fast Completion
16
16
 
@@ -51,7 +51,9 @@ Do not run a material producer when current project-native evidence already cove
51
51
 
52
52
  For each selected SSH action, preserve the verified destination, authentication identity, proxy path, host-key evidence, and project-owned working boundary used during discovery. Execute the smallest exact remote command needed for the current difference, with bounded connection/action time and output. Reuse one proven connection binding across observation, transfer, write, and verification instead of silently changing users or endpoints between steps.
53
53
 
54
- Do not pass Secret values in command arguments, print private-key material, start a broad remote inventory, or bypass host-key verification. Attempt one bounded non-interactive connection with the established SSH configuration before deciding authentication cannot complete; continue immediately when it succeeds. Only then return one exact `WAITING_USER` authentication action when user input is unavoidable. If the target key or destination differs from established evidence, treat it as an identity conflict rather than a transient retry. After a disconnect during a possible write, use the same verified SSH destination to inspect actual state before considering replay.
54
+ When local credential use is authorized, perform target-scoped discovery through the SSH client: resolve the selected destination's effective configuration, inspect available agent public-key fingerprints when relevant, and let SSH select its configured key files. Do not open private-key files to obtain their contents, enumerate unrelated host aliases or keys, or print local credential paths in the result.
55
+
56
+ Do not pass Secret values in command arguments, print private-key material, start a broad remote inventory, or bypass host-key verification. Attempt one bounded non-interactive connection with the established SSH configuration before deciding authentication cannot complete; continue immediately when it succeeds. If it fails, preserve bounded safe diagnostics and classify whether the cause is unresolved destination, name resolution, timeout/no route, connection refusal, host-key trust/conflict, unavailable local key/agent, public-key denial, SSH service policy, or connected-user authorization. Only then return one exact `WAITING_USER` connection-enablement action when user input is unavoidable. State the exact missing server fact or cloud/server configuration change needed for durable automatic access, then retry and perform the server work through SSH; never ask the user to log in and run deployment commands. If the target key or destination differs from established evidence, treat it as an identity conflict rather than a transient retry. After a disconnect during a possible write, use the same verified SSH destination to inspect actual state before considering replay.
55
57
 
56
58
  ## Current → Desired Loop
57
59