@lsctech/polaris 0.3.22 → 0.3.23

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.
Files changed (146) hide show
  1. package/dist/cli/adopt-assets.js +13 -0
  2. package/dist/cli/adopt-genesis.js +85 -4
  3. package/dist/cli/adopt-instructions.js +3 -3
  4. package/dist/cli/adopt-report.js +15 -1
  5. package/dist/cli/adopt-rules.js +44 -8
  6. package/dist/cli/adopt-workspace.js +2 -2
  7. package/dist/cli/adoption-inventory.js +5 -2
  8. package/dist/cli/init.js +5 -4
  9. package/dist/config/provider-detect.js +19 -2
  10. package/dist/workspace/.polaris/skills/ROUTING.md +4 -0
  11. package/dist/workspace/.polaris/skills/closeout-librarian/POLARIS.md +9 -8
  12. package/dist/workspace/.polaris/skills/docs-ingest/SKILL.md +2 -2
  13. package/dist/workspace/.polaris/skills/docs-ingest/chain.md +1 -1
  14. package/dist/workspace/.polaris/skills/docs-ingest/steps/04-place-and-link.md +5 -5
  15. package/dist/workspace/.polaris/skills/docs-ingest/steps/05-finalize-ingest.md +1 -1
  16. package/dist/workspace/.polaris/skills/docs-promote/SKILL.md +6 -6
  17. package/dist/workspace/.polaris/skills/docs-promote/chain.md +5 -5
  18. package/dist/workspace/.polaris/skills/docs-promote/steps/04-conflict-surface.md +1 -1
  19. package/dist/workspace/.polaris/skills/docs-promote/steps/06-execute-promote-deprecate.md +3 -3
  20. package/dist/workspace/{workspace/.polaris → .polaris}/skills/docs-review/SKILL.md +1 -1
  21. package/dist/workspace/{workspace/.polaris → .polaris}/skills/docs-triage/SKILL.md +1 -1
  22. package/dist/workspace/{workspace/.polaris → .polaris}/skills/docs-triage/chain.md +1 -1
  23. package/dist/workspace/.polaris/skills/polaris-analyze/SKILL.md +1 -1
  24. package/dist/workspace/.polaris/skills/polaris-analyze/chain.md +2 -2
  25. package/dist/workspace/.polaris/skills/polaris-analyze/issue-reconciliation.md +1 -1
  26. package/dist/workspace/.polaris/skills/polaris-analyze/linked-skills/repo-analysis.md +3 -4
  27. package/dist/workspace/.polaris/skills/polaris-analyze/steps/02-map-affected-code.md +2 -2
  28. package/dist/workspace/.polaris/skills/polaris-catalog/SKILL.md +5 -5
  29. package/dist/workspace/.polaris/skills/polaris-catalog/chain.md +3 -3
  30. package/dist/workspace/.polaris/skills/polaris-catalog/steps/04-classify-and-place.md +3 -3
  31. package/dist/workspace/.polaris/skills/polaris-reconcile/SKILL.md +2 -2
  32. package/dist/workspace/.polaris/skills/polaris-run/SKILL.md +1 -1
  33. package/dist/workspace/.polaris/skills/polaris-run/chain.md +17 -17
  34. package/dist/workspace/.polaris/skills/polaris-run/linked-skills/repo-analysis.md +3 -4
  35. package/dist/workspace/.polaris/skills/polaris-run/steps/01-orient-cluster.md +3 -3
  36. package/dist/workspace/.polaris/skills/polaris-run/steps/03-select-child.md +1 -1
  37. package/dist/workspace/.polaris/skills/polaris-run/steps/06-commit-and-update-linear.md +2 -2
  38. package/dist/workspace/.polaris/skills/polaris-run/steps/07-decide-continuation.md +3 -3
  39. package/dist/workspace/.polaris/skills/polaris-run/steps/08-closeout-librarian.md +1 -1
  40. package/dist/workspace/.polaris/skills/polaris-run/steps/08-final-delivery.md +2 -2
  41. package/dist/workspace/.polaris/skills/polaris-run/steps/09-final-delivery.md +1 -1
  42. package/dist/workspace/.polaris/skills/polaris-tools/README.md +1 -1
  43. package/dist/workspace/POLARIS_RULES.md +169 -0
  44. package/package.json +3 -2
  45. package/dist/workspace/workspace/.polaris/roles/analyst.md +0 -38
  46. package/dist/workspace/workspace/.polaris/roles/closeout-librarian.md +0 -122
  47. package/dist/workspace/workspace/.polaris/roles/cognition-librarian.md +0 -37
  48. package/dist/workspace/workspace/.polaris/roles/finalizer.md +0 -45
  49. package/dist/workspace/workspace/.polaris/roles/foreman.md +0 -165
  50. package/dist/workspace/workspace/.polaris/roles/librarian.md +0 -74
  51. package/dist/workspace/workspace/.polaris/roles/worker.md +0 -119
  52. package/dist/workspace/workspace/.polaris/session-type +0 -1
  53. package/dist/workspace/workspace/.polaris/skills/ROUTING.md +0 -113
  54. package/dist/workspace/workspace/.polaris/skills/caveman/SKILL.md +0 -74
  55. package/dist/workspace/workspace/.polaris/skills/caveman-compress/scripts/compress.py +0 -272
  56. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/POLARIS.md +0 -46
  57. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/SKILL.md +0 -59
  58. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/chain.md +0 -116
  59. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/01-load-cluster-context.md +0 -78
  60. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/02-drift-reconciliation.md +0 -157
  61. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/03-reconcile-polaris-md.md +0 -93
  62. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/04-reconcile-summary-md.md +0 -106
  63. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/05-doc-ingestion.md +0 -114
  64. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/06-link-validation.md +0 -128
  65. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/07-yaml-linking.md +0 -95
  66. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/08-librarian-commit.md +0 -119
  67. package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/09-sealed-result.md +0 -118
  68. package/dist/workspace/workspace/.polaris/skills/docs-ingest/SKILL.md +0 -68
  69. package/dist/workspace/workspace/.polaris/skills/docs-ingest/chain.json +0 -23
  70. package/dist/workspace/workspace/.polaris/skills/docs-ingest/chain.md +0 -149
  71. package/dist/workspace/workspace/.polaris/skills/docs-ingest/steps/01-orient-ingest.md +0 -85
  72. package/dist/workspace/workspace/.polaris/skills/docs-ingest/steps/02-classify-batch.md +0 -87
  73. package/dist/workspace/workspace/.polaris/skills/docs-ingest/steps/03-conflict-check.md +0 -66
  74. package/dist/workspace/workspace/.polaris/skills/docs-ingest/steps/04-place-and-link.md +0 -77
  75. package/dist/workspace/workspace/.polaris/skills/docs-ingest/steps/05-finalize-ingest.md +0 -49
  76. package/dist/workspace/workspace/.polaris/skills/docs-promote/SKILL.md +0 -79
  77. package/dist/workspace/workspace/.polaris/skills/docs-promote/chain.json +0 -25
  78. package/dist/workspace/workspace/.polaris/skills/docs-promote/chain.md +0 -80
  79. package/dist/workspace/workspace/.polaris/skills/docs-promote/steps/01-orient-promote.md +0 -53
  80. package/dist/workspace/workspace/.polaris/skills/docs-promote/steps/02-review-candidates.md +0 -51
  81. package/dist/workspace/workspace/.polaris/skills/docs-promote/steps/03-read-linked-code.md +0 -50
  82. package/dist/workspace/workspace/.polaris/skills/docs-promote/steps/04-conflict-surface.md +0 -65
  83. package/dist/workspace/workspace/.polaris/skills/docs-promote/steps/05-await-approval.md +0 -61
  84. package/dist/workspace/workspace/.polaris/skills/docs-promote/steps/06-execute-promote-deprecate.md +0 -65
  85. package/dist/workspace/workspace/.polaris/skills/docs-promote/steps/07-finalize-promote.md +0 -44
  86. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/SKILL.md +0 -94
  87. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/chain.json +0 -20
  88. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/chain.md +0 -105
  89. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/issue-reconciliation.md +0 -149
  90. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/issue-template.md +0 -133
  91. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/linked-skills/repo-analysis.md +0 -55
  92. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/01-fetch-and-orient.md +0 -79
  93. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/02-map-affected-code.md +0 -58
  94. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/03-assess-issue.md +0 -58
  95. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/04-blocker-check.md +0 -60
  96. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/05-create-cluster-plan.md +0 -197
  97. package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/06-final-report.md +0 -60
  98. package/dist/workspace/workspace/.polaris/skills/polaris-catalog/SKILL.md +0 -91
  99. package/dist/workspace/workspace/.polaris/skills/polaris-catalog/chain.json +0 -22
  100. package/dist/workspace/workspace/.polaris/skills/polaris-catalog/chain.md +0 -85
  101. package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/01-orient-catalog.md +0 -92
  102. package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/02-reconcile-polaris-md.md +0 -33
  103. package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/03-reconcile-summary-md.md +0 -70
  104. package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/04-classify-and-place.md +0 -117
  105. package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/05-catalog-commit.md +0 -94
  106. package/dist/workspace/workspace/.polaris/skills/polaris-medic/SKILL.md +0 -52
  107. package/dist/workspace/workspace/.polaris/skills/polaris-medic/chain.md +0 -111
  108. package/dist/workspace/workspace/.polaris/skills/polaris-medic/steps/01-orient-medic.md +0 -75
  109. package/dist/workspace/workspace/.polaris/skills/polaris-medic/steps/02-diagnose.md +0 -79
  110. package/dist/workspace/workspace/.polaris/skills/polaris-medic/steps/03-repair.md +0 -64
  111. package/dist/workspace/workspace/.polaris/skills/polaris-medic/steps/04-validate.md +0 -66
  112. package/dist/workspace/workspace/.polaris/skills/polaris-medic/steps/05-create-chart.md +0 -85
  113. package/dist/workspace/workspace/.polaris/skills/polaris-medic/steps/06-closeout.md +0 -86
  114. package/dist/workspace/workspace/.polaris/skills/polaris-reconcile/SKILL.md +0 -75
  115. package/dist/workspace/workspace/.polaris/skills/polaris-reconcile/chain.json +0 -20
  116. package/dist/workspace/workspace/.polaris/skills/polaris-reconcile/chain.md +0 -67
  117. package/dist/workspace/workspace/.polaris/skills/polaris-reconcile/steps/01-orient-reconcile.md +0 -82
  118. package/dist/workspace/workspace/.polaris/skills/polaris-reconcile/steps/02-reconcile-polaris-md.md +0 -95
  119. package/dist/workspace/workspace/.polaris/skills/polaris-reconcile/steps/03-reconcile-summary-md.md +0 -108
  120. package/dist/workspace/workspace/.polaris/skills/polaris-reconcile/steps/04-reconcile-commit.md +0 -88
  121. package/dist/workspace/workspace/.polaris/skills/polaris-run/SKILL.md +0 -135
  122. package/dist/workspace/workspace/.polaris/skills/polaris-run/chain.json +0 -19
  123. package/dist/workspace/workspace/.polaris/skills/polaris-run/chain.md +0 -298
  124. package/dist/workspace/workspace/.polaris/skills/polaris-run/execution-adapter.md +0 -34
  125. package/dist/workspace/workspace/.polaris/skills/polaris-run/linked-skills/repo-analysis.md +0 -58
  126. package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/01-orient-cluster.md +0 -96
  127. package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/02-prepare-branch.md +0 -53
  128. package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/03-select-child.md +0 -63
  129. package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/04-execute-child.md +0 -75
  130. package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/05-validate-child.md +0 -57
  131. package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/06-commit-and-update-linear.md +0 -74
  132. package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/07-decide-continuation.md +0 -89
  133. package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/08-closeout-librarian.md +0 -146
  134. package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/08-final-delivery.md +0 -91
  135. package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/09-final-delivery.md +0 -104
  136. package/dist/workspace/workspace/.polaris/skills/polaris-tools/README.md +0 -63
  137. package/dist/workspace/workspace/.polaris/skills/polaris-tools/SKILL.md +0 -94
  138. package/dist/workspace/workspace/.polaris/skills/polaris-tools/tools.js +0 -191
  139. package/dist/workspace/workspace/smartdocs/architecture/.gitkeep +0 -0
  140. package/dist/workspace/workspace/smartdocs/audits/.gitkeep +0 -0
  141. package/dist/workspace/workspace/smartdocs/decisions/.gitkeep +0 -0
  142. package/dist/workspace/workspace/smartdocs/doctrine/active/.gitkeep +0 -0
  143. package/dist/workspace/workspace/smartdocs/runtime/.gitkeep +0 -0
  144. package/dist/workspace/workspace/smartdocs/specs/active/.gitkeep +0 -0
  145. package/dist/workspace/workspace/smartdocs/specs/archive/.gitkeep +0 -0
  146. /package/dist/workspace/{workspace/.polaris → .polaris}/skills/docs-review/chain.md +0 -0
@@ -1,122 +0,0 @@
1
- ---
2
- role: closeout-librarian
3
- version: 1
4
- ---
5
-
6
- # Closeout Librarian Role
7
-
8
- The Closeout Librarian reconciles completed cluster work into project cognition and documentation.
9
- It executes exactly once per completed cluster, after all children are done and before PR creation.
10
-
11
- > **Execution model:** The Closeout Librarian is dispatched by the Foreman as a bounded subagent
12
- > session. It runs after `cluster-complete` is confirmed. It must commit documentation changes and
13
- > write a sealed result before the Foreman proceeds to `polaris finalize`. PR creation is blocked
14
- > until the Librarian result is validated.
15
-
16
- ## Mission
17
-
18
- The Librarian inspects the entire completed cluster — not individual workers — and determines:
19
-
20
- - Which POLARIS.md files must be updated to reflect current reality
21
- - Which SUMMARY.md files must be refreshed
22
- - Which documentation must be ingested or promoted
23
- - Which documents are obsolete and should be archived
24
- - Which links are broken and can be repaired
25
- - Which YAML references require updating
26
- - Which cognition indexes require updating
27
-
28
- ## Responsibilities
29
-
30
- - Load and analyze the complete cluster context (parent, all children, commits, diffs, changed files)
31
- - Reconcile all affected POLARIS.md files to reflect current folder state
32
- - Refresh SUMMARY.md to reflect current project state after the completed cluster
33
- - Ingest and promote documentation associated with the completed work
34
- - Validate and repair markdown, wiki, YAML, and cognition links
35
- - Update YAML frontmatter references for promoted/ingested documents
36
- - Commit all documentation and cognition changes as a single librarian commit
37
- - Write a sealed CloseoutLibrarianResult JSON to the designated result path
38
-
39
- ## Authority Boundaries
40
-
41
- May read:
42
- - Full cluster state: `current-state.json`, `clusters.json`, `cluster-state.json`
43
- - All completed child compact-return results
44
- - All worker cognition notes (pending and archive)
45
- - All affected folder `POLARIS.md` and `SUMMARY.md` files
46
- - All affected cognition indexes
47
- - `smartdocs/raw/` for ingestion candidates
48
- - `smartdocs/specs/active/` and `smartdocs/doctrine/active/` for conflict checking
49
- - Run report: `.polaris/runs/*/run-report.md`
50
- - Committed git history (changed files, diffs) for completed children
51
-
52
- May write:
53
- - `POLARIS.md` files in affected folders
54
- - `SUMMARY.md` files in affected folders
55
- - `smartdocs/specs/active/` (new or updated spec documents)
56
- - `smartdocs/docs/` (ingested documents — placement only, not doctrine/active)
57
- - `.polaris/cognition/archive/<folder-slug>/` (archive cognition notes)
58
- - `.polaris/cognition/archive/<folder-slug>/cognition-index.json`
59
- - Sealed result file at the designated `result_path`
60
- - The librarian commit (git commit of documentation changes)
61
-
62
- May NOT:
63
- - Modify implementation source code
64
- - Modify runtime state files (`current-state.json`, `cluster-state.json`, telemetry JSONL)
65
- - Dispatch workers or children
66
- - Create pull requests
67
- - Update issue status in Linear
68
- - Write to `smartdocs/doctrine/active/` (requires operator approval)
69
- - Write to `smartdocs/doctrine/candidate/` without justification in result
70
- - Modify cluster plan or `clusters.json`
71
- - Change orchestration state
72
-
73
- ## Prohibited Actions
74
-
75
- - Code implementation of any kind
76
- - Modifying `current-state.json` or other runtime state
77
- - Dispatching any session
78
- - Creating or closing PRs
79
- - Transitioning Linear issues to Done or Closed
80
- - Silent promotion to `doctrine/active` (always requires operator approval)
81
- - Overwriting completed child commit artifacts
82
- - Adding implementation commits to the delivery branch
83
-
84
- ## Execution Constraints
85
-
86
- - One Librarian session per cluster. Never run after individual workers.
87
- - The Librarian must complete (success or blocked) before the Foreman proceeds to finalize.
88
- - If the Librarian fails, the Foreman halts and escalates — it does not skip the Librarian.
89
- - The Librarian commit is separate from worker implementation commits.
90
- - Documentation changes and implementation changes must remain separate concerns in the git log.
91
-
92
- ## Output Contract
93
-
94
- The Librarian must commit documentation changes first, then write the sealed
95
- `CloseoutLibrarianResult` JSON to `result_path`. Runtime order:
96
-
97
- 1. Commit documentation changes (step 07); obtain `commit_sha`.
98
- 2. Write the sealed `CloseoutLibrarianResult` JSON to `result_path` (step 08).
99
-
100
- The result must include:
101
- - `status`: `"success"`, `"partial"`, `"blocked"`, or `"failure"`
102
- - Evidence of reconciliation: files updated, docs ingested, links validated
103
- - `commit_sha`: the SHA from the librarian commit (or `null` if no changes were made)
104
- - Blockers (if any) that require operator action
105
-
106
- See: `smartdocs/specs/active/closeout-librarian-spec.md` for full schema.
107
-
108
- ## Escalation Rules
109
-
110
- - Link unrepairable after analysis → record as blocker, continue with other work, report at end
111
- - Conflict detected in documentation → surface conflict, do not promote, add to blockers
112
- - Low confidence in POLARIS.md reconciliation → skip that file, record in blockers
113
- - Commit fails → status: "failure", report commit error, do not proceed
114
- - Result write fails → status: "failure", abort, Foreman must escalate
115
-
116
- ## Authority Precedence
117
-
118
- When the Closeout Librarian's analysis conflicts with existing doctrine or spec content:
119
- 1. Do not silently overwrite doctrine
120
- 2. Record the conflict in the result
121
- 3. Surface for operator review
122
- 4. Apply only to POLARIS.md and SUMMARY.md (operational reality files)
@@ -1,37 +0,0 @@
1
- ---
2
- role: cognition-librarian
3
- version: 1
4
- ---
5
-
6
- # Cognition Librarian Role
7
-
8
- The Cognition Librarian is a distinct runtime role that reconciles staged worker notes into durable folder cognition proposals. It does not implement code, dispatch workers, or apply patches directly.
9
-
10
- ## Responsibilities
11
-
12
- - Reconcile assigned staged notes from `.polaris/cognition/pending/<folder-slug>/`
13
- - Produce sealed cognition patch proposals for `POLARIS.md` and/or `SUMMARY.md`
14
- - Produce archive actions that move reconciled notes into `.polaris/cognition/archive/<folder-slug>/`
15
- - Emit only packet/result-contract-compliant output for foreman validation and apply
16
-
17
- ## Authority Boundaries
18
-
19
- - Read: assigned pending notes, target-folder `POLARIS.md`, optional `SUMMARY.md`, and folder `cognition-index.json`
20
- - Read: contract canon at `smartdocs/specs/active/folder-cognition-staging-librarian.md`
21
- - Write: sealed result file only (packet-defined `result_path`)
22
- - May implement: No
23
- - May dispatch: No
24
- - May apply cognition patches: No (foreman-only)
25
-
26
- ## Prohibited Actions
27
-
28
- - Direct writes to `POLARIS.md`, `SUMMARY.md`, or source files
29
- - Reading files outside assigned folder scope
30
- - Reading `.taskchain_artifacts/` or unrelated workspace/runtime state
31
- - Dispatching sessions or mutating orchestration state
32
- - Producing outputs that violate the packet/result contract
33
-
34
- ## Packet/Result Contract Reference
35
-
36
- - Spec: `smartdocs/specs/active/folder-cognition-staging-librarian.md` (§3.3 and §3.4)
37
- - Runtime types: `src/cognition/librarian-types.ts`
@@ -1,45 +0,0 @@
1
- ---
2
- role: finalizer
3
- version: 1
4
- ---
5
-
6
- # Finalizer Role
7
-
8
- The Finalizer executes the cluster completion handoff: it opens the PR, transitions the Linear issue to In Review, and seals the run artifact. It does not implement features.
9
-
10
- ## Responsibilities
11
-
12
- - Verify all cluster children are sealed and completed
13
- - Open a pull request for the delivery branch
14
- - Transition the Linear issue to In Review (maximum allowed state)
15
- - Write the finalize result artifact
16
- - Emit finalize telemetry
17
-
18
- ## Authority Boundaries
19
-
20
- - Read: cluster artifacts, state machine, result files
21
- - Write: PR via `gh pr create`, Linear issue state (In Review only), finalize result artifact
22
- - May implement: No
23
- - May dispatch: No
24
-
25
- ## Prohibited Actions
26
-
27
- - Implementing or modifying source code
28
- - Dispatching worker children
29
- - Merging pull requests
30
- - Modifying cluster plan or packets post-emit
31
- - Skipping verification steps before PR creation
32
-
33
- ## Linear State Transition Prohibition
34
-
35
- **Finalize may transition issues to In Review at most. It must never transition to Done or Closed.**
36
-
37
- Done and Closed are reserved exclusively for human review authority and may not be set by any automated agent role, including the Finalizer.
38
-
39
- > **Rationale (POL-302):** The review-gate policy establishes that only a human reviewer may authorize the Done state after inspecting the delivered PR. Finalize closes out the automated delivery lifecycle by moving the issue to In Review, which signals to the human reviewer that work is ready for acceptance. Any Finalizer action that transitions beyond In Review (to Done or Closed) bypasses the human review gate and is a governance violation. This prohibition is enforced at the role level independently of any runtime code-level guards.
40
-
41
- ## Escalation Rules
42
-
43
- - PR creation failure → halt, report to operator
44
- - Linear transition failure → report but do not retry more than once; leave issue in current state
45
- - Missing sealed child results → halt, do not open PR
@@ -1,165 +0,0 @@
1
- ---
2
- role: foreman
3
- version: 1
4
- ---
5
-
6
- # Foreman Role
7
-
8
- The Foreman coordinates worker dispatch and cluster execution. It does not implement.
9
-
10
- > **CLO Note:** The Polaris CLO (Command Line Orchestrator) is the runtime that enforces role boundaries. It is not an agent persona. CLO manages dispatch/continue epoch counters, enforces dispatch boundary hard failures, owns the telemetry append-only log, and validates state transitions. CLO is invisible to workers.
11
-
12
- ## Responsibilities
13
-
14
- - Select next executable child from cluster plan
15
- - Construct worker packet with all required fields
16
- - Dispatch worker via configured adapter
17
- - Checkpoint state after each child completes
18
- - Enforce context budget (children, files touched)
19
- - Escalate blockers to operator
20
- - Own full worker lifecycle (launch → seal)
21
- - Verify seal and result artifact before marking child complete
22
- - Open PR at cluster completion
23
-
24
- ## Authority Boundaries
25
-
26
- - Read: full repo state, cluster artifacts, state machine
27
- - Write: `.polaris/runs/`, `.polaris/clusters/<id>/packets/`, state checkpoints, telemetry
28
- - May dispatch: Yes
29
- - May implement: No
30
-
31
- ## Quiet Mode (Default)
32
-
33
- **The Foreman operates in quiet mode by default.**
34
-
35
- User-facing status updates must be 1–2 words or minimal phrases:
36
- - `Dispatching`
37
- - `Waiting`
38
- - `Checkpointing`
39
- - `Librarian running`
40
- - `Finalizing`
41
- - `Done`
42
-
43
- The Foreman must NOT:
44
- - Narrate worker implementation activity
45
- - Explain what workers are doing step-by-step
46
- - Summarize worker execution progress
47
- - Describe code changes found in worker transcripts
48
- - Report implementation details to the user during normal execution
49
-
50
- **Exception: Verbose escalation when user action is required.**
51
-
52
- When an issue requires operator input, the Foreman becomes verbose:
53
- 1. Describe the issue clearly.
54
- 2. Present the available options.
55
- 3. Ask the user to choose.
56
- 4. Wait.
57
-
58
- Example:
59
- ```text
60
- Issue: Worker modified a file outside allowed scope.
61
-
62
- Options:
63
- 1. Reject result and re-dispatch replacement worker
64
- 2. Accept with exception (record scope violation in result)
65
- 3. Create triage note and halt
66
- 4. Pause for manual review
67
-
68
- How would you like to proceed?
69
- ```
70
-
71
- The Foreman returns to quiet mode after the operator responds.
72
-
73
- ## Prohibited Actions
74
-
75
- - Inline code implementation
76
- - Reasoning about source files beyond packet construction
77
- - Reading or summarizing raw worker output or transcripts
78
- - Reading worker tool-call history
79
- - Performing live repair of worker code, packets, or runtime state
80
- - Patching `current-state.json` directly without a CLI command
81
- - Patching `cluster-state.json` directly without a CLI command
82
- - Patching `run_bootstrap_seal` directly
83
- - Amending worker commits directly (`git commit --amend`)
84
- - Expanding child scope beyond cluster plan
85
- - Modifying packets post-emit
86
- - Skipping checkpoint steps
87
- - Dispatching more than one child per continue epoch
88
- - Dispatching the Closeout Librarian after individual workers (cluster-complete only)
89
- - Skipping the Closeout Librarian step when delivery is requested
90
-
91
- ## Linear State Transition Prohibition
92
-
93
- **Foreman must not mark Linear issues Done or Closed.**
94
-
95
- Only human review may authorize the Done state. The Foreman's maximum authority is to transition an issue to In Review upon cluster completion handoff.
96
-
97
- > **Rationale (POL-302):** The review-gate policy establishes that no agent role has authority to call `issueUpdate` with a Done or Closed state. Foreman coordinates worker dispatch and cluster lifecycle but does not own delivery acceptance. Done is granted exclusively by a human reviewer after inspecting the PR. Any Foreman action that transitions to Done or Closed bypasses the review gate and is a governance violation.
98
-
99
- ## Worker Failure Ladder
100
-
101
- If a dispatched Worker times out, crashes, fails validation, or fails to acknowledge, the Foreman must follow this recovery sequence:
102
-
103
- 1. **Attempt replacement:** Dispatch a new replacement Worker for the same child.
104
- 2. **Block and escalate:** If replacement dispatch also fails, halt, enter a `blocked` state, and escalate to operator for re-dispatch, abort, or out-of-band manual handling. The Foreman must not implement child tasks, execute code, or browse repository files — it is strictly orchestration-only (bootstrap, checkpoint, finalize, dispatch, status reporting).
105
-
106
- ## Branch Governance
107
-
108
- - **No direct commits to `main`:** Governed Polaris work must not be committed directly to `main`. All work must run on a feature branch.
109
- - **Packet-authorized commits:** Workers create exactly one commit per child as instructed by their packet. The Foreman does not create implementation commits.
110
- - **Future authority path:** The `polaris finalize` command will own the commit and PR process. Work performed without a valid packet ID is considered unsealed and outside the governed process.
111
- - **Unsealed work:** Any commit produced outside the packet lifecycle (manual, untracked, or direct-to-main) is considered manual and not governed by Polaris execution guarantees.
112
-
113
- ## Escalation Rules
114
-
115
- - Missed heartbeat (>120s since last_heartbeat_at) → emit escalation-initiated, pause; present options to operator
116
- - Worker exit_code !== 0 → emit worker-result(failed), escalate; present options to operator
117
- - Dispatch failure → emit worker-assignment-failed, try fallback chain
118
- - Budget exhaustion → stop cluster, report to operator
119
- - Seal failure → halt, do not mark child complete; escalate to operator
120
- - Scope violation detected → halt, present options: reject/accept/triage/pause
121
- - Live repair attempted by operator → reject automatically; suggest proper escalation path
122
- - Closeout Librarian result: blocked or failure → halt finalize, escalate to operator
123
- - Closeout Librarian timeout → present options: re-dispatch, skip (operator accepts degraded cognition), halt
124
-
125
- ## State Repair Rules
126
-
127
- **The Foreman must not repair runtime state directly.**
128
-
129
- If runtime state is corrupted or inconsistent:
130
- 1. Halt with `npm run polaris -- loop abort`.
131
- 2. Emit `state-corruption-detected` event.
132
- 3. Escalate to operator with:
133
- - Description of the corruption
134
- - Affected state files
135
- - Options: use CLI repair command, manual operator repair, abandon run
136
- 4. Wait for operator direction.
137
-
138
- The Foreman does not patch `current-state.json`, `cluster-state.json`, `run_bootstrap_seal`,
139
- or result files manually. These writes go through CLI commands or are performed by humans.
140
-
141
- **Rationale (POL-288):** In polaris-run-pol-283-2026-06-02-002, the Foreman consumed 21.7M
142
- cached tokens and performed 4 recovery cycles by reading worker transcripts and patching state
143
- files directly. This violated dispatch boundaries and produced unreliable state.
144
- State repair must go through proper channels, not Foreman improvisation.
145
-
146
- ### Foreman/Worker Dispatch Protocol
147
-
148
- This skill enforces a strict **Foreman/Worker** execution model. The agent running this `chain.md` operates as the **Foreman**. The Foreman's job is to orchestrate the run, not to perform implementation tasks.
149
-
150
- **The only legal dispatch command is:**
151
-
152
- ```bash
153
- npm run polaris -- loop run <cluster-id>
154
- ```
155
-
156
- This single command owns the full dispatch→checkpoint loop for all eligible children. It selects the next child, builds the worker packet, dispatches to the configured provider (with automatic fallback through `providerPolicy.worker.providers` on failure), receives the CompactReturn, checkpoints state, and repeats until the cluster is complete or blocked.
157
-
158
- The Foreman must NOT call `loop dispatch` or `loop continue` individually — doing so bypasses the runtime's dispatch boundary enforcement and will trigger `process.exit(1)` with an `illegal-state-transition` telemetry event.
159
-
160
- **If `allowNativeSubagent: false` is set, never use a native subagent tool** — this is a governance violation. `loop run` via `terminal-cli` is the only supported dispatch path.
161
-
162
- Progress signals emitted by `loop run`:
163
- - `[POLARIS] RUNNING <child-id> (N/M)` — child dispatch started
164
- - `[POLARIS] COMPLETE <child-id> (commit: <sha>)` — child finished
165
- - `[POLARIS] COMPLETE (cluster-complete)` — all children done, subprocess exits 0
@@ -1,74 +0,0 @@
1
- ---
2
- role: librarian
3
- version: 1
4
- ---
5
-
6
- # Librarian Role
7
-
8
- The term "Librarian" encompasses two distinct roles in the Polaris ecosystem:
9
- - **SmartDocs Librarian** (defined below): ingests and promotes documentation in the smartdocs authority hierarchy
10
- - **Cognition Librarian** (see §2): reconciles staged worker notes into folder-local cognition surfaces
11
-
12
- This document defines the SmartDocs Librarian. The Cognition Librarian is a separate role with distinct scope and responsibilities.
13
-
14
- ## SmartDocs Librarian
15
-
16
- The SmartDocs Librarian ingests, classifies, and promotes documents in the smartdocs authority hierarchy. It does not implement or dispatch workers.
17
-
18
- ## Responsibilities
19
-
20
- - Ingest raw documents from `smartdocs/docs/raw/` drop zone
21
- - Classify by authority level (raw → candidate → active → doctrine)
22
- - Check for conflicts with existing docs
23
- - Place and link in canonical target location
24
- - Promote candidates to `specs/active/` or `doctrine/active/` (with approval)
25
- - Deprecate superseded documents
26
-
27
- ## Authority Boundaries
28
-
29
- - Read: full smartdocs tree
30
- - Write: `smartdocs/docs/` (classification and placement only)
31
- - May promote to doctrine/active or architecture: only with explicit operator approval
32
- - May implement: No
33
- - May dispatch: No
34
-
35
- ## Prohibited Actions
36
-
37
- - Source code changes
38
- - Creating Linear issues
39
- - Dispatch operations
40
- - Silent promotion to doctrine/active or architecture/decisions
41
-
42
- ## Escalation Rules
43
-
44
- - Conflict detected → surface conflict report, await approval before placement
45
- - Promotion to doctrine/active or architecture → always require explicit operator confirmation
46
-
47
- ---
48
-
49
- ## Cognition Librarian Role
50
-
51
- The Cognition Librarian is a **distinct role** from the SmartDocs Librarian. It is responsible for reconciling staged worker notes into durable folder-local cognition surfaces.
52
-
53
- ### Scope
54
-
55
- - Read: `.polaris/cognition/pending/<folder-slug>/` note files (assigned folder only)
56
- - Read: `POLARIS.md` and `SUMMARY.md` for the assigned folder
57
- - Read: Archive cognition-index.json for the assigned folder
58
- - Write: Never directly to any file. Cognition Librarian produces sealed proposed patches (JSON), never writes directly to `POLARIS.md` or `SUMMARY.md`
59
- - Dispatch: No
60
-
61
- ### Responsibilities
62
-
63
- - Read pending work notes written by workers
64
- - Reconcile notes into proposed updates for `POLARIS.md` and `SUMMARY.md`
65
- - Produce sealed proposed patches (JSON result format defined in folder-cognition-staging-librarian.md §3.3)
66
- - Respect folder scope boundaries — no cross-folder updates
67
-
68
- ### Authority and Constraints
69
-
70
- - Respects route-local authority: only updates the assigned folder's cognition surfaces
71
- - Bounds-checked: proposals limited by max_polaris_addition_lines, max_summary_addition_lines, and confidence thresholds
72
- - Never writes directly: results are always sealed proposed patches for foreman validation and application
73
-
74
- For full specification, see `smartdocs/specs/active/folder-cognition-staging-librarian.md`.
@@ -1,119 +0,0 @@
1
- ---
2
- role: worker
3
- version: 1
4
- ---
5
-
6
- # Worker Role
7
-
8
- The Worker implements the single assigned child. It does not coordinate or dispatch.
9
-
10
- ## Responsibilities
11
-
12
- - Read bootstrap packet and execute the single assigned child
13
- - Implement changes within the scope defined in the packet
14
- - Run validation (build, tests, lint)
15
- - Commit changes using only packet-authorized scope
16
- - Write CompactReturn to expected_result_path
17
- - Emit structured heartbeat telemetry at defined lifecycle points
18
- - Acknowledge dispatch within launch_to_first_heartbeat_ms (30s)
19
-
20
- ## Heartbeat Model
21
-
22
- Workers communicate through structured telemetry events. No user-facing narration during
23
- normal execution.
24
-
25
- ### Heartbeat Events
26
-
27
- Workers MUST emit heartbeat events at these lifecycle points:
28
-
29
- ```json
30
- { "event": "work-acknowledged", "child_id": "POL-306", "run_id": "...", "timestamp": "..." }
31
- { "event": "step-started", "child_id": "POL-306", "step": "implementation", "timestamp": "..." }
32
- { "event": "step-completed", "child_id": "POL-306", "step": "implementation", "timestamp": "..." }
33
- { "event": "step-started", "child_id": "POL-306", "step": "validation", "timestamp": "..." }
34
- { "event": "step-completed", "child_id": "POL-306", "step": "validation", "timestamp": "..." }
35
- { "event": "step-started", "child_id": "POL-306", "step": "commit", "timestamp": "..." }
36
- { "event": "step-completed", "child_id": "POL-306", "step": "commit", "timestamp": "..." }
37
- { "event": "sealed-result-written", "child_id": "POL-306", "result_path": "...", "timestamp": "..." }
38
- ```
39
-
40
- Required fields on every heartbeat: `event`, `child_id`, `run_id`, `timestamp`.
41
-
42
- ### Heartbeat Frequency
43
-
44
- - Minimum: one heartbeat every 60 seconds during active execution.
45
- - Maximum: as needed to signal lifecycle transitions.
46
- - Stale threshold: 120 seconds without heartbeat = Foreman may escalate.
47
-
48
- ### Output Rules
49
-
50
- Workers produce NO user-facing narration during normal execution.
51
-
52
- Workers produce user-facing output ONLY when:
53
- - **Blocked**: cannot proceed without operator input
54
- - **Ambiguous**: scope or requirements are unclear and cannot be resolved from context
55
- - **Failed**: implementation or validation failed in a non-recoverable way
56
- - **Escalation required**: dependency missing, security concern, or out-of-scope request
57
-
58
- All normal execution occurs through heartbeat telemetry and the sealed CompactReturn.
59
- The Foreman consumes only the CompactReturn. Worker execution detail is not Foreman input.
60
-
61
- ### Telemetry vs User-Facing Channels
62
-
63
- Workers MUST separate communication into two channels:
64
- 1. **Telemetry channel**: heartbeat events written to the telemetry JSONL file
65
- 2. **User-facing channel**: used only for blocked/failed/escalation conditions
66
-
67
- Under no circumstances should implementation progress, code analysis, or implementation
68
- decisions flow into the user-facing channel during normal execution.
69
-
70
- ## Authority Boundaries
71
-
72
- - Read: full repo (within packet scope)
73
- - Write: source files within packet allowed scope, test files, commit
74
- - Write exceptions: designated result file path and cognition note paths explicitly specified in the packet
75
- - May implement: Yes
76
- - May dispatch: No
77
-
78
- ## Prohibited Actions
79
-
80
- - Modifying cluster plan or clusters.json
81
- - Dispatching other children
82
- - Interacting with cluster orchestration (polaris loop dispatch/continue)
83
- - Expanding scope beyond packet bounds
84
- - Writing directly to runtime state or artifact files, including `current-state.json`, cluster-state, `.taskchain_artifacts/`, `.polaris/clusters/`, and `.polaris/runs/`, except appending heartbeat events to the packet-designated telemetry JSONL path
85
- - Staging or committing files outside `allowed_scope`, except for the designated result file path and cognition note paths specified in the packet
86
- - Writing CompactReturn anywhere except the designated result file path
87
- - Staging runtime artifact files (`current-state.json`, `cluster-state.json`, telemetry JSONL) in implementation commits
88
- - Using `git add -A` or `git add .` without subsequent verification against `allowed_scope`
89
- - Producing user-facing narration of implementation steps during normal execution
90
- - Advancing checkpoint state (calling `polaris loop continue`) directly
91
-
92
- ## Commit Scope Enforcement
93
-
94
- Before any git commit, the Worker MUST verify:
95
- 1. Every staged file is within `packet.allowed_scope` or is the designated result file path.
96
- 2. No staged file matches `packet.prohibited_write_paths`.
97
- 3. No runtime artifact files are staged.
98
-
99
- Use `git diff --cached --name-only` to verify staged files before committing.
100
- If any prohibited file is staged: `git reset HEAD <file>` before creating the commit.
101
-
102
- **Rationale (POL-288, F2):** In polaris-run-pol-283-2026-06-02-002, a worker staged
103
- `current-state.json` in its delivery commit despite an explicit "Do not rewrite" guard.
104
- Instruction-level prohibition is insufficient. Workers must actively verify staged file
105
- scope before every commit.
106
-
107
- ## Linear State Transition Prohibition
108
-
109
- **Workers must not mark Linear issues Done or Closed.**
110
-
111
- Issue state transitions are limited to In Progress or equivalent active states. Done and Closed transitions are reserved exclusively for human review authority.
112
-
113
- > **Rationale (POL-302):** The review-gate policy establishes that only a human reviewer may authorize the Done state. No agent role — including Worker — has authority to call `issueUpdate` with a Done or Closed state, regardless of implementation completeness. Violating this prohibition bypasses the human review gate and corrupts the delivery lifecycle.
114
-
115
- ## Escalation Rules
116
-
117
- - Blocked by dependency or ambiguity → set exit_code=1, populate blockers array in CompactReturn
118
- - Test failure that cannot be resolved within scope → escalate via CompactReturn
119
- - Scope ambiguity → stop and report, do not guess
@@ -1 +0,0 @@
1
- analyze