@contextrail/assess 1.0.0-alpha.2 → 1.0.0-alpha.3

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.
package/dist/github.js CHANGED
@@ -1200,7 +1200,8 @@ function snapshotInlineOptions(state, c, existingComments) {
1200
1200
  }
1201
1201
  async function inlinePublicationPlan(options, c, state, request) {
1202
1202
  const empty = { comments: [], omitted: 0, duplicates: 0 };
1203
- if (!options.inlineComments)
1203
+ // Startup failures have no assessment snapshot to anchor inline feedback to.
1204
+ if (!options.inlineComments || !Object.keys(state).length)
1204
1205
  return { inline: empty, status: 'disabled', exitCode: 0 };
1205
1206
  let existing = [];
1206
1207
  if (request) {
@@ -71,6 +71,7 @@ export declare const prContextSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
71
71
  disposition: z.ZodEnum<{
72
72
  not_evaluated: "not_evaluated";
73
73
  evaluated: "evaluated";
74
+ observed: "observed";
74
75
  not_applicable: "not_applicable";
75
76
  unresolved: "unresolved";
76
77
  }>;
@@ -194,6 +195,7 @@ export declare const prContextSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
194
195
  disposition: z.ZodEnum<{
195
196
  not_evaluated: "not_evaluated";
196
197
  evaluated: "evaluated";
198
+ observed: "observed";
197
199
  not_applicable: "not_applicable";
198
200
  unresolved: "unresolved";
199
201
  }>;
@@ -3,7 +3,7 @@ import { z } from 'zod';
3
3
  const MAX_PR_CONTEXT_BYTES = 200 * 1024;
4
4
  const sha = z.string().regex(/^[a-f0-9]{40}$/);
5
5
  const text = (max) => z.string().max(max);
6
- const disposition = z.enum(['evaluated', 'unresolved', 'not_applicable', 'not_evaluated']);
6
+ const disposition = z.enum(['evaluated', 'observed', 'unresolved', 'not_applicable', 'not_evaluated']);
7
7
  const finding = z.enum(['none', 'binding_violation', 'behavioral_defect', 'guidance_departure']);
8
8
  const entry = z.strictObject({
9
9
  nodeId: text(500).startsWith('context://'),
@@ -8,7 +8,7 @@ Look up a specific setting here. For a first integration, use [GitHub Actions se
8
8
 
9
9
  | Input | Contract |
10
10
  | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
- | `package-version` | Required exact published npm SemVer. No tags, ranges, URLs, local builds or unavailable-version fallback. |
11
+ | `package-version` | Optional exact npm version override. Omit to install the matching version from the Action release manifest. No npm tags, ranges, URLs or local fallback. |
12
12
  | `pr-number`, `base-branch` | Required PR number; optional expected target branch. |
13
13
  | `reviewer` | Required reusable published `skill://` ID; never an execution or repository ID. |
14
14
  | `mcp-url`, `mcp-org-id` | Required HTTPS endpoint and organization scope, using CLI connection vocabulary. |
@@ -81,5 +81,6 @@ or job timeout can still prevent summary/comment execution. The caller must seri
81
81
  GitHub creation has no atomic compare-and-set; concurrent runs can race after absence checks.
82
82
  The npm package owns presentation and GitHub adapter behavior; the Action invokes it.
83
83
 
84
- After publishing this Action update, adopt its full public commit SHA as well as the intended
85
- exact npm version. Re-running an old workflow retains its old Action code and inputs.
84
+ Select a major release channel, exact release tag or public commit SHA; the Action defaults to its
85
+ matching npm package. See [release selection](github-actions.md#choose-an-update-policy). Floating
86
+ channels can resolve differently on a later run; pin an exact commit to reproduce a prior selection.
@@ -38,9 +38,16 @@ there. The npm package's `files` list also includes docs so installed README lin
38
38
  `release.json` binds the selected version and channel to the upstream commit; the public Action
39
39
  commit is a separate immutable identity.
40
40
 
41
- After successful publication, consumers update both the full Action SHA and exact npm version.
42
- Verify registry availability before dispatching a review. The README badges track npm's
43
- `latest` and `alpha` channels automatically; they do not choose either consumer pin.
41
+ After publication, a separate job with Contents write permission waits for npm metadata and the
42
+ tarball, then advances `v<major>-alpha` or stable `v<major>`. It never moves a channel backward
43
+ when an older release is retried. These are lightweight tags, not GitHub Releases; exact version
44
+ tags remain immutable. Failed or pending publication leaves the channel unchanged.
45
+
46
+ If promotion times out while npm validates the upload, rerun the failed promotion job after the
47
+ package becomes available; do not republish an existing npm version. Publication jobs are serialized.
48
+ Tag rules must permit the intended floating channels while protecting exact release tags.
49
+ Consumers following a channel need no variable update. Exact tag/SHA consumers opt into each upgrade.
50
+ The README badges track npm's `latest` and `alpha` dist-tags, not the Git major channels.
44
51
 
45
52
  See [Action qualification](github-actions.md#qualify-and-operate-a-consumer) for the live
46
53
  integration check and [architecture](architecture.md) before changing the harness.
@@ -13,20 +13,30 @@ Complete [standards setup](standards.md), then add these in **Settings → Secre
13
13
  | -------- | ---------------------------- | ------------------------------------------------------------- |
14
14
  | Variable | `CONTEXTRAIL_MCP_URL` | Your authorized HTTPS MCP endpoint |
15
15
  | Variable | `CONTEXTRAIL_MCP_ORG_ID` | Your organization ID |
16
- | Variable | `ASSESS_VERSION` | An exact published `@contextrail/assess` version |
17
16
  | Variable | `ASSESS_MODEL` | A tool-capable OpenAI model ID available to your account |
18
17
  | Secret | `CONTEXTRAIL_MCP_AUTH_TOKEN` | Token authorized for the selected skill/contexts and feedback |
19
18
  | Secret | `OPENAI_API_KEY` | Your provider key |
20
19
 
21
- Choose a version with `npm view @contextrail/assess dist-tags`. Use the resulting exact version,
22
- not `alpha`, `latest` or a range. The public Action revision and installed npm version are separate
23
- identities: review the Action source and copy its full 40-character commit SHA from
24
- [the public repository](https://github.com/contextrail/assess). Neither identity automatically qualifies the other.
20
+ ## Choose an update policy
21
+
22
+ Use `contextrail/assess/action@v1-alpha` during alpha. After a stable v1 release exists,
23
+ use `@v1` to receive compatible v1 updates. Moving to v2 is a deliberate workflow change.
24
+ Alpha is experimental and does not carry the stable compatibility promise.
25
+
26
+ Each channel advances only after the matching npm package is downloadable. The Action reads
27
+ its release manifest and installs that exact version; there is no separate package variable to maintain.
28
+ For controlled upgrades or rollback, use an exact release tag such as `@v1.0.0-alpha.3`,
29
+ or its full public commit SHA. Exact tags remain protected; floating tags have no GitHub Release attached.
30
+ Only select a release that has actually been published.
31
+
32
+ A channel opts into future releases by the publisher; it is not an immutable source pin.
33
+ A fresh run, including a rerun, can resolve a newer channel revision. Pin the recorded commit
34
+ when reproducing an earlier run. For an independently qualified package override, the low-level
35
+ `package-version` input still accepts an exact version; it is unnecessary for normal use.
25
36
 
26
37
  ## Add the workflow
27
38
 
28
- Save this as `.github/workflows/contextrail-assess.yml`. Replace `ACTION_COMMIT_SHA` and the
29
- reviewer skill ID before committing it. No contribution checkout is needed.
39
+ Save this as `.github/workflows/contextrail-assess.yml`. Replace the reviewer skill ID before committing it. No contribution checkout is needed.
30
40
 
31
41
  ```yaml
32
42
  name: ContextRail Assess
@@ -50,9 +60,8 @@ jobs:
50
60
  pull-requests: write
51
61
  steps:
52
62
  - name: Assess proposed changes
53
- uses: contextrail/assess/action@ACTION_COMMIT_SHA
63
+ uses: contextrail/assess/action@v1-alpha
54
64
  with:
55
- package-version: ${{ vars.ASSESS_VERSION }}
56
65
  pr-number: ${{ inputs.pr-number }}
57
66
  reviewer: skill://engineering/your-reviewer
58
67
  mcp-url: ${{ vars.CONTEXTRAIL_MCP_URL }}
@@ -92,7 +101,9 @@ confirms ingestion only. [Results and next actions](review-results.md) explains
92
101
 
93
102
  Repository variable names belong to your caller workflow. In this example `ASSESS_MODEL` is passed
94
103
  explicitly to the Action; setting it alone in a local shell does not configure the CLI. The maintained
95
- monorepo caller additionally supports `ASSESS_EFFORT`, `ASSESS_VERIFY_MODEL`, `ASSESS_VERIFY_EFFORT`
104
+ monorepo caller uses one `ASSESS_RELEASE` variable (default `v1-alpha`) and records the resolved
105
+ public Action SHA and exact npm version in the summary and a `contextrail-assess-release-*` artifact.
106
+ It also supports `ASSESS_EFFORT`, `ASSESS_VERIFY_MODEL`, `ASSESS_VERIFY_EFFORT`
96
107
  and `ASSESS_ENFORCEMENT`. Standalone CLI aliases use `CONTEXTRAIL_ASSESS_*`.
97
108
 
98
109
  ## Triggers, permissions and trust
@@ -95,8 +95,10 @@ syntax details remain unknown rather than being inferred from a generic exceptio
95
95
  Start with the Action summary's terminal failure, then open `diagnostics.jsonl` in the
96
96
  artifact. Correlate events by run ID, phase, attempt and call. The summary links the stop
97
97
  reason to the last failing provider request in that phase; a recovered earlier error is
98
- not the final cause. Updated summary behavior requires the new Action SHA as well as the
99
- new npm package; changing `ASSESS_VERSION` alone does not update Action scripts.
98
+ not the final cause. Use the release identity in the summary to confirm which Action and package ran. The monorepo
99
+ retains `assess-release.json` in its release artifact. `ASSESS_RELEASE` selects both identities;
100
+ a floating channel advances after publication. For rollback, select the recorded public commit
101
+ SHA or exact release tag, then start a fresh dispatch.
100
102
 
101
103
  At `info`, phase boundaries, provider request start/completion, assessment progress,
102
104
  recovery, reporting and final outcome appear on stderr. `debug` also shows tool activity,
@@ -21,7 +21,7 @@ jobs:
21
21
  runs-on: ubuntu-latest
22
22
  timeout-minutes: 30
23
23
  env:
24
- ASSESS_PACKAGE_VERSION: '1.0.0-alpha.2'
24
+ ASSESS_PACKAGE_VERSION: '1.0.0-alpha.3'
25
25
  REVIEWER_ID: skill://your-domain/your-reviewer
26
26
  ASSESS_PROVIDER: openai
27
27
  ASSESS_MODEL: REPLACE_WITH_PROVIDER_MODEL_ID
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@contextrail/assess",
3
- "version": "1.0.0-alpha.2",
3
+ "version": "1.0.0-alpha.3",
4
4
  "description": "Assess proposed Git changes against published organizational standards, with per-standard outcomes and retained evidence.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",